Default language.

Enabling OAuth authorization for AR System REST APIs

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

The Remedy 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 need to generate a new token.

 is the OAuth 2 provider, which returns an access token and a refresh token. Even if the access token is of 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 , you can use the  OAuth 2.0 authentication to interact with .  For information about the  OAuth 2.0, see Configuring OAuth 2.0 in the  online documentation portal.

After an application is configured to consume  and when any REST API call occurs, the application receives a token from the  server and passes the token to  through the HTTP header.  then uses the token to  authenticate a user and allow the 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  by performing REST API GET calls  on a particular entries. While performing REST API calls, the client gets a token from the  server and passes it to . The  then validates the token and allows the client to get the high priority ticket data based on the user's privileges.

The following sections explain how you can enable OAuth authentication.

Before you begin

Integrate  with . For more information, see Getting started in the  online documentation portal.

Architecture

The application (client) needs to register with the authorization server () so that the application can create an authorization request. For this, first, the client sends an authorization request to the user who needs to have an account to register with . Once the access is granted, the client uses the credentials to register with .  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 to the . Once  recognizes the access token and  validates the token,  sends the user related information to the client.call

OAuth2_authentication_architecture.jpg

To use  OAuth 2.0 authorization in your application

You can use  OAuth 2.0 authentication in your application only when  is configured for your applications.

  1. Configure your application to get the OAuth 2.0 token from the  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  server.

    Request parameter

    You must provide 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

    You must provide 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 view 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.
      Registers 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.

    You must provide 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  server to  (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:  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  (RSSO) installed, you can use the RSSO_Oauth2 authentication scheme through the Swagger UI. The following process explains how to access  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 allowed on the  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 loacted 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  Console

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

  2. On the  Console, in the Redirect URI text 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 shown in the pop-up.


 

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