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:
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 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.
- 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.
- 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
- 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
- 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:
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 that the claim value should be used with |
|
---|
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 |
---|
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 up to a particular maximum limit |
---|
Input Parameters | Parameter | Type | Description |
---|
Filter | String | A filter to filter out any users | Max Item Limit | Integer | The max limit to the number of users returned in the list |
|
---|
Output Parameters | A filtered string array of all the user names |
---|
deleteRole()
Method | deleteRole |
---|
Description | Delete a given role name |
---|
Input Parameters | Parameter | Type | Description |
---|
Role Name | String | Name of the role |
|
---|
Output Parameters | None |
---|
deleteUser()
Method | deleteUser |
---|
Description | Delete a user |
---|
Input Parameters | Parameter | Type | Description |
---|
Username | String | Username of the user |
|
---|
Output Parameters | None |
---|
getRoleListOfUser()
Method | getRoleListOfUser |
---|
Description | Get the list of roles that a particular user belongs to |
---|
Input Parameters | Parameter | Type | Description |
---|
Username | String | Username of the user |
|
---|
Output Parameters | A string array of the role names |
---|
updateRoleName()
Method | updateRoleName |
---|
Description | Change the name of a particular role |
---|
Input Parameters | Parameter | Type | Description |
---|
Role Name | String | Existing name of the role | New Role Name | String | New name for the role |
|
---|
Output Parameters | None |
---|
isExistingRole()
Method | isExistingRole |
---|
Description | Check whether a given role exists |
---|
Input Parameters | Parameter | Type | Description |
---|
Role Name | String | Name of the role |
|
---|
Output Parameters | A Boolean parameter indicating whether the role exists or not |
---|
updateRoleListOfUser()
Method | updateRoleListOfUser |
---|
Description | Change the list of roles that a user belongs to |
---|
Input Parameters | Parameter | Type | Description |
---|
Username | String | Username of User | Deleted Roles | String Array | List of roles that are to be removed | New Roles | String Array | List of roles that are to be added |
|
---|
Output Parameters | None |
---|
getHybridRoles()
Method | getHybridRoles |
---|
Description | Get the list of roles stored in the internal UserMgt database irrespective of the user store |
---|
Input Parameters | None |
---|
Output Parameters | A string array of all the roles |
---|
getUserClaimValues()
Method | getUserClaimValues |
---|
Description | Get a list of all claim information for a given user name and profile name |
---|
Input Parameters | Parameter | Type | Description |
---|
Username | String | Username of User | Profile Name | String | Name of the profile |
|
---|
Output Parameters | Array of objects of type 'claim' which includes all the information of the claims |
---|
addUser()
Method | addUser |
---|
Description | Add a user to the user store |
---|
Input Parameters | Parameter | Type | Description |
---|
Username | String | Username of the new user | Credential | String | Password for the new user | Role List | String Array | List of roles that the user should be assigned to | Claims | Objects Array | Properties of the user (claim mapping) as a mapping | Profile Name | String | Name of the profile |
|
---|
Output Parameters | None |
---|
addRole()
Method | addRole |
---|
Description | Add a role to the system |
---|
Input Parameters | Parameter | Type | Description |
---|
Role Name | String | Name of the new role | User List | String | List of users to be included in the role | Permissions | Permission Objects Array | Permissions to be assigned to the role |
|
---|
Output Parameters | None |
---|
updateUserListOfRole()
Method | updateUserListOfRole |
---|
Description | Add/remove users that belong to a particular role |
---|
Input Parameters | Parameter | Type | Description |
---|
Role Name | String | Name of the new role | Deleted Users | String Array | List of users to be deleted from the role | New Users | String Array | List of users to be added to the role |
|
---|
Output Parameters | None |
---|
setUserClaimValues()
Method | setUserClaimValues |
---|
Description | Update the claim values of a given user |
---|
Input Parameters | Parameter | Type | Description |
---|
Username | String | Username | Claims | String Array | Map of claim URIs and values | Profile Name | String | Name of the profile |
|
---|
Output Parameters | None |
---|
getTenantIdOfUser()
Method | getTenantIdOfUser |
---|
Description | Get the tenant ID of the tenant that a particular user belongs to |
---|
Input Parameters | Parameter | Type | Description |
---|
Username | String | Username |
|
---|
Output Parameters | The Tenant ID as an integer |
---|
getProfileNames()
Method | getProfileNames |
---|
Description | Get all profile names of a user |
---|
Input Parameters | Parameter | Type | Description |
---|
Username | String | Username |
|
---|
Output Parameters | The profile names as a string array |
---|