Managing Users and Roles with APIs

Warning

From 5.4.0 onwards, SCIM 2.0 REST APIs are supported out-of-the-box with WSO2 Identity Server and is recommended for user store management. For more information on using the SCIM 2.0 REST APIs instead of the SOAP service given below, see Using the SCIM 2.0 REST 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 bellow configuration in <IS_HOME>/repository/conf/deployment.toml file.

    [admin_service.wsdl]
enable = true

  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.

Operations included in the API and sample requests

The following operations are available in the RemoteUserStoreManagerService.

Note

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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:authenticate>
         <!--Optional:-->
         <ser:userName>nilasini</ser:userName>
         <!--Optional:-->
         <ser:credential>admin</ser:credential>
      </ser:authenticate>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:isReadOnly/>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getUserClaimValue>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Optional:-->
         <ser:claim>http://wso2.org/claims/lastname</ser:claim>
         <!--Optional:-->
         <ser:profileName>?</ser:profileName>
      </ser:getUserClaimValue>
   </soapenv:Body>
</soapenv:Envelope>
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. 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getUserList>
         <!--Optional:-->
         <ser:claimUri>http://wso2.org/claims/country</ser:claimUri>
         <!--Optional:-->
         <ser:claimValue>srilanka</ser:claimValue>
         <!--Optional:-->
         <ser:profile>default</ser:profile>
      </ser:getUserList>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getUserListOfRole>
         <!--Optional:-->
         <ser:roleName>Engineer</ser:roleName>
      </ser:getUserListOfRole>
   </soapenv:Body>
</soapenv:Envelope>

Note

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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:updateCredential>
         <!--Optional:-->
         <ser:userName>[email protected] </ser:userName>
         <!--Optional:-->
         <ser:newCredential>admin</ser:newCredential>
         <!--Optional:-->
         <ser:oldCredential>nilasini</ser:oldCredential>
      </ser:updateCredential>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getUserClaimValuesForClaims>
         <!--Optional:-->
         <ser:userName>[email protected] </ser:userName>
         <!--Zero or more repetitions:-->
         <ser:claims>country</ser:claims>
         <!--Optional:-->
         <ser:profileName>[email protected] </ser:profileName>
      </ser:getUserClaimValuesForClaims>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:setUserClaimValue>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Optional:-->
         <ser:claimURI>http://wso2.org/claims/lastname</ser:claimURI>
         <!--Optional:-->
         <ser:claimValue>thiru</ser:claimValue>
         <!--Optional:-->
         <ser:profileName>[email protected]</ser:profileName>
      </ser:setUserClaimValue>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:deleteUserClaimValue>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Optional:-->
         <ser:claimURI>http://wso2.org/claims/lastname</ser:claimURI>
         <!--Optional:-->
         <ser:profileName>[email protected]</ser:profileName>
      </ser:deleteUserClaimValue>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:isExistingUser>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
      </ser:isExistingUser>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:deleteUserClaimValues>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Zero or more repetitions:-->
         <ser:claims>http://wso2.org/claims/organization</ser:claims>
         <ser:claims>http://wso2.org/claims/country</ser:claims>
         <!--Optional:-->
         <ser:profileName>default</ser:profileName>
      </ser:deleteUserClaimValues>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:updateCredentialByAdmin>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Optional:-->
         <ser:newCredential>admin</ser:newCredential>
      </ser:updateCredentialByAdmin>
   </soap:Body>
</soap:Envelope>
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 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:getRoleNames/>
   </soap:Body>
</soap:Envelope>
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 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:getAllProfileNames/>
   </soap:Body>
</soap:Envelope>
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 Integer

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 Parameters A filtered string array of all the user names 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:listUsers>
         <!--Optional:-->
         <ser:filter>*@wso2support.com</ser:filter>
         <!--Optional:-->
         <ser:maxItemLimit>10</ser:maxItemLimit>
      </ser:listUsers>
   </soap:Body>
</soap:Envelope>
deleteRole()
Method deleteRole
Description Delete a given role name
Input Parameters
Parameter Type Description
Role Name String Name of the role
Output Parameters None 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:deleteRole>
         <!--Optional:-->
         <ser:roleName>Engineer</ser:roleName>
      </ser:deleteRole>
   </soap:Body>
</soap:Envelope>
deleteUser()
Method deleteUser
Description Delete a user
Input Parameters
Parameter Type Description
Username String Username of the user
Output Parameters None 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:deleteUser>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
      </ser:deleteUser>
   </soap:Body>
</soap:Envelope>
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 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:getRoleListOfUser>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
      </ser:getRoleListOfUser>
   </soap:Body>
</soap:Envelope>
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 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:updateRoleName>
         <!--Optional:-->
         <ser:roleName>Doctor</ser:roleName>
         <!--Optional:-->
         <ser:newRoleName>Teacher</ser:newRoleName>
      </ser:updateRoleName>
   </soap:Body>
</soap:Envelope>
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 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:isExistingRole>
         <!--Optional:-->
         <ser:roleName>Teacher</ser:roleName>
      </ser:isExistingRole>
   </soap:Body>
</soap:Envelope>
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 
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:updateRoleListOfUser>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Zero or more repetitions:-->
         <ser:deletedRoles>Teacher</ser:deletedRoles>
         <ser:deletedRoles>lecturer</ser:deletedRoles>
         <!--Zero or more repetitions:-->
         <ser:newRoles>doctor</ser:newRoles>
         <ser:newRoles>carpenter</ser:newRoles>
      </ser:updateRoleListOfUser>
   </soap:Body>
</soap:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getHybridRoles/>
   </soapenv:Body>
</soapenv:Envelope>
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 
soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soap:Header/>
   <soap:Body>
      <ser:getUserClaimValues>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Optional:-->
         <ser:profileName>default</ser:profileName>
      </ser:getUserClaimValues>
   </soap:Body>
</soap:Envelope>
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 Claims Objects Array Properties of the user (claim mapping) as a mapping
Profile Name String Name of the profile
Output Parameters None 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org" xmlns:xsd="http://common.mgt.user.carbon.wso2.org/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:addUser>
         <!--Optional:-->
         <ser:userName>nilasini</ser:userName>
         <!--Optional:-->
         <ser:credential>admin</ser:credential>
         <!--Zero or more repetitions:-->
         <ser:roleList>teacher</ser:roleList>
         <ser:roleList>Doctor</ser:roleList>
         <!--Zero or more repetitions:-->
         <ser:claims>
            <!--Optional:-->
            <xsd:claimURI>http://wso2.org/claims/country</xsd:claimURI>
            <!--Optional:-->
            <xsd:value>England</xsd:value>
         </ser:claims>
         <ser:claims>
            <!--Optional:-->
            <xsd:claimURI>http://wso2.org/claims/organization</xsd:claimURI>
            <!--Optional:-->
            <xsd:value>Intuit</xsd:value>
         </ser:claims>
         <!--Optional:-->
         <ser:profileName>default</ser:profileName>
         <!--Optional:-->
         <ser:requirePasswordChange>false</ser:requirePasswordChange>
      </ser:addUser>
   </soapenv:Body>
</soapenv:Envelope>
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 to the role
Permissions Permission Objects Array Permissions to be assigned to the role
Output Parameters None 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org" xmlns:xsd="http://dao.service.ws.um.carbon.wso2.org/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:addRole>
         <!--Optional:-->
         <ser:roleName>hrManager</ser:roleName>
         <!--Zero or more repetitions:-->
         <ser:userList>[email protected]</ser:userList>
         <ser:userList>venilope</ser:userList>
         <ser:userList>[email protected]</ser:userList>
         <!--Zero or more repetitions:-->
         <ser:permissions>
            <!--Optional:-->
            <xsd:action>ui.execute</xsd:action>
            <!--Optional:-->
            <xsd:resourceId>/permission/admin/manage/identity</xsd:resourceId>
         </ser:permissions>
      </ser:addRole>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:updateRoleListOfUser>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Zero or more repetitions:-->
         <ser:deletedRoles>teacher</ser:deletedRoles>
         <ser:deletedRoles>Doctor</ser:deletedRoles>
         <!--Zero or more repetitions:-->
         <ser:newRoles>lecturer</ser:newRoles>
         <ser:newRoles>carpenter</ser:newRoles>
      </ser:updateRoleListOfUser>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org" xmlns:xsd="http://common.mgt.user.carbon.wso2.org/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:setUserClaimValues>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
         <!--Zero or more repetitions:-->
         <ser:claims>
            <!--Optional:-->
            <xsd:claimURI>http://wso2.org/claims/organization</xsd:claimURI>
            <!--Optional:-->
            <xsd:value>wso2</xsd:value>
         </ser:claims>
         <ser:claims>
            <!--Optional:-->
            <xsd:claimURI>http://wso2.org/claims/country</xsd:claimURI>
            <!--Optional:-->
            <xsd:value>srilanka</xsd:value>
         </ser:claims>
         <!--Optional:-->
         <ser:profileName>default</ser:profileName>
      </ser:setUserClaimValues>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getTenantIdofUser>
         <!--Optional:-->
         <ser:username>[email protected]</ser:username>
      </ser:getTenantIdofUser>
   </soapenv:Body>
</soapenv:Envelope>
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 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.um.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getProfileNames>
         <!--Optional:-->
         <ser:userName>[email protected]</ser:userName>
      </ser:getProfileNames>
   </soapenv:Body>
</soapenv:Envelope>
Top