Enabling OAuth authorization for AR System REST APIs

You can enable the OAuth authorization only for on-premises BMC Helix SSO deployments.

The REST API authentication uses a token that is valid for a configurable amount of time and acts as a temporary password. After a token expires, you must generate a new token.

BMC Helix Single Sign-On is the OAuth 2 provider, which returns an access token and a refresh token. The access token is valid for a shorter duration, the refresh token has a longer expiration time. When the access token expires, you can use the refresh token to get a new access token.

Related topics

Configuring OAuth 2.0 in BMC Helix SSO documentation

Configuring authentication in BMC Helix SSO documentation

For API-based client applications (such as data loading applications) or any other API clients that are integrated with the AR System server, you can use the BMC Helix Single Sign-On OAuth 2.0 authentication to interact with the AR System server. 

For information about the BMC Helix Single Sign-On OAuth 2.0, see Configuring OAuth 2.0 in the BMC Helix Single Sign-On online documentation portal.

After an application is configured to use the BMC Helix Single Sign-On and when any REST API call occurs, the application receives a token from the BMC Helix Single Sign-On server.  The BMC Helix Single Sign-On server passes the token to AR System server through the HTTP header. AR System server then uses the token to  authenticate a user and permit operations based on the user's privileges.

For example, an API-based client generates report of open high priority tickets. The client fetches the  high priority ticket data from AR System server by performing REST API GET calls. While performing REST API calls, the client gets a token from the BMC Helix Single Sign-On server and passes it to AR System server. The AR System server then validates the token and permits the client to get the high priority ticket data based on the user's privileges.

Use the information in the following sections to enable OAuth authentication:

Before you begin

Integrate AR System server with BMC Helix Single Sign-On. For more information, see Getting started in the BMC Helix Single Sign-On online documentation portal.

Architecture

You must register the application (client) with the authorization server (BMC Helix Single Sign-On) so that the application can create an authorization request. For this, the client sends an authorization request to the user who must have an account to register with BMC Helix Single Sign-On. After the access is granted, the client uses the credentials to register with BMC Helix Single Sign-On. BMC Helix Single Sign-On then grants the authorization and sends the access token (default value is 60 minutes) and refresh token (default value is 60 days) to the client. The client uses the access token to make a REST API call to the AR System server. After the AR System server recognizes the access token and BMC Helix Single Sign-On validates the token, AR System server sends the user related information to the client call.

221_EnablingOAuth.png

To use BMC Helix Single Sign-On OAuth 2.0 authorization in your application

You can use BMC Helix Single Sign-On OAuth 2.0 authentication in your application only when BMC Helix Single Sign-On is configured for your applications.

  1. Configure your application to get the OAuth 2.0 token from the BMC Helix Single Sign-On server by using the following REST API calls:

    REST API call for authorization request:

    Request

    Description

    Request type

    GET <authorizationURL>/oauth2/authorize
    where <authorizationURL> is the URL to the BMC Helix Single Sign-On server.

    Request parameter

    Specify the following parameters in the request:

    • Response Type: CODE <default value, implicitly set>
    • Client ID: <clientID> must correspond to the client ID specified in the registeredclient table.
    • Call back URL: <redirectURI> must correspond to the redirect URI specified in the registeredclient table.
    • Scope: <scope> Optional parameter
    • State: <state> Optional parameter

    Response output

    Authorization Code

    The following sample shows a REST call:

    • REST API URL: http:// <localHostName> :<portNumber>/rsso/oauth2/ authorize
    • Client ID: <clientID>

    • Redirect URI:  https://oauth.pstmn.io/v1/callback
      The following response shows the sample REST call:

      code=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MDcyNzUzMTgsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzI3NTQ5OCwianRpIjoiMDJlMjAyMmItOTI2My00MDNhLThhNjMtNGQ2ZDQ4NWY4ODJjIiwic3ViIjoiYWRtaW4iLCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6ImF1dGhvcml6YXRpb25Db2RlIn

    REST API call for access token request:

    Request

    Description

    Request type

    POST <authorizationURL>/oauth2/token

    Request parameter

    Specify the following parameters in the request to get access token:

    • Grant Type: AUTHORIZATION CODE <default value. Implicitly set>
    • Client ID: Client ID <clientID> Registers the client identifier issued to the client by BMC Helix SSO server during the registration process.
      You can see this information when you select the registered client, and click to view its details.
      <clientID> must correspond to the client ID specified in the registeredclient table. You must specify the client ID that is specified in the REST call for authorization request.
      Register the client identifier issued to the client by BMC Helix SSO server during the registration process. You can view this information when you select the registered client, and click to view its details.
    • Authorization Code: Specify the authorization code that is retrieved in the response of the REST API call for authorization request.
    • Redirect URI: Redirect URI <redirectURI>
      <redirectURI> must correspond to the redirect URI specified in the registeredclient table.
      You must specify the redirect URI that is specified in the REST API call for authorization request.

    Specify the following parameters in the request to get new access token by providing a refresh token:

    • Grant Type: refresh_token
    • Client ID: <clientID> must correspond to the client ID specified in the registeredclient table. You must specify the client ID that is specified in the REST call for authorization request.
    • refreshToken: <refreshTokenValue>

    Response output

    Access token and refresh token.

    The following sample shows the REST call:

    • REST API URL: http:// <localHostName> :8080/rsso/oauth2/token
    • Client ID: Client ID <clientID>
    • Redirect URI:  https://oauth.pstmn.io/v1/callback
    • access_token:
      • ad9032e1-a014-41e5-a987-4427d2837437
    • refresh_token:
      • 3483f054-a9ab-4722-beb0-e9b06e3f0345

  2. Configure your application to send the token received from the BMC Helix Single Sign-On server to AR System server (through HTTP header) by using the following REST API call for access to resource request:

    Request

    Description

    Request type

    GET <resourceServerURL>
    POST <resourceServerURL>

    Request header

    Authorization: Bearer <bearerValue>
    You must specify the access token that is retrieved in the REST call of access token request.

    Note: If you are using the PUT or POST method, add the X-Requested-By header and set the value of XMLHttpRequest to that header.


    Response output

    Access to a resource in the resource server in the form of JSON response:

    • REST API URL: AR System REST API GET entry URL. 
      For example: http://<server_name>:<port>/api/arsys/v1/entry/HPD:IncidentInterface_Create/Incident Number
    • Request header: Bearer
      ad9032e1-a014-41e5-a987-4427d2837437

Using the RSSO_Oauth2 authentication with Swagger UI

If you have BMC Helix Single Sign-On (BMC Helix Single Sign-On) installed, you can use the RSSO_Oauth2 authentication scheme through the Swagger UI. Perform the following steps to access AR System REST APIs through OAuth2 authentication:

image2019-2-18_13-18-28.png

For more information, see Using-the-REST-API-with-Swagger.

Before you begin

Make sure that the cross-domain requests are permitted on the BMC Helix Single Sign-On server.

You can enable the cross-domain requests on Apache Tomcat. For more information, see https://tomcat.apache.org/tomcat-7.0-doc/config/filter.html#CORS_Filter.

If cross-domain requests are not enabled, an error occurs. 

Refer to the following code sample to enable to cross-domain requests:

To add the CORS filter, edit the web.xml file located in the TOMCAT_HOME/conf folder.

<filter>
 <filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
 <init-param>
   <param-name>cors.allowed.origins</param-name>
   <param-value>http://<Swagger Tomcat Hostname or IP>:<></param-value>
 </init-param>

 <init-param>   
<param-name>cors.allowed.methods</param-name>   
<param-value>GET,POST,PUT,DELETE,OPTIONS</param-value>
 </init-param>

 <init-param>   
<param-name>cors.exposed.headers</param-name>   
<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
 </init-param>

 <init-param>   
<param-name>cors.support.credentials</param-name>
   <param-value>true</param-value>
 </init-param>
</filter>

<filter-mapping>
 <filter-name>CorsFilter</filter-name>
 <url-pattern>/*</url-pattern>
</filter-mapping>

To register clients in the BMC Helix Single Sign-On Console

  1. Register the Swagger UI as a BMC Helix Single Sign-On client in the BMC Helix Single Sign-On Console.
    For more information, see Configuring OAuth 2.0.
    image2019-2-18_8-52-3.png

  2. On the BMC Helix Single Sign-On Console, in the Redirect URI box enter the following URL:
    http://<Swagger Tomcat Host Name or IP address>:<Tomcat HTTP port>/swagger-ui/oauth2-redirect.html
    The default port is 8080.
    image2019-2-18_8-57-47.png

    Best Practice
    Use Localhost in the redirect URL. Use the Host Name or IP address of the computer where Swagger is running.

  3. Click Save.
  4. Copy the ClientSecret.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*