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.

1 Invoking the admin service
2 Working with the API
3 Operations included in the API

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:

Set the <HideAdminServiceWSDLs> element to false in <IS_HOME>/repository/conf/carbon.xml file.
<HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>
Restart the Identity Server.
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 it's 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.

Authenticates a user.
Creates a new role.
Creates a user and adds the user to a new role.
Adds a value to a predefined custom attribute under the user profile.
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.9.wso2v1.jar

axis2-1.6.0.wso2v1.jar

commons-codec-1.3.0.wso2v1.jar

commons-fileupload-1.2.0.wso2v1.jar

commons-httpclient-3.1.0.wso2v1.jar

httpcore-4.1.0.alpha1-wso2v1.jar

neethi-2.0.4.wso2v1.jar

org.wso2.carbon.authenticator.proxy-3.0.0.jar

org.wso2.carbon.logging-3.0.0.jar

org.wso2.carbon.um.ws.api-3.0.0.jar

org.wso2.carbon.user.core-3.0.0.jar

wsdl4j-1.6.2.wso2v1.jar

XmlSchema-1.4.6.wso2v1.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.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()

Method

authenticate

Description

Authenticate users against the user store

Input Parameters

Parameter	Type	Description
Username	string	Provide the relevant user's username
Credential	string	Provide the relevant user's password

Output Parameters

A boolean parameter indicating if the user has been authenticated or not

isReadOnly()

Method	isReadOnly
Description	Check whether the user store is read only
Input Parameters	None
Output Parameters	A boolean parameter indicating if the user store is read only or not

getUserClaimValue()

Method

getUserClaimValue

Description

Retrieve the value of the user property from the user profile

Input Parameters

Parameter	Type	Description
Username	String	Username
Claim	String	Name of the claim
Profile Name	String	Name of the user profile

Output Parameters

Value of the claim as a string

getUserList()

Method

getUserList

Description

Retrieve a list of all users

Input Parameters

Parameter	Type	Description
Claim URI	String	The Claim URI of the claim
Claim Value	String	The value of the claim
Profile Name	String	Name of the user profile

Output Parameters

List of users with the specified claim.

getUserListOfRole()

Method

getUserListOfRole

Description

Retrieve a list of all users belonging to a role

Input Parameters

Parameter	Type	Description
Role Name	String	Name of the role

Output Parameters

List 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()

Method

updateCredential

Description

This operation can be used by the user itself to update his/her own password

Input Parameters

Parameter	Type	Description
Username	String	Username
New Credential	String	The new password
Old Credential	String	The old password

Output Parameters

None

getUserClaimValuesForClaims()

Method

getUserClaimValuesForClaims

Description

Retrieve the claim values of a user when given a set of claims and a user profile

Input Parameters

Parameter	Type	Description
Username	String	Username
Set of Claims	String	Name of the claim
Profile Name	String	Name of the user profile

Output Parameters

Array of objects of type ClaimValue which contains the claim mapping between claim URI and claim value

setUserClaimValue()

Method

setUserClaimValue

Description

Update the user claim value in a user profile

Input Parameters

Parameter	Type	Description
Username	String	Username
Profile Name	String	Name of the user profile
Claim URI	String	The claim URI of the claim
Claim Value	String	The claim value

Output Parameters

None

deleteUserClaimValue()

Method

deleteUserClaimValue

Description

Delete a single user claim value

Input Parameters

Parameter	Type	Description
Username	String	Username
Profile Name	String	Name of the user profile
Claim URI	String	The claim URI of the claim

Output Parameters

None

isExistingUser()

Method

isExistingUser

Description

Check whether a given user name exists in the system

Input Parameters

Parameter	Type	Description
Username	String	Username

Output Parameters

A Boolean parameter indicating whether the user exists or not

deleteUserClaimValues()

Method

deleteUserClaimValues

Description

Delete many user claim values

Input Parameters

Parameter	Type	Description
Username	String	Username
Profile Name	String	Name of the user profile
Claims	String Array	The claims to be deleted

Output Parameters

None

updateCredentialByAdmin()

Method

updateCredentialByAdmin

Description

This operation can be used by the admin to update a user's password

Input Parameters

Parameter	Type	Description
Username	String	Username
New Credential	String	The new password

Output Parameters

None

getRoleNames()

Method	getRoleNames
Description	Get a list of all the roles created in the system
Input Parameters	None
Output Parameters	A string array of all the role names

getAllProfileNames()

Method	getAllProfileNames
Description	Get a list of all the profile names created in the system
Input Parameters	None
Output Parameters	A string array of all the profile names

listUsers()

Method

listUsers

Description

Retrieves a list of user names upto a particular maximum limit

Input Parameters

Parameter	Type	Description
Filter	String	A filter to filter out any users
Max Item Limit