40.1 Use Cases for Identity Applications REST API

This topic describes some of the basic use cases that you can accomplish using Identity Applications REST API.

40.1.1 Before You Begin

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.

40.1.2 Use Cases

The following use case describe some of the basic operations that can be performed by using Identity Applications REST APIs:

Role Management

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

Example 1: Create a Role

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/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"}]} 

Example 2: Modify a Role

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/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"}}

Example 3: Delete a Role

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/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"}}

Example 4: Obtain the Details of a Role

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/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"}]}]} 

User Management

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

Example 1: Create a User

Use the following example endpoint to create a user.

Request URL: https://IP:port/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"}

Example 2: Modify a User

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/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"}]}

Example 3: Delete a User

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/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"}]} 

Assign a Role to a User

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.

40.1.3 Request a Role for Yourself

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://IP: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"}]}