This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Managing Users and Roles with APIs

This section guides you through invoking and working with the RemoteUserStoreManagerService and the operations you can work with in this service.

Invoking the admin service

RemoteUserStoreManagerService is an admin service of the WSO2 Carbon platform. As admin services are secured to prevent anonymous invocations, you cannot view the WSDL of the admin service by default. Follow the steps below to view and invoke it:

  1. Set the <HideAdminServiceWSDLs> element to false in <IS_HOME>/repository/conf/carbon.xml file.

    <HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>
  2. Restart the Identity Server.
  3. If you have started the server in default configurations, use the following URL in your browser to see the WSDL of the admin service: https://localhost:9443/services/RemoteUserStoreManagerService?wsdl.

For more information on WSO2 admin services and how to invoke an admin service using either SoapUI or any other client program, see Calling Admin Services from Apps section in WSO2 Carbon documentation.

Working with the API

The Identity Server enables you to manage users and roles in your system with its open web services API - so, any third party application can consume this API to handle authentication and authorization with WSO2 Identity Server.

The code sample that comes with this topic illustrates the following tasks.

  1. Authenticates a user.
  2. Creates a new role.
  3. Creates a user and adds the user to a new role.
  4. Adds a value to a predefined custom attribute under the user profile.
  5. Checks whether a given user belongs to a given role.

You can download the complete Eclipse project for the sample from here. Unzip the attached zipped file and import it to Eclipse. You need to have following in your class path.

  • axiom_1.2.11.wso2v9.jar
  • axis2_1.6.1.wso2v16.jar
  • commons-codec_1.4.0.wso2v1.jar
  • commons-fileupload_1.2.2.wso2v1.jar
  • commons-httpclient_3.1.0.wso2v2.jar
  • httpcore_4.3.3.wso2v1.jar
  • neethi_2.0.4.wso2v5.jar
  • org.wso2.carbon.authenticator.proxy_4.4.3.jar
  • org.wso2.carbon.logging_4.4.3.jar
  • org.wso2.carbon.um.ws.api_5.0.7.jar
  • org.wso2.carbon.user.core_4.4.3.jar
  • org.wso2.carbon.user.api_4.4.3.jar
  • wsdl4j_1.6.2.wso2v4.jar
  • XmlSchema_1.4.7.wso2v3.jar

You can find all these .jar files inside the <IS_HOME>\repository\components\plugins directory. The following is a sample of how your API may look.

package org.wso2.identity.um.sample;  
  
import java.util.HashMap;  
import java.util.Map;  
  
import org.apache.axis2.context.ConfigurationContext;  
import org.apache.axis2.context.ConfigurationContextFactory;  
import org.apache.axis2.transport.http.HTTPConstants;  
#import org.wso2.carbon.authenticator.proxy.AuthenticationAdminStub;  
import org.wso2.carbon.authenticator.stub.AuthenticationAdminStub
import org.wso2.carbon.um.ws.api.WSRealmBuilder;  
import org.wso2.carbon.user.core.UserRealm;  
import org.wso2.carbon.user.core.UserStoreManager;  
  
public class IdentityServerClient {  
  
 // ONE TIME TASKS WE NEED TO DO BEFORE EXECUTING THIS PROGRAM.  
  
 // TASK - 1 , CREATE a LoginOnly role from IS UI Console  
 // ===========================================================  
 // 0. Login as admin/admin  
 // 1. Go to Users and Roles  
 // 2. Click on Roles  
 // 3. Add New Role  
 // 4. Role Name : loginOnly [please use this name, since it's referred within the code below]  
 // 5. Click Next  
 // 6. Select only the 'Login' permission  
 // 7. Click Next  
 // 8. No need to select any users  
 // 9. Click Finish  
  
 // TASK - 2 , CREATE a custom claim from IS UI Console  
 // ===========================================================  
 // 0. Login as admin/admin  
 // 1. Go to Claim Management  
 // 2. Click on http://wso2.org/claims  
 // 3. Click on 'Add New Claim Mapping'  
 // 3.1 Display Name : Business Phone  
 // 3.2 Description : Business Phone  
 // 3.3 Claim Uri : http://wso2.org/claims/businessphone  
 // 3.4 Mapped Attribute : http://wso2.org/claims/businessphone  
 // 3.5 Support by default : Checked  
 // 3.6 The rest can be kept blank  
  
 private final static String SERVER_URL = "https://localhost:9443/services/";  
 private final static String APP_ID = "myapp";  
  
 /** 
  * @param args 
  */  
 public static void main(String[] args) {  
  
  AuthenticationAdminStub authstub = null;  
  ConfigurationContext configContext = null;  
  String cookie = null;  
  String newUser = "prabath2";  
  
  System.setProperty("javax.net.ssl.trustStore", "wso2carbon.jks");  
  System.setProperty("javax.net.ssl.trustStorePassword", "wso2carbon");  
  
  try {  
   configContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(  
     "repo", "repo/conf/client.axis2.xml");  
   authstub = new AuthenticationAdminStub(configContext, SERVER_URL  
     + "AuthenticationAdmin");  
  
   // Authenticates as a user having rights to add users.  
   if (authstub.login("admin", "admin", null)) {  
    cookie = (String) authstub._getServiceClient().getServiceContext().getProperty(  
      HTTPConstants.COOKIE_STRING);  
  
    UserRealm realm = WSRealmBuilder.createWSRealm(SERVER_URL, cookie, configContext);  
    UserStoreManager storeManager = realm.getUserStoreManager();  
  
    // Add a new role - with no users - with APP_ID as the role name  
  
    if (!storeManager.isExistingRole(APP_ID)) {  
  
     storeManager.addRole(APP_ID, null, null);  
     System.out.println("The role added successfully to the system");  
    } else {  
     System.out.println("The role trying to add - already there in the system");  
    }  
  
    if (!storeManager.isExistingUser(newUser)) {  
     // Let's the this user to APP_ID role we just created.  
  
     // First let's create claims for users.  
     // If you are using a claim that does not exist in default IS instance,  
     Map<string, string=""> claims = new HashMap<string, string="">();  
  
     // TASK-1 and TASK-2 should be completed by now.  
     // Here I am using an already existing claim  
     claims.put("http://wso2.org/claims/businessphone", "0112842302");  
  
     // Here we pass null for the profile - so it will use the default profile.  
     storeManager.addUser(newUser, "password", new String[] { APP_ID, "loginOnly" },  
       claims, null);  
     System.out.println("The use added successfully to the system");  
    } else {  
     System.out.println("The user trying to add - already there in the system");  
    }  
  
    // Now let's see the given user [newUser] belongs to the role APP_ID.  
    String[] userRoles = storeManager.getRoleListOfUser(newUser);  
    boolean found = false;  
  
    if (userRoles != null) {  
     for (int i = 0; i < userRoles.length; i++) {  
      if (APP_ID.equals(userRoles[i])) {  
       found = true;  
       System.out.println("The user is in the required role");  
       break;  
      }  
     }  
    }  
      
    if (!found){  
     System.out.println("The user is NOT in the required role");  
    }  
   }  
  } catch (Exception e) {  
   e.printStackTrace();  
  }  
 }  
}  
  
</string,></string,>  

Operations included in the API

The following operations are available in the RemoteUserStoreManagerService

For the methods that have profile name as an input parameter, you can also pass null for the parameter in which case the default profile will then be considered instead.

authenticate()
Methodauthenticate
DescriptionAuthenticate users against the user store
Input Parameters
ParameterTypeDescription
UsernamestringProvide the relevant user's username
CredentialstringProvide the relevant user's password
Output ParametersA boolean parameter indicating if the user has been authenticated or not
isReadOnly()
MethodisReadOnly
DescriptionCheck whether the user store is read-only
Input Parameters

None

Output ParametersA boolean parameter indicating if the user store is read-only or not
getUserClaimValue()
MethodgetUserClaimValue
DescriptionRetrieve the value of the user property from the user profile
Input Parameters
ParameterTypeDescription
UsernameStringUsername
ClaimStringName of the claim
Profile NameStringName of the user profile
Output ParametersValue of the claim as a string
getUserList()
MethodgetUserList
DescriptionRetrieve a list of all users
Input Parameters
ParameterTypeDescription
Claim URIStringThe Claim URI of the claim
Claim ValueStringThe value of the claim
Profile NameStringName of the user profile that the claim value should be used with
Output ParametersList of users with the specified claim.
getUserListOfRole()
MethodgetUserListOfRole
DescriptionRetrieve a list of all users belonging to a role
Input Parameters
ParameterTypeDescription
Role NameStringName of the role
Output ParametersList of usernames as a string array

Note: This operation retrieves a list of all the users. The users assigned to the specified role will be indicated in the list. Users belonging to the role are shown as selected = true and users not belonging to the role are show as selected = false.

updateCredential()
MethodupdateCredential
DescriptionThis operation can be used by the user itself to update his/her own password
Input Parameters
ParameterTypeDescription
UsernameStringUsername
New CredentialStringThe new password
Old CredentialStringThe old password
Output ParametersNone
getUserClaimValuesForClaims()
MethodgetUserClaimValuesForClaims
DescriptionRetrieve the claim values of a user when given a set of claims and a user profile
Input Parameters
ParameterTypeDescription
UsernameStringUsername
Set of ClaimsStringName of the claim
Profile NameStringName of the user profile
Output ParametersArray of objects of type ClaimValue which contains the claim mapping between claim URI and claim value
setUserClaimValue()
MethodsetUserClaimValue
DescriptionUpdate the user claim value in a user profile
Input Parameters
ParameterTypeDescription
UsernameStringUsername
Profile NameStringName of the user profile
Claim URIStringThe claim URI of the claim
Claim ValueStringThe claim value
Output ParametersNone
deleteUserClaimValue()
MethoddeleteUserClaimValue
DescriptionDelete a single user claim value
Input Parameters
ParameterTypeDescription
UsernameStringUsername
Profile NameStringName of the user profile
Claim URIStringThe claim URI of the claim
Output ParametersNone
isExistingUser()
MethodisExistingUser
DescriptionCheck whether a given user name exists in the system
Input Parameters
ParameterTypeDescription
UsernameStringUsername
Output ParametersA Boolean parameter indicating whether the user exists or not
deleteUserClaimValues()
MethoddeleteUserClaimValues
DescriptionDelete many user claim values
Input Parameters
ParameterTypeDescription
UsernameStringUsername
Profile NameStringName of the user profile
ClaimsString ArrayThe claims to be deleted
Output ParametersNone
updateCredentialByAdmin()
MethodupdateCredentialByAdmin
DescriptionThis operation can be used by the admin to update a user's password
Input Parameters
ParameterTypeDescription
UsernameStringUsername
New CredentialStringThe new password
Output ParametersNone
getRoleNames()
MethodgetRoleNames
DescriptionGet a list of all the roles created in the system
Input Parameters

None

Output ParametersA string array of all the role names
getAllProfileNames()
MethodgetAllProfileNames
DescriptionGet a list of all the profile names created in the system
Input Parameters

None

Output ParametersA string array of all the profile names
listUsers()
MethodlistUsers
DescriptionRetrieves a list of user names up to a particular maximum limit
Input Parameters
ParameterTypeDescription
FilterStringA filter to filter out any users
Max Item LimitInteger

The max limit to the number of users returned in the list

  • If the value given is below 0, it will be disregarded and the system configured limit will be taken instead.
  • If the value given is greater than the system configured limit, it will be disregarded and the system configured limit will be taken instead.
Output ParametersA filtered string array of all the user names
deleteRole()
MethoddeleteRole
DescriptionDelete a given role name
Input Parameters
ParameterTypeDescription
Role NameStringName of the role
Output ParametersNone
deleteUser()
MethoddeleteUser
DescriptionDelete a user
Input Parameters
ParameterTypeDescription
UsernameStringUsername of the user
Output ParametersNone
getRoleListOfUser()
MethodgetRoleListOfUser
DescriptionGet the list of roles that a particular user belongs to
Input Parameters
ParameterTypeDescription
UsernameStringUsername of the user
Output ParametersA string array of the role names
updateRoleName()
MethodupdateRoleName
DescriptionChange the name of a particular role
Input Parameters
ParameterTypeDescription
Role NameStringExisting name of the role
New Role NameStringNew name for the role
Output ParametersNone
isExistingRole()
MethodisExistingRole
DescriptionCheck whether a given role exists
Input Parameters
ParameterTypeDescription
Role NameStringName of the role
Output ParametersA Boolean parameter indicating whether the role exists or not
updateRoleListOfUser()
MethodupdateRoleListOfUser
DescriptionChange the list of roles that a user belongs to
Input Parameters
ParameterTypeDescription
UsernameStringUsername of User
Deleted RolesString ArrayList of roles that are to be removed
New RolesString ArrayList of roles that are to be added
Output ParametersNone
getHybridRoles()
MethodgetHybridRoles
DescriptionGet the list of roles stored in the internal UserMgt database irrespective of the user store
Input Parameters

None

Output ParametersA string array of all the roles
getUserClaimValues()
MethodgetUserClaimValues
DescriptionGet a list of all claim information for a given user name and profile name
Input Parameters
ParameterTypeDescription
UsernameStringUsername of User
Profile NameStringName of the profile
Output ParametersArray of objects of type 'claim' which includes all the information of the claims
addUser()
MethodaddUser
DescriptionAdd a user to the user store
Input Parameters
ParameterTypeDescription
UsernameStringUsername of the new user
CredentialStringPassword for the new user
Role ListString ArrayList of roles that the user should be assigned to
ClaimsObjects ArrayProperties of the user (claim mapping) as a mapping 
Profile NameStringName of the profile
Output ParametersNone
addRole()
MethodaddRole
DescriptionAdd a role to the system
Input Parameters
ParameterTypeDescription
Role NameStringName of the new role
User ListStringList of users to be included in the role
PermissionsPermission Objects ArrayPermissions to be assigned to the role 
Output ParametersNone
updateUserListOfRole()
MethodupdateUserListOfRole
DescriptionAdd/remove users that belong to a particular role
Input Parameters
ParameterTypeDescription
Role NameStringName of the new role
Deleted UsersString ArrayList of users to be deleted from the role
New UsersString ArrayList of users to be added to the role
Output ParametersNone
setUserClaimValues()
MethodsetUserClaimValues
DescriptionUpdate the claim values of a given user
Input Parameters
ParameterTypeDescription
UsernameStringUsername
ClaimsString ArrayMap of claim URIs and values
Profile NameStringName of the profile
Output ParametersNone
getTenantIdOfUser()
Method

getTenantIdOfUser

DescriptionGet the tenant ID of the tenant that a particular user belongs to
Input Parameters
ParameterTypeDescription
UsernameStringUsername
Output ParametersThe Tenant ID as an integer
getProfileNames()
Method

getProfileNames

DescriptionGet all profile names of a user
Input Parameters
ParameterTypeDescription
UsernameStringUsername
Output ParametersThe profile names as a string array