This topic describes some of the basic use cases that you can accomplish using Identity Applications REST API.
Identity Applications provide a complete API accessible via HTTP/HTTPS. See the REST API documentation for detailed information about the available endpoints. This information will also help you to make the API calls described in this topic.
The following use case describe some of the basic operations that can be performed by using Identity Applications REST APIs:
Roles are a key component in role-based provisioning and role-based access control. A role represents a set of permissions that allows a user to perform defined activities. A role can be mapped to one or more roles, resources, and entitlements from different connected systems. You can assign any role to any user in your organization.
The following examples describe some of the basic role management operations. The role and resource administration user interface of Identity Applications leverages the same APIs to accomplish the role management tasks.
Access Rights Needed: Role Administrator or Role Manager
Build roles depending on your organization’s needs to efficiently provision users with the resources that they need access to, such as a software application or a security access card.
A role is created with a specific role level. You can associate a role with other roles, map it with organizational resources, and assign it to users, groups, or containers. Use the following example endpoint to create a role named PhysicsProfessor1.
Request URL: https://IP:port:8543/IDMProv/rest/catalog/roles
Request Method: POST
Sample Request Payload: {"id": "PhysicsProfessor1", "name": "PhysicsProfessor1", "localizedNames": [{"locale": "en", "name": "PhysicsProfessor1" }], "description": "PhysicsProfessor1", "localizedDescriptions": [{"locale": "en", "desc": "PhysicsProfessor1"}], "categories": [], "owners": [], "level": 30, "approvalRequired": false, "revokeRequired": false}
Sample Success Response: Returns a JSON output containing the details of the role.
{"id": "cn=PhysicsProfessor1,cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=User Application Driver,cn=driverset1,o=system", "name": "PhysicsProfessor1", "description": "PhysicsProfessor1", "categories": [null], "owners": [null], "level": 30, "approvalRequired": false, "revokeRequired": false, "localizedNames": [{"locale": "en", "name": "PhysicsProfessor1" }], "localizedDescriptions": [{"locale": "en", "desc": "PhysicsProfessor1"}]}
You can modify all role parameters except Level and Subcontainer. You can edit each role separately or multiple roles at the same time. For example, if you want to set the approval for a role, use the following example endpoint:
Request URL: https://IP:port:8543/IDMProv/rest/catalog/roles/role
Request Method: PUT
Sample Request Payload: {"roles": [{"id": "cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system", "name": "PhysicsProfessor1", "localizedNames": [{ "locale": "en", "name": "PhysicsProfessor1"}], "description": "PhysicsProfessor1", "localizedDescriptions": [{ "locale": "en", "desc": "PhysicsProfessor1" }], "categories": [{"id": "system", "name": "System Roles", "type": "category" }], "owners": [], "approvalRequired": true, "approvalIsStandard": true, "approvalApprovers": [{ id": "cn=kevin,o=data", "name": "kevin klaus", "type": "user", "sequence": 0}]}]}
Sample Success Response: Returns a JSON output containing the details of the updated role.
{"success": "true", "succeeded": {"id": "cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system"}}
You can delete a role when it is no longer required in the system. When you issue the endpoint to delete a role, Identity Applications set the status of the role to a pending delete status. The Role and Resource Service driver notes the change of status for the role and removes the corresponding references and then deletes the role from the Identity Vault.
Request URL: https://IP:port:8543/IDMProv/rest/catalog/roles/role
Request Method: DELETE
Sample Request Payload: {"roles":[{"id":"cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system","name":"PhysicsProfessor1","description":"PhysicsProfessor1","level":30,"roleLevel":"Business Role","rowId":"cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system"}]}
Sample Success Response: Returns a JSON output containing the DN of the deleted role.
{"success":"true","succeeded":{"id":"cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system"}}
A role can be associated with other roles, mapped with organizational resources, and assigned to users, groups, or containers. To obtain the details of a role, use the following example endpoint:
Request URL: https://IP:port:8543/IDMProv/rest/catalog/roles/role
Request Method: POST
Sample Request Payload: {"roles": {"id": "cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system"}} {"arraySize":1,"roles":[{"id":"cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system","name":"PhysicsProfessor1","description":"PhysicsProfessor1","approvalRequestDef":"cn=Role Approval,cn=RequestDefs,cn=AppConfig,cn=User Application Driver,cn=driverset1,o=system","approvalApprovers":[{"id":"cn=kevin,o=data","name":"kevin kevin","type":"user","sequence":"0"}],"level":30,"roleLevel":{"name":"Business Role","level":30,"cn":"cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=User Application Driver,cn=driverset1,o=system"},"subContainer":"","approvalIsStandard":true,"approvalRequired":true,"localizedNames":[{"locale":"en","name":"PhysicsProfessor1"}],"localizedDescriptions":[{"locale":"en","desc":"PhysicsProfessor1"}]}]}
Sample Success Response: Returns the details of the role.
{"roles": {"id": "cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system"}}
{"arraySize":1,"roles":[{"id":"cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system","name":"PhysicsProfessor1","description":"PhysicsProfessor1","approvalRequestDef":"cn=Role Approval,cn=RequestDefs,cn=AppConfig,cn=User Application Driver,cn=driverset1,o=system","approvalApprovers":[{"id":"cn=kevin,o=data","name":"kevin kevin","type":"user","sequence":"0"}],"level":30,"roleLevel":{"name":"Business Role","level":30,"cn":"cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=User Application Driver,cn=driverset1,o=system"},"subContainer":"","approvalIsStandard":true,"approvalRequired":true,"localizedNames":[{"locale":"en","name":"PhysicsProfessor1"}],"localizedDescriptions":[{"locale":"en","desc":"PhysicsProfessor1"}]}]}
A user is an individual in an organization (typically an employee) who requires access to one or more resources. Users are added to Identity Manager to provision resources to them. When you create a user, the user is stored as a user object in the Identity Vault. Each user object is associated with attributes that act as identifiers for the user. For example, a user’s attributes can include user’s first name, last name, phone numbers, employee number, manager, and e-mail address.
The following examples describe some of the basic user management operations, such as create a user, delete an existing user, and update the details of an existing user such as change the email ID, phone number, and manager. You can edit a single user or multiple users at the same time.
Access Rights Needed: Provisioning Administrator
Use the following example endpoint to create a user.
Request URL: https://IP:port:8543/IDMProv/rest/access/user
Request Method: POST
Sample Request Payload: {"container":"o=data","password":"novell","attributes":[{"key":"FirstName","dataType":"String","isRequired":true,"values":["kevin"],"action":"add"},{"key":"LastName","dataType":"String","isRequired":true,"values":["kevin"],"action":"add"},{"key":"CN","dataType":"String","isRequired":false,"values":["kevin"],"action":"add"} ] }
Sample Success Response: Returns a JSON output containing the details of the user created in the Identity Vault.
{"dn":"cn=kevin,o=data"}
You can modify all user attributes that are configured in the Directory Access Layer. For example, if you want to change the title of a user, use the following example endpoint:
Request URL: https://IP:port:8543/IDMProv/rest/access/user
Request Method: PUT
Sample Request Payload: {"dn":"cn=ABlake,o=data","attributes":[{"key":"Title","values":["SE"],"action":"UPDATE"},{"key":"Email","values":[],"action":"UPDATE"},{"key":"TelephoneNumber","values":[],"action":"UPDATE"},{"key":"manager","values":[],"action":"UPDATE"},{"key":"directReports","values":[],"action":"UPDATE"}]}
Sample Success Response: Returns a JSON output containing all the details of the user.
{"dn":"cn=ABlake,o=data","attributes":[{"name":"Hidden attribute List","key":"srvprvHideAttributes","hidden":false,"dataType":"String"},{"name":"Email","key":"Email"," hidden":false,"dataType":"String"},{"name":"Manager","key":"manager","hidden":false,"dataType":"DN"},{"name":"Direct Reports","key":"directReports","hidden":false,"dataType":"DN"},{"name":"First Name","key":"FirstName","values":["ABlake"],"hidden":false,"dataType":"String"},{"name":"Title","key":"Title","values":["SE"],"hidden":false,"dataType":"String"},{"name":"CN","key":"CN","values":["ABlake"],"hidden":false,"dataType":"String"},{"name":"Telephone Number","key":"TelephoneNumber","hidden":false,"dataType":"String"},{"name":"User Preferences","key":"srvprvUserPrefsPlus","hidden":false,"dataType":"Stream"},{"name":"User Photo","key":"UserPhoto","hidden":false,"dataType":"Binary"},{"name":"Department","key":"Department","hidden":false,"dataType":"String"},{"name":"Query List","key":"srvprvQueryList","hidden":false,"dataType":"String"},{"name":"User Preferences","key":"srvprvUserPrefs","hidden":false,"dataType":"String"},{"name":"Preferred Notification","key":"NotificationPrefs","hidden":false,"dataType":"String"},{"name":"Last Name","key":"LastName","values":["ABlake"],"hidden":false,"dataType":"String"},{"name":"Dashboard Preferences","key":"srvprvDashboardPrefs","hidden":false,"dataType":"Stream"},{"name":"Region","key":"Location","hidden":false,"dataType":"String"},{"name":"Group","key":"group","hidden":false,"dataType":"DN"}]}
You can delete or make a user inactive if the user is no longer part of the organization. To delete a user, use the following example endpoint:
Request URL: https://IP:port:8543/IDMProv/rest/access/user
Request Method: DELETE
Sample Request Payload: {"members":[{"dn":"cn=ABlake,o=data"}]}
Sample Success Response: Returns a JSON output containing the DN of the deleted user.
{"success":true,"succeeded":[{"id":"cn=ABlake,o=data","name":"Aston Blake"}]}
An administrator can assign a role to a user, group, or a container.
To assign a role to a user, use the following example endpoint:
Access Rights Needed: Role Administrator or Role Manager
Request URL: https://IP:PORT/IDMProv/rest/catalog/roles/role/assignments/assign
Sample Request Method: POST
Sample Request Payload: {"reason": "change of designation", "assignments": [{"id": "cn=rolea,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system", "assignmentToList": [{ "assignedToDn": "cn=kevin,o=data", "subtype": "user"}], "effectiveDate": "", "expiryDate": ""}]}
Sample Success Response: Returns a JSON output containing a list of role assignments of the user.
{"success":"true","succeeded":{"id":"cn=rolea,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system","assignToUsers":{"dn":"cn=kevin,o=data","name":"kevin"}}}
The role catalog user interface of Identity Applications leverages the same API for assigning a role to a user.
Users can request a role for themselves.
Access Rights Needed: Any end-user who can log in to the Dashboard can access it.
Request URL: https://port:port/IDMProv/rest/access/requests/permissions
Request Method: POST
Sample Request Payload: {"reason":"change of designation","effDate":"","expDate":"","reqPermissions":[{"id":"cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system","dn":"cn=PhysicsProfessor1,cn=Level30,cn=RoleDefs,cn=RoleConfig,cn=AppConfig,cn=User Application Driver,cn=driverset1,o=system","name":"PhysicsProfessor1","desc":"PhysicsProfessor1","entityType":"role","bulkRequestable":true,"link":"/IDMProv/rest/access/permissions/item","multiAssignable":true,"edition":"rbpm.role.1552670228469","isNewForm":false,"isExpirationRequired":"false"}]}
Sample Success Response: Returns a JSON output containing the details of the requested role.
{"success":true,"succeeded":[{"id":"cn=PhysicsProfessor1,cn=level30,cn=roledefs,cn=roleconfig,cn=appconfig,cn=user application driver,cn=driverset1,o=system","instanceId":"cn=20190320201141-05e23fe7133c4014bb4bcefc2e9d980b-0,cn=Requests,cn=RoleConfig,cn=AppConfig,cn=User Application Driver,cn=driverset1,o=system"}]}
Tasks are the activities assigned to a user who is responsible for granting permissions. The user can either approve or deny the request for permissions one at a time or perform a bulk action for multiple simple requests that do not require detailed information.
The following examples describe the basic operations that can be performed by using the REST APIs, such as getting a task list and filtering tasks based on recipients.
You can obtain a list of all tasks assigned to a user who is currently logged-in to the application. For example, when a user navigates to the Tasks page, the Identity Applications invokes the following API to obtain the task list assigned to that user.
Access Rights Needed: Any end-user who can log in to the Dashboard can access it.
Request URL: https://IP:port:8543/IDMProv/rest/access/tasks/list
Request Method: GET
Sample Request Payload: fromIndex=1&size=25&q=*&sortOrder=desc&sortBy=createTime&assignedTo=assignedTo&recipient=recipientAsMe&expireUnit=weeks&expireWithin=&proxyUser=&assignStatus=&delegatedTasks=false&onlyHelpdeskTask=false&status=
Sample Success Response: Returns a JSON output containing a list of tasks assigned to the logged-in user (KEVIN).
{
"total": 2,
"hasMore": false,
"tasks": [
{
"taskId": "99e28c696cda48fcaff9de2c8fdb74a6",
"link": "/IDMProv/rest/access/tasks/item",
"processName": "Add Role To User - Arole",
"activityName": "Role Request/Revocation Approval",
"createTime": "1612334004663",
"recipient": "cn=ABlake,o=data",
"recipientType": "user",
"recipientName": "ABlake ABlake",
"bulkApprovable": true,
"approvalFormId": "Role Approval Form",
"addresseetype": "0",
"addresseeEntityType": "user",
"addressee": "cn=Kevin,o=data",
"assignedTo": "Kevin Chester",
"priority": "2",
"delegatedTask": "false",
"assignStatus": "DEFAULT",
"confirmationNumber": "20210203-13",
"isNewForm": true
},
{
"taskId": "444b199724bf45f4a415830b27b8bdb0",
"link": "/IDMProv/rest/access/tasks/item",
"processName": "Add Role To User - IT_service_desk_role",
"activityName": "Role Request/Revocation Approval",
"createTime": "1603355106283",
"recipient": "cn=Anil,o=data",
"recipientType": "user",
"recipientName": "Anil K",
"bulkApprovable": true,
"approvalFormId": "Role Approval Form",
"addresseetype": "0",
"addresseeEntityType": "user",
"addressee": "cn=Kevin,o=data",
"assignedTo": "Kevin Chester",
"priority": "2",
"delegatedTask": "false",
"assignStatus": "DEFAULT",
"confirmationNumber": "20201022-14",
"isNewForm": true
}
],
"totalSize": 2,
"nextIndex": 0,
"userTypeInTask": true
}
The REST API provides you query parameters to filter tasks based on different task attributes, such as process name, activity name, or recipient. For example, if you want to filter all tasks for a certain recipient, then use the following sample endpoint:
Access Rights Needed: Any end-user who can log in to the Dashboard can access it. You can use this API for both the end user and administrator’s tasks.
Request URL: https://IP:port:8543/IDMProv/rest/access/tasks/list
Request Method: GET
Sample Request Payload: fromIndex=1&size=25&q=ABlake&sortOrder=desc&sortBy=createTime&assignedTo=assignedTo&recipient=recipientAsMe&expireUnit=weeks&expireWithin=&proxyUser=&assignStatus=&delegatedTasks=false&onlyHelpdeskTask=false&status=
Sample Success Response: Returns a JSON output containing all tasks for the recipient (ABlake) that are assigned to the logged-in user.
{
"total": 1,
"hasMore": false,
"tasks": [
{
"taskId": "99e28c696cda48fcaff9de2c8fdb74a6",
"link": "/IDMProv/rest/access/tasks/item",
"processName": "Add Role To User - Arole",
"activityName": "Role Request/Revocation Approval",
"createTime": "1612334004663",
"recipient": "cn=ABlake,o=data",
"recipientType": "user",
"recipientName": "Allison Blake",
"bulkApprovable": true,
"approvalFormId": "Role Approval Form",
"addresseetype": "0",
"addresseeEntityType": "user",
"addressee": "cn=Kevin,o=data",
"assignedTo": "Kevin Chester",
"priority": "2",
"delegatedTask": "false",
"assignStatus": "DEFAULT",
"confirmationNumber": "20210203-13",
"isNewForm": true
}
],
"totalSize": 1,
"nextIndex": 0,
"userTypeInTask": true
}
NOTE:The query parameters provided with the IDMProv/rest/access/tasks/list REST API can be used to match the legacy /v1/wf/workitems?filter={recipient}={value} RIS API to obtain the task list for a specific recipient. However, the IDMProv does not provide a dedicated REST API (similar to the RIS API) and can only filter the recipient’s tasks that assigned to the logged-in user. For more information on the Identity Applications REST APIs and supported query parameters, see the REST API documentation.
A Helpdesk user and administrator can view the task list of all users present in the system.
Access Rights Needed: Provisioning Administrator
Request URL: https://IP:port:8543/IDMProv/rest/access/tasks/list/others
Request Method: GET
Sample Request Payload: fromIndex=1&size=25&q=*&sortOrder=desc&sortBy=createTime&assignedTo=assignedTo&recipient=recipientAsMe&expireUnit=weeks&expireWithin=&proxyUser=&assignStatus=&status=
Sample Success Response: Returns a JSON output containing the task list for all users.
{
"total": 3,
"hasMore": false,
"tasks": [
{
"taskId": "652f7db2851a4b40b15e14fadbd35683",
"link": "/IDMProv/rest/access/tasks/item",
"processName": "Add Role To User - IT_service_desk_role",
"activityName": "Role Request/Revocation Approval",
"createTime": "1612334700391",
"recipient": "cn=Maria,o=data",
"recipientType": "user",
"recipientName": "Maria Belafonte",
"bulkApprovable": true,
"approvalFormId": "Role Approval Form",
"addresseetype": "2",
"addresseeEntityType": "user",
"addressee": "cn=Kevin,o=data",
"assignedTo": "Kevin Chester",
"priority": "2",
"delegatedTask": "false",
"assignStatus": "DEFAULT",
"confirmationNumber": "20210203-20",
"isNewForm": true
},
{
"taskId": "ea9f8829b508435fbea9448789103349",
"link": "/IDMProv/rest/access/tasks/item",
"processName": "Add Role To User - IT_service_desk_role",
"activityName": "Role Request/Revocation Approval",
"createTime": "1612334700142",
"recipient": "cn=ABlake,o=data",
"recipientType": "user",
"recipientName": "Allison Blake",
"bulkApprovable": true,
"approvalFormId": "Role Approval Form",
"addresseetype": "2",
"addresseeEntityType": "user",
"addressee": "cn=Kevin,o=data",
"assignedTo": "Kevin Chester",
"priority": "2",
"delegatedTask": "false",
"assignStatus": "DEFAULT",
"confirmationNumber": "20210203-19",
"isNewForm": true
},
{
"taskId": "824ed402ca2b45ab84651cfc1f4d28df",
"link": "/IDMProv/rest/access/tasks/item",
"processName": "Add Role To User - Arole",
"activityName": "Role Request/Revocation Approval",
"createTime": "1612334004355",
"recipient": "cn=Kevin,o=data",
"recipientType": "user",
"recipientName": "Kevin Chester",
"bulkApprovable": true,
"approvalFormId": "Role Approval Form",
"addresseetype": "2",
"addresseeEntityType": "user",
"addressee": "cn=Margo,o=data",
"assignedTo": "Margo Mackenzie",
"priority": "2",
"delegatedTask": "false",
"assignStatus": "DEFAULT",
"confirmationNumber": "20210203-11",
"isNewForm": true
}
],
"totalSize": 3,
"nextIndex": 0,
"userTypeInTask": false
}
NOTE:The IDMProv/rest/access/tasks/list/others REST API can be used to match the legacy /v1/wf/workitems RIS API to obtain the task list of all users in the system. For more information on the Identity Applications REST APIs and supported query parameters, see the REST API documentation.