This documentation supports the 18.08 version of Remedy Action Request System.

To view the latest version, select the version from the Product version menu.

Enabling OAuth authentication by the REST API with Remedy Single Sign-On integrated

From version 18.08, the Remedy REST API supports OAuth authentication when integrated with Remedy Single Sign-On.

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 serverFor information about the Remedy SSO OAuth 2.0, see  Configuring OAuth 2.0 authentication in 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+System in 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 call 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.


To use Remedy SSO OAuth 2.0 authentication 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:

    RequestDescription
    Request typeGET <authorizationURL>/oauth2/authorize
    where <authorizationURL> is the URL to the Remedy SSO server.
    Request parameterYou must provide the following parameters in the request:
    • Response Type: CODE <default value, implicitly set>
    • Client ID: Client ID <clientID>
      <clientID>must correspond to the client ID specified in the registeredclient table.
    • Redirect URI: Redirect URI <redirectURI>
      <redirectURI> must correspond to the redirect URI specified in the registeredclient table.
    • Scope: Optional parameter
    • State: Optional parameter
    Response output

    Authorization Code

    The following sample shows a REST call:

    • REST API URL: http://<localHostName>:8080/rsso/oauth2/authorize
    • Client ID: 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:

    RequestDescription
    Request typePOST <authorizationURL>/oauth2/token
    Request parameterYou 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.
    • Secret: secret <secretValue>
      <secretValue> must correspond to the secret value specified in the registeredclient table.
    • 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: 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.
    • Secret: secret <secretValue>
      <secretValue> must correspond to the secret value specified in the registeredclient table.
    • 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>
    • Secret: secret3
    • Redirect URI: https://app.getpostman.com/oauth2/callback
      The complete URL is as follows:

      http://<localHostName>:8080/rsso/oauth2/token?grant_type=authorization_code&client_id=<clientID>&client_secret=secret3&code=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MDcyNzU3NDksImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzI3NTkyOSwianRpIjoiYmQ0MTgwZTMtMzEzNy00ZjI3LWFmODUtODJkOGE1Y2YzODExIiwic3ViIjoiYWRtaW4iLCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6ImF1dGhvcml6YXRpb25Db2RlIn0.o33KLHWsdmPZwCCnCuBFWeOZpgS153ATBqEXjE0lLDVMygAHXD8hf4Rc0QleI7bmSOrDnHYFjIZR2-OlSwiDlCpwxAlCvD4AXAmrK3Nimt7py9fm_FvsDQ5NpMjy91uMhGBAug3VvZJagb9YfeSPfBEsU8UAp4hU85qkR89Yn6gTKr4oQ2EV2PO__bglE36faSXKO7Wdes9jn96f-cYsebRzesdKzg-NpaTuKfOC70h4xVrFj-ZLiVYVSJawuJf-Ws-7g8s1gDYroSdExS55NaPi6Mtpfht1A8jZMo1_fywCCD9b7ydz5IPZNiVSBpCAcrEL1VHl2HKvqUwPVPVrZw&redirect_uri=https%3A%2F%2Fwww.getpostman.com%2Foauth2%2Fcallback&
    • access_token:

      eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MDcyMTY3NzYsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzIxNzM3NiwianRpIjoiYWQ5MDMyZTEtYTAxNC00MWU1LWE5ODctNDQyN2QyODM3NDM3Iiwic3ViIjoiYWRtaW4iLCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6ImFjY2Vzc1Rva2VuIn0.VhL0ap-HUiVQcXak3MMHlPN-HYKQmpai3AkGSh3Du0qh7jwF13yliVnMPUlQBGz0HlFZRGX3blMSxneaKJLaj_aLN-AMYMxPURNcy_LwPzTvp9pUyk0quN1iY7ZSjd5A2DNejVOBAXo_kSsmgDoW5_MXLih73d6XU-8VOpsywqY8vNj56JgVE4eT1Z2r7s480OLIvwUDeJfZAbGrD567XsWYAvDaTD7Gy5ieK9lFCrIviCqkjXDRqpDo-XolxClOvJe0pzM0gwKJfXx_9xqwq2i7GQ9nlegBHxkal1KHYLB8-eRGIO1Wpqd3CwYhI96RzoBYw256thkjZNLV4RrjuQ
    • refresh_token:

      eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MDcyMTY3NzYsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzIyMDM3NiwianRpIjoiMzQ4M2YwNTQtYTlhYi00NzIyLWJlYjAtZTliMDZlM2YwMzQ1Iiwic3ViIjoiYWRtaW4iLCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6InJlZnJlc2hUb2tlbiJ9.V_SCSd6KuWTOHj7274ry8Ndqs6B_g_EA0Qei9NEpxDMc0BJj2XvCzIZ6f4zdEwcaWVrbHCuslUwFrkTIXFqL9TjGQ_10vJEqTqK1g0RBXj3W68Ex89noB46kB0Wm5_7tQ2H4WKFOJCpXyb6OP8O0fk0IuQ0zY56XVSQsKK6kAOEJy_xV25oOCaC_wvzyaVuZiWbWXNukWloRugys5KyruGyg9hf25shspD0eMLQZrxAPhjSneZTCeID_ofa83H6VO_EQTGVxiOQ0dhA7qw8Aziwr9bV_hy5W-8U8VRdUcPaxgtezQqHKTV_NLsrHTkXt6w0v7rwIreg5ONM0nIaJAw
  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:

    RequestDescription
    Request typeGET <resourceServerURL>
    POST <resourceServerURL>
    Request headerAuthorization: Bearer <bearerValue>
    You must specify the access token that is retrieved in the REST call of access token request.
    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 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MDcyMTY3NzYsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzIxNzM3NiwianRpIjoiYWQ5MDMyZTEtYTAxNC00MWU1LWE5ODctNDQyN2QyODM3NDM3Iiwic3ViIjoiYWRtaW4iLCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6ImFjY2Vzc1Rva2VuIn0.VhL0ap-HUiVQcXak3MMHlPN-HYKQmpai3AkGSh3Du0qh7jwF13yliVnMPUlQBGz0HlFZRGX3blMSxneaKJLaj_aLN-AMYMxPURNcy_LwPzTvp9pUyk0quN1iY7ZSjd5A2DNejVOBAXo_kSsmgDoW5_MXLih73d6XU-8VOpsywqY8vNj56JgVE4eT1Z2r7s480OLIvwUDeJfZAbGrD567XsWYAvDaTD7Gy5ieK9lFCrIviCqkjXDRqpDo-XolxClOvJe0pzM0gwKJfXx_9xqwq2i7GQ9nlegBHxkal1KHYLB8-eRGIO1Wpqd3CwYhI96RzoBYw256thkjZNLV4RrjuQ

Related topics

Tools for testing the REST API

Login information

API use cases

General REST API guidelines

Was this page helpful? Yes No Submitting... Thank you

Comments