Authentication and Authorization of APIs

This section provides the following information for Query and Service Analytics APIs:
doi13
This section provides the following information for Query and Service Analytics APIs:
Access the REST APIs
The REST APIs connect to the 
DX Operational Intelligence
 Server to read and retrieve the data. To restrict rogue requests, the server processes the REST API requests after authenticating them. Before you invoke the REST API calls in your code, pass the authentication details and receive the authorization token, which you must include in the header of the subsequent API calls. The EMM Security Server handles the authentication and authorization of the REST APIs.
To access the REST APIs, perform the following operations:
  • Authenticate the REST APIs
  • Pass the Authorization Details
Authenticate the REST APIs
The following steps describe the REST API authentication process:
  1. The resource owner or the user provides the client with their username and password.
  2. The client requests an access token from the EMM Security Server's token endpoint by including the credentials that are received from the resource owner. When making the request, the client authenticates with the EMM Security Server.
  3. The EMM Security Server authenticates the user and issues an access token. If the authentication fails, then the EMM Security Server returns an error response.
Use  the 
Authentication
 API for authenticating to the REST APIs. This API takes the user credentials as the input parameters and returns the access token and the refresh token. Pass the credentials as the HTTP POST request to the EMM Security Server. Ensure that you also include the 
Content Type 
as 
application/x-www-form-urlencoded
 in the POST call. The post request must be sent to the following URL where the EMM Security Server service is available:
ess/security/v1/token
The following table lists the input parameters of the Authentication APIs:
Parameter
Description
Parameter Type
Required
grant_type
Indicates whether you want to enter the password or the refresh token to receive the access token. The possible values are:
  • Password
  • Refresh_Token
form
Yes
username
The username of the authenticating user.
form
Yes, if grant_type=PASSWORD
password
The password of the user. This field is applicable only if the grant_type is set to Password.
form
Yes, if grant_type=PASSWORD
refresh_token
The token that is used to issue a new access token. This field is applicable only if the grant_type is set to REFRESH_TOKEN.
form
Yes, if grant_type=REFRESH_TOKEN
exttoken_requested
Indicates if you want to use the token that an external authentication module issues.
form
No
Authorization
The base64-encoded value of the tenant name.
header
Yes
client_txn_id
The unique identifier to track the transactions.
query
No
The following code snippet provides an example for HTTP POST requests for user authentication:
POST /ess/security/v1/token HTTP/1.1 Host: <host_name>:8080 Authorization: Basic REVGQVVMVE9SRw== Accept-Language: es Cache-Control: no-cache Content-Type: application/x-www-form-urlencoded grant_type=PASSWORD&username=jsmith&password=Wc1205 <host_name> is the FQDN route name of the OpenShift environment.
The following code snippet provides an authentication response example:
{ "userRefID"?: 1, "tkn"?: "a3bdf820-1eaf-47f4-acd6-7caca7fe17d2", "tt"?: "Bearer", "v"?: 1800, "rtkn"?: "22d27b41-c392-41b6-8785-0503b398b4e7", "lc"?: "es" }
The following table explains the response parameters:
Parameter
Description
userRefID
The unique identifier to track the request.
tkn
The access token that must be used for authorization.
tt
The token type. Possible values are:
  • Basic
  • Bearer
v
The period for which the token is valid, if it is not used. The default value for which the token is valid if not in use is 1800 seconds.
rtkn
The refresh token that is used to issue a new access token.
lc
The locale that is used for the session.
Pass the Authorization Details
The access token that you have obtained as the result of the Authentication API must be passed as the 
Authorization
 parameter in the header of API calls. This token indicates that the user is already authenticated. The token therefore eliminates the need for user credentials for successive authentication attempts. Before you pass the token, append the tenant scope to the token, convert this appended string to the base64-encoded format. Now, include this token in the header. The EMM Security Server verifies the incoming request that is based on the token and tenant scope. The EMM Security Server then grants access to the protected resources.
Perform the following steps to pass the authorization details in the API calls:
  1. Construct the string in the following format by using the token and tenant scope:
    {"tkn":"<token>","<tenant_scope_argument>":"<value>"}
    The token that is issued for the user must have scope on the tenants that are specified in
    <tenant_scope_argument>
    .
    The following table lists the possible arguments for tenant scope:
    Argument
    Description
    t
    Specifies that the authorization is for the tenant for which the request is being made. The following code provides an example for the string using this argument:
    { “tkn”:”e03820ae-8732-43b1-b2b5-5a215ee07bd3”,
    “t”:”cohort1” }
    all
     Specifies that the authorization for all the tenants in the user's scope for which the request is being made. The following code provides an example for the string using this argument:
    { “tkn”:”e03820ae-8732-43b1-b2b5-5a215ee07bd3”,
    “all”:true
    }
    Note:
    By default, this value is set to false.
    global
    Specifies that the authorization is for global configurations. The following code provides an example for the string using this argument:
    { “tkn”:”e03820ae-8732-43b1-b2b5-5a215ee07bd3”,
    “global”:true
    }
    Note:
    By default, this value is set to false.
  2. Convert the string to the base64-encoded format. For example, you can use  to perform this conversion.
  3. Include the base64-encoded string in the header of 
    DX Operational Intelligence
     APIs. Refer to the 
    Authorization
     line in the following code:
    GET /ess/security/v1/me HTTP/1.1 Host: <host_name>:8080 Accept: application/json Authorization: Bearer eyJ0a24iOiI4Njc5YzU3Yy02ZWYyLTQ2OTUtOTc3NC0yYjkwNDQwNDQ3ZGYiLCJhbGwiOnRydWV9 Cache-Control: no-cache <host_name> is the FQDN route name of the OpenShift environment.
    You can now use these authorization details to access the protected 
    DX Operational Intelligence
     APIs. The 
    DX Operational Intelligence
     API requests must be posted at 
    /mdo/v2/aoanalytics
    .