Authentication for the Cloud Administration APIs
Clients calling the Cloud Administration APIs must authenticate themselves by including a bearer token in the HTTP request. The bearer token must be provided in the HTTP Authorization header as follows:
Authorization: Bearer <bearer token>
The bearer token can be one of the following:
A Base64 URL-safe encoded OAuth Access Token created by Cloud Access Service (CAS) at the request of an OAuth Administration API client.
A Base64 URL-safe encoded JSON Web Token (JWT) created by a Legacy Administration API client.
Both types of bearer tokens have limited lifetimes. See the following sections for details. A bearer token can be reused in multiple Cloud Admin API requests, until it expires.
OAuth Administration API Client
Obtaining the OAuth Access Token
For OAuth-based authentication, a Super Administrator configures settings for OAuth Clients using the Cloud Administration Console, as described in Manage OAuth API Clients. The OAuth API Client must be configured by the Super Administrator with the permissions required for all the different Cloud Administration APIs that your client will use. For more information, see OAuth 2.0-Based Permissions for the Cloud Administration APIs. Contact your Super Administrator to obtain the following OAuth client credentials for your Admin API client:
Issuer URL
Client ID
Private key file
Private key type (RSA or EC)
When you obtain the OAuth Client credentials, use them to build an OAuth Client Assertion. The Client Assertion must then be sent in a Cloud Administration API Token request to CAS. CAS will return an OAuth Access Token to be used in Cloud Admin API requests until the Access Token expires.
To generate OAuth credentials for your client, you must first build a client assertion as a signed JSON Web Token (JWT) and send it to CAS. CAS (acting as an OAuth authorization server) will generate and return an access token to the client. The access token can be reused in multiple Admin API requests, until it expires.
Access tokens have limited lifetimes. The maximum allowed lifetime for any access token generated for an OAuth Admin API client, is configured for that client in CAS, by the Super Administrator. The Maximum allowed access token lifetime cannot be longer than 24 hours .
OAuth Client Assertion
The OAuth client assertion is a Base64/URL-safe encoded JSON Web Token (JWT) formatted as a JSON Web Signature (JWS). It is sent as the client_assertion in a token request from an OAuth Admin API client to the RSA Cloud Access Service (CAS). CAS, acting as an OAuth Authorization Server, will return an OAuth access token. The access token is used as the bearer token for client authentication in later Cloud Administration API requests.
To build an OAuth client assertion, the client will require the following data from the OAuth API client configured by a Super Administrator in the Cloud Administration Console:
Issuer URL
Client ID
Private key (downloaded in JSON Web Key format (JWK) format)
Private key type (RSA or EC)
A client assertion JWT has three parts parts:
JOSE header
JWT claims
Signature
These three parts must be formatted using JWS Compact Serialization as defined in RFC 7515: JSON Web Signature (JWS).
BASE64URL(UTF8(JOSE header)) || '.' ||
BASE64URL(JWT claims) || '.' ||
BASE64URL(Signature)
Note: "||" means "concatenate"
A source code example of how to build an OAuth Client Assertion is available in the RSA IDPlus Admin Rest API Download (v2.8.0 and later) available from the RSA ID Plus Downloads page.
Python source code is in API download file \src\main\python\admin_api_cli\admin_api_cli\admin_api_cli.py in method generate_oauth_token().
JOSE Header
See the following JOSE Header example:
{
"alg":"ES256",
"kid":"07dda36e-d0d8-4f56-989c-410def304ad1",
"typ":"JWT"
}
| Claim | Description |
|---|---|
| alg | Must be “RS256” if the private key type is RSA. Must be “ES256” if the private key type is EC. This is the algorithm used to sign the client assertion. |
| kid | Use the kid value from the private key file |
| typ | Must be “JWT” |
JWT Claims
See the following JWT Claims example:
{
"iss":"787372bd-e949-4751-93ab-9852d933bfcd",
"sub":"787372bd-e949-4751-93ab-9852d933bfcd",
"aud":"https://tenant.auth.securid.com/oauth/token",
"jti":"1754646708",
"exp":1754650308,
"iat":1754646708
}
Note: UNIX Epoch Time format in the following table means the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds.
| Claim | Description |
|---|---|
| iss | Client ID From the OAuth API client in the Cloud Administration Console. Provided by the Super Administrator. |
| sub | Client ID From the OAuth API client in the Cloud Administration Console. Provided by the Super Administrator. |
| aud | Issuer URL || ‘/token’. The Issuer URL is from the OAuth API client in the Cloud Administration Console. Provided by the Super Administrator. |
| jti | A JWT ID, as defined by section 4.1.7 of RFC 7519 JSON Web Token (JWT). Any unique value that can be used to prevent the JWT Claim from being replayed. The value is a case-sensitive string. |
| exp | Expiration time. The expiration time in UNIX Epoch Time format, on or after which the client assertion will not be accepted by CAS. |
| iat | Current time. UNIX Epoch Time format. It must be before the time in the exp claim. |
Signature
A digital signature using the private key must generated over a concatenation of the encoded JOSE header and claims parts, separated by a dot:
BASE64URL(UTF8(JOSE Header)) || '.' || BASE64URL(JWT Claims)
An example of a string that must be signed is:
eyJhbGciOiJFUzI1NiIsImtpZCI6IjA3ZGRhMzZlLWQwZDgtNGY1Ni05ODljLTQxMGRlZjMwNGFkMSIsInR5cCI6IkpXVCJ9.
eyJpc3MiOiI3ODczNzJiZC1lOTQ5LTQ3NTEtOTNhYi05ODUyZDkzM2JmY2QiLCJzdWIiOiI3ODczNzJiZC1lOTQ5LTQ3NTEtOTNhYi05ODUyZDkzM2JmY2QiLCJhdWQiOiJodHRwczovL3RlbmFudC5hdXRoLnNlY3VyaWQuY29tL29hdXRoL3Rva2VuIiwianRpIjoiMTc1NDk5MzU5MiIsImV4cCI6MTc1NDk5NzE5MiwiaWF0IjoxNzU0OTkzNTkyfQ
The signature must be generated using the private key (downloaded in JWK format from the OAuth API client in the Cloud Administration Console) and the alg (algorithm) specified in the JWT header. Signature algorithms are defined here:
RS256: defined in section 3.3 of RFC 7518 JSON Web Algorithms (JWA)
ES256: defined in section 3.4 of RFC 7518 JSON Web Algorithms (JWA)
Building the OAuth Client Assertion
The client assertion is formed as a concatenation of the encoded JOSE header, JWT claims and Signature, separated by dots, as follows:
BASE64URL(UTF8(JOSE Header)) || '.' || BASE64URL(JWS Claims) || '.' || BASE64URL(Signature)
See the following example of a client assertion:
eyJhbGciOiJFUzI1NiIsImtpZCI6IjA3ZGRhMzZlLWQwZDgtNGY1Ni05ODljLTQxMGRlZjMwNGFkMSIsInR5cCI6IkpXVCJ9.
eyJpc3MiOiI3ODczNzJiZC1lOTQ5LTQ3NTEtOTNhYi05ODUyZDkzM2JmY2QiLCJzdWIiOiI3ODczNzJiZC1lOTQ5LTQ3NTEtOTNhYi05ODUyZDkzM2JmY2QiLCJhdWQiOiJodHRwczovL3RlbmFudC5hdXRoLnNlY3VyaWQuY29tL29hdXRoL3Rva2VuIiwianRpIjoiMTc1NDk5MzU5MiIsImV4cCI6MTc1NDk5NzE5MiwiaWF0IjoxNzU0OTkzNTkyfQ.
e0BqGkTM4TNLBUqvKY22uQOoXqGK5iuBfSg41gd2KbwDykkWZNu8SWu02yIsybZavGrsR_QsDWEShwyV_MEBaA
Cloud Administration OAuth Token API
To request an OAuth Access Token, the OAuth Administration API Client must send a Token Request to CAS.
Use the Cloud Administration OAuth Token API to request an OAuth Access Token that can be sent in later Cloud Administration API requests in the HTTP Authorization header as a bearer token.
A source code example of how to build an OAuth Token API request is available in the RSA IDPlus Admin Rest API Download (v2.8.0 and later) available from the RSA ID Plus Downloads page.
Python source code is in API download file \src\main\python\admin_api_cli\admin_api_cli\admin_api_cli.py in method generate_oauth_token().
Authentication
Use the following information to request an OAuth Access Token.
Request Requirements
| Method | Request URL | Response Body | Response Body Type | Response Codes |
|---|---|---|---|---|
| PUT | /oauth/token | application/json;charset=UTF-8 | access_token | 200, 403, 500 |
Example Request Data
The following example displays an OAuth Token request.
PUT https://tenant.auth.securid.com/oauth/token
Content-Type: application/x-www-form-urlencoded; charset=UTF-8'
grant_type=client_credentials&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjA3ZGRhMzZlLWQwZDgtNGY1Ni05ODljLTQxMGRlZjMwNGFkMSIsInR5cCI6IkpXVCJ9.
eyJpc3MiOiI3ODczNzJiZC1lOTQ5LTQ3NTEtOTNhYi05ODUyZDkzM2JmY2QiLCJzdWIiOiI3ODczNzJiZC1lOTQ5LTQ3NTEtOTNhYi05ODUyZDkzM2JmY2QiLCJhdWQiOiJodHRwczovL3RlbmFudC5hdXRoLnNlY3VyaWQuY29tL29hdXRoL3Rva2VuIiwianRpIjoiMTc1NDk5MzU5MiIsImV4cCI6MTc1NDk5NzE5MiwiaWF0IjoxNzU0OTkzNTkyfQ.
vIJV5zcNkD8GY2VRL2ZcuLfRBsAkhsNsmcIKvavEFykDMBfBv3865A53wTxsBQPNzbJflNClb6zA7LjjsZMdaA&scope=rsa.audit.user+rsa.audit.admin
Request Parameters
The following table describes the request parameters, which must be in the request body:
| Parameter | Value |
|---|---|
| grant_type | “client_credentials” |
| client_assertion_type | “urn:ietf:params:oauth:client-assertion-type:jwt-bearer” |
client_assertion | Base64, URL-safe encoded OAuth Client Assertion |
| scope | Plus(+)-separated list of one or more permissions for the Cloud Administration API. See OAuth 2.0-Based Permissions for the Cloud Administration APIs. |
Example Response Data
{
"access_token":"eyJraWQiOiIyMTE2Mzk1Mzk5NTA5MjU2MTYyOTQwODIyMTYyMjk3MDA3NTg0Nzk3ODQ4NDc1MjAiLCJhbGciOiJSUzI1NiJ9.
eyJzdWIiOiI3ODczNzJiZC1lOTQ5LTQ3NTEtOTNhYi05ODUyZDkzM2JmY2QiLCJhdWQiOlsiaHR0cHM6Ly9teVRlbmFudC5hY2Nlc3Muc2VjdXJpZC5jb20iLCJodHRwczovL215VGVuYW50LmF1dGguc2VjdXJpZC5jb20iXSwidmVyIjoxLCJzY29wZSI6InJzYS5hdWRpdC5hZG1pbiByc2EuYXVkaXQudXNlciIsImlzcyI6Imh0dHBzOi8vbXlUZW5hbnQuYXV0aC5zZWN1cmlkLmNvbS9vYXV0aCIsImV4cCI6MTc1NTA4MTAxNSwiaWF0IjoxNzU0OTk0NTU1LCJqdGkiOiI2NDg4MTg1MzAifQ.
uItwWcaWe4cWlA2a6z-RF42T9H5OWVgKLDPaBUGqF2hIftzIgkU2UWcmxyEwNALfjCH1foh-eNx-Ii-FjpuqouV2ZzyBv232Rt5S8IpM_7jYCEU9n6_s3j8GzW-DS7Ne9J8NWDv_w7cR2h7JexOX4QA0HfVuLJSaPkmF8SX3uR6FcIuDLrnM6SjZ-LEaONjfv6E5OeqeAAyP95H3XAhuxx8ICQnWSS9Z2InwOStQqWJ5XtT1kcujewIlKdWiFiV-oV0L8jMVdK8VmNhLAEHC971MaG0ALpH6PfN361hsyCL7--CBzkHNVIc8E_M40J-qtsLXrGRZdFbjYap3swzNjw",
"scope":"rsa.audit.admin rsa.audit.user",
"token_type":"Bearer",
"expires_in":86400
}
Response Property Descriptions
The following table shows property descriptions and data types.
| Property | Description | Data Type |
|---|---|---|
| access_token | Base64-encoded OAuth Access Token generated by CAS | String |
| scope | Space-separated list of permissions granted by CAS. This will be all permissions sent in the request, less any that are not permitted for this OAuth Client. | String |
| token_type | “Bearer” | String |
| expires_in | Number of seconds until the access_token expires. The maximum possible value is 86400 (24 hours). | Integer |
Response Codes
The following table shows response codes and descriptions for this API.
| Code | Description |
|---|---|
| 200 | OAuth Access Token granted. |
| 403 | Not authorized to perform the request |
| 500 | Internal error occurred when processing the request. |
Legacy Administration API
Generating a JSON Web Token (JWT)
Legacy Administration API requests require a valid Base64 URL-encoded legacy JWT, signed with the client's Legacy Administration API key.
A Super Administrator generates the required Legacy Administration API key for the client using the Cloud Administration Console, as described in Manage the RSA Administration API Keys (Legacy Clients) and downloads the Legacy Administration API Key file.
The Legacy Admin API client must generate a JWT, using the key from the API key file to create its Signature. The client must then Base64 URL-encode the JWT. The encoded JWT must be provided as the bearer token in the HTTP Authorization header of subsequent Admin API request(s). Each JWT can be valid for up to 60 minutes.
JWT Format for Legacy Administration API Clients
A JWT for a Legacy Administration API client is in JSON Web Signature (JWS) format. It consists of three parts:
- JOSE header
- JWT claims
- Signature
These three parts must be formatted using JWS Compact Serialization as defined in RFC 7515: JSON Web Signature (JWS).
JOSE Header
The JOSE (JSON Object Signing and Encryption) header consists of the following set of header parameters. The RS256 algorithm must be used to sign the token and must be specified in the header. The "typ": "JWT" header parameter is optional but supported. Other values are not supported and will result in an HTTP 403 Authorization error.
{
"typ": "JWT",
"alg": "RS256"
}
JWT Claims
The following table lists standard claims that must be present in the JWT Claims part for authentication. All other claims are ignored.
| Claim | Value |
|---|---|
| sub | Access ID value of the Administration API key (the accessID property in the Admin API key file). |
| iat | The time when the JWT was created, specified in Unix Epoch time. |
| exp | Expiration time of JWT, specified in Unix Epoch time. A clock skew of 60 seconds is allowed. For security reasons, tokens must expire one hour or less after they are issued. CAS will enforce this (a request containing an access token where the exp time in the JWT Claim is more than 60 minutes after the iat time, will be rejected by CAS). |
| aud | Audience of the claim. Value must be the Admin REST API Base URL. This can be obtained from the adminRestApiUrl property of the Admin API key file. |
See the following example of JWT claims:
{
"sub": "139f6495-e447-4a26-a765-5c01b6b152d5",
"iat" "1526273000",
"exp": "1526273493",
"aud": "https://mycompany.access-anz.securid.com/AdminInterface/restapi/
}
Signature
A JWT signature must be completed with the RS256 algorithm, using the API Access Key. RS256 is defined in section 3.3. Digital Signature with RSASSA-PKCS1-v1_5 of standard RFC7518: JSON Web Algorithms (JWA).
Token Expiration
Tokens must expire one hour or less after they are issued, otherwise the request is rejected. A clock skew of 60 seconds is allowed. The signed access token can be reused in multiple Admin API requests, until it expires.
Encoding
The signed JWT access token must be Base64, URL-safe encoded and sent in the Authorization Bearer header of subsequent Admin API request(s).
Build the JWT
The following steps and pseudocode show how to create a Legacy JWT. Note: "||" means "concatenate".
Create a JOSE Header and JWT Claims as described above.
Get the private key from the API key file (property accessKey in the API key file).
Use the RS256 algorithm and the private key to sign the Base64-encoded JOSE header and JWT Claims as follows:
signature = RSASHA256(base64UrlEncode(JOSE Header) || "." || base64UrlEncode(JWT Claims), accessKey)
Create the JWT in the format hhhhhh.pppppp.ssssss as follows:
base64UrlEncode(JOSE Header) || "." || base64UrlEncode(JWT Claims) || "."|| base64UrlEncode(signature)
Sample code for generating a legacy API access token from an API Key file, is provided in the RSA IDPlus Admin Rest API Download (v2.8.0 and later) available from the RSA ID Plus Downloads page.
A JWT access token can also be generated from a command line utility (CLU) provided in the API download. Add these bullet points:
Java CLU - see file README_Java.md in the API download.
Python CLU - see file README_Python.md in the download.
