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

Managing Users and Roles with APIs

WSO2 Identity Server provides a Web service API by the name called RemoteUserStoreManagerService for user role management. If your application needs a user role management function, you can directly integrate with Identity Server instead of dealing with the user store. The WSDL of this service is https://localhost:9443/services/RemoteUserStoreManagerService?wsdl and you can find its operations by going through the WSDL.

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 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.

  1. Authenticates a user
  2. Creates a new role
  3. Creates a user and add 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.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,>