×
 
 

 

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

To view an earlier version, select the version from the Product version menu.

BMC Remedy Action Request System 19.08 ... Developing an API program Integrating AR System forms with a third-party application by using REST API

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 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 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


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: <clientID> must correspond to the client ID specified in the registeredclient table.
    • Client secret: <Client secret> must correspond to the client secret specfied 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:

    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: <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> 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: <secretValue>

    • 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:

    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
      ad9032e1-a014-41e5-a987-4427d2837437

Related topics

Testing AR System REST API

Authentication and permissions in the REST API

Use cases for integrating AR REST API with an external form

General principles for using the REST API

Was this page helpful? Yes No Submitting... Thank you
Last modified by Anagha Deshpande on Apr 23, 2020

Comments

Authentication and permissions in the REST API
Testing AR System REST API
© Copyright 1991-2021 BMC Software, Inc. © Copyright 1991-2021 BladeLogic, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2021 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.