Accessing and using the Role-Based Access Control Service API

Edit online

Use the Role-Based Access Control Service API to manage the lifecycle of role-based access control policies from the command line.

About this task

Complete role-based access tasks such as creating, viewing, updating, and deleting roles. Add and delete a set of users or user groups from a specific role. Grant permissions to a specific role. View a list of roles, users, user groups, and permissions that are defined in the system.

You can create scripts for automating such tasks as defining new roles and assigning users, user groups, and permissions to these roles.

In this task you can use either access tokens or basic authorisation in the curl command:

Access tokens: Use the OpenID Connect (OIDC) protocol to get an access token from the OIDC server on the Cloud APM server. The access token gives you authorised access to the API for running operations until the token expires after 30 minutes.

Basic authorisation

Use a base64 tool to encode your Cloud APM console user ID and password into a single base64 string. The input string format is userId:password, such as apmadmin:apmpass. The output is a string such as: YXBtYWRtaW46YXBtcGFzcw==

Use base64_encoded_string in the authorisation header of every request as shown in the curl command examples.

Note the Cloud APM console user ID must be added to a role with appropriate permissions.

Disabling OIDC authentication, which is required before you can enable single sign-on (SSO) between Cloud APM and other IBM® products such as Tivoli® Common Reporting that require LTPA for single sign-on, does not affect the API. The RESTful API continues to use the Cloud APM internal OIDC server, even if OIDC is disabled for single sign-on between the Cloud APM console and other product user interfaces.

Role-Based Access Control Service API requests must be issued by using https to the port 9443 of the Cloud APM server.

Procedure

On the system where the Cloud APM server is installed, open the following file and copy the values of the client.secret.apmui and client.id.apmui variables:

install_dir/wlp/usr/shared/config/clientSecrets.xml

The following example shows what the file contains:

<server>
  <variable name="client.secret.apmui" value="{xor}BiY3KQgIa2gRCms3CxxrMhUYL2YRJSwvCjUnJxYb" />
  <variable name="client.id.apmui" value="rpapmui" />
</server>

Optional: If you plan to use an access token in your curl command, use an XOR decoder to decode the value of the client.secret.apmui variable to get the actual secret value.
For example, when you use an XOR decoder to decode BiY3KQgIa2gRCms3CxxrMhUYL2YRJSwvCjUnJxYb, you get the following value: YyhvWW47NU4hTC4mJGp9NzspUjxxID
Optional: If you plan to use an access token in your curl command, complete this step. To get an access token, contact the token endpoint of the Cloud APM OIDC server with the four required items: username, password, client_id, and client_secret, as in the following command:
```
curl --tlsv1.2 -v -k -d "grant_type=password&client_id=rpapmui&client_secret=YyhvWW47NU4hTC4mJGp9NzspUjxxID&username=apmadmin&password=apmpass&scope=openid" https://example.mycompany.com:8099/oidc/endpoint/OP/token
```
Where:
- username is the username of the Cloud APM console user
- password is the password of a Cloud APM console user
- clientid is the value of the client.id.apmui variable from step 1.
- client_secret is the value created by the XOR decoder in step 2.
Output:
```
{"access_token":"jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8","token_type":"Bearer","expires_in":1800,"scope":"openid","refresh_token":"VsCWUhPHBRpidD2F1PVyZ2LNGMuQPTN837t3OoqZj71FcBfsGE"}
```
Note: If the client_secret, username, or password values contain characters other than digits (0-9), ASCII letters (A-Z, a-z), and a few special characters ( "-" , "." , "_" , "~" ), you must URL encode the other characters. For example, if the decoded client secret is TEVlNjROVT8iPF9r=1dNNW8+SGFgJ0, replace the = character with %3D, replace the + character with %2B, and enter client_secret=TEVlNjROVT8iPF9r%3D1dNNW8%2BSGFgJ0 instead of client_secret=TEVlNjROVT8iPF9rO1dNNW8+SGFgJ0.
Optional: If you plan to use an access token in your curl command, extract the access_token value.
Looking at the output in the previous example, the value is jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8.

Enter requests to the Role-Based Access Control Service API using either an access token or basic authorisation.

Access token example:

curl --tlsv1.2 -v -k --request GET 
--url 'https://myAPMServer.mycompany-domain.com:9443/1.0/authzn/users'  
--header 'authorization: Bearer  jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8' 
--header 'content-type: application/json'

Basic authorisation example:

curl --tlsv1.2 -v -k --request GET 
--url 'https://myAPMServer.mycompany-domain.com:9443/1.0/authzn/users'  
--header 'authorization: Basic YXBtYWRtaW46YXBtcGFzcw==' 
--header 'content-type: application/json'

For more details about API operations, see API documentation in API Explorer. For instructions about accessing API Explorer, see Exploring the APIs.

Note: Part of the URL and some of the headers that are shown in the examples are required for Cloud APM only. For example: https://api.ibm.com/perfmgmt/run, x-ibm-service-location, X-IBM-Client-Id, X-IBM-Client-Secret. See step 5 for request examples.
You must include a referer header in all POST, PUT, and DELETE requests. The value for the referer header is:
```
-H 'Referer: https://apm_server:9443'
```
where apm_server is the IP address or the fully qualified host name of your Cloud APM server.

Example

The following example uses the curl command to create a new role.

POST /1.0/authzn/roles

Note: The body of the POST request must contain a JSON object that defines the role as shown by the -d parameter.


curl -X POST \
  https://apm_server:9443/1.0/authzn/roles \
  -H 'Referer: https://apm_server:9443' \
  -H 'authorization: Bearer Your_Access_Token' \
  -H 'content-type: application/json' \
  -d '{
    "description": "Your Role Description",
    "id": "/authzn/roles/Your_Role_Id",
    "label": "Your Role Name"
}'