Default language.

Enabling OAuth authorization for Remedy AR System REST APIs

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.

Remedy Single Sign-On 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.

For API-based client applications (such as data loading applications) or any other API clients that are integrated with Remedy AR System server, you can use the Remedy SSO OAuth 2.0 authentication to interact with Remedy AR System server. For information about the Remedy SSO OAuth 2.0, see Configuring OAuth 2.0 authenticationin the Remedy Single Sign-On online documentation portal.

After an application is configured to consume Remedy SSO and when any REST API call occurs, the application receives a token from the Remedy SSO server and passes the token to Remedy AR System server through the HTTP header. Remedy AR System server 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 Remedy AR System server by performing REST API GET calls on a particular entries. While performing REST API calls, the client gets a token from the Remedy SSO server and passes it to Remedy AR System server. The Remedy AR System server 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 Remedy AR System server with Remedy Single Sign-On. For more information, see Integrating Remedy SSO with BMC Remedy AR+Systemin the Remedy Single Sign-On online documentation portal.

Architecture

The application (client) needs to register with the authorization server (Remedy Single Sign-On) 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 Remedy Single Sign-On. Once the access is granted, the client uses the credentials to register with Remedy Single Sign-On. Remedy 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 to the Remedy AR System server. Once Remedy AR System server recognizes the access token and Remedy Single Sign-On validates the token, Remedy AR System server sends the user related information to the client.call

OAuth2_authentication_architecture.jpg

To use Remedy SSO OAuth 2.0 authorization in your application

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

  1. Configure your application to get the OAuth 2.0 token from the Remedy SSO 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 Remedy SSO 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://app.getpostman.com/oauth2/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>
      <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.
    • 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://app.getpostman.com/oauth2/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 Remedy SSO server to Remedy 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.

    The following sample shows the REST call:

    • REST API URL: Remedy 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 Remedy Single Sign-On (RSSO) installed, you can use the RSSO_Oauth2 authentication scheme through the Swagger UI. The following process explains how to access AR 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 Remedy SSO 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 Remedy SSO Console

  1. Register the Swagger UI as a Remedy SSO client in the Remedy SSO Console. For more information, seeOAuth Client Authentication.
    image2019-2-18_8-52-3.png

  2. On the Remedy SSO 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.

Related topics

Access-and-authentication-for-the-REST-API

General-principles-for-using-the-REST-API


 

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