This documentation supports the 21.05 version of BMC Helix Innovation Studio.To view an earlier version, select the version from the Product version menu.

Using authorization REST APIs to consume BMC Helix Single Sign-On

BMC Helix Innovation Studio supports OAuth 2.0 authentication provided by BMC Helix Single Sign-On. For API-based client applications (such as data loading applications) or any other API clients that are integrated with BMC Helix Innovation Studio, you can use the BMC Helix Single Sign-On OAuth 2.0 authentication to interact with BMC Helix Innovation Studio. For information about BMC Helix Single Sign-On OAuth 2.0, see Configuring OAuth 2.0 in the BMC Helix Single Sign-On documentation.

After an application is configured to consume BMC Helix Single Sign-On and when any REST API call occurs, the application receives a token from BMC Helix Single Sign-On and passes the token to BMC Helix Innovation Studio through the HTTP header. BMC Helix Innovation Studio 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 BMC Helix Innovation Studio by performing REST API GET calls on a particular incident management record definition. While performing REST API calls, the client gets a token from BMC Helix Single Sign-On and passes it to BMC Helix Innovation Studio. BMC Helix Innovation Studio then validates the token and allows the client to get the high priority ticket data.

To use BMC Helix Single Sign-On OAuth 2.0 authentication 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

      <authorizationURL>is the URL to the BMC Helix Single Sign-On server.

      Request parameter

      You 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: innovationsuite

      • 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.
      • 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: innovationsuite
      • 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=innovationsuite&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&

      The following tokens are the sample REST call response:

      • 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 BMC Helix Single Sign-On server to BMC Helix Innovation Studio (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.

    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: BMC Helix Innovation Studio Resource URL.
      For example, http://<localHostName>:8008/api/rx/application/record/recorddefinition/com.bmc.arsys.rx.foundation%3AAgent
    • Request header: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1MDcyMTY3NzYsImlzcyI6Imlubm92YXRpb25zdWl0ZSIsImV4cCI6MTUwNzIxNzM3NiwianRpIjoiYWQ5MDMyZTEtYTAxNC00MWU1LWE5ODctNDQyN2QyODM3NDM3Iiwic3ViIjoiYWRtaW4iLCJyZWFsbSI6IioiLCJ0ZW5hbnRJZCI6IiIsInRva2VuVHlwZSI6ImFjY2Vzc1Rva2VuIn0.VhL0ap-HUiVQcXak3MMHlPN-HYKQmpai3AkGSh3Du0qh7jwF13yliVnMPUlQBGz0HlFZRGX3blMSxneaKJLaj_aLN-AMYMxPURNcy_LwPzTvp9pUyk0quN1iY7ZSjd5A2DNejVOBAXo_kSsmgDoW5_MXLih73d6XU-8VOpsywqY8vNj56JgVE4eT1Z2r7s480OLIvwUDeJfZAbGrD567XsWYAvDaTD7Gy5ieK9lFCrIviCqkjXDRqpDo-XolxClOvJe0pzM0gwKJfXx_9xqwq2i7GQ9nlegBHxkal1KHYLB8-eRGIO1Wpqd3CwYhI96RzoBYw256thkjZNLV4RrjuQ

    The following is a sample JSON response of the sample REST call:

    {
    "resourceType": "com.bmc.arsys.rx.services.record.domain.RegularRecordDefinition",
    "version": "0",
    "lastUpdateTime": "2017-08-29T11:48:40.000+0000",
    "lastChangedBy": "ARSERVER",
    "owner": "com.bmc.arsys.rx.foundation",
    "name": "com.bmc.arsys.rx.foundation:Agent",
    "tags": null,
    "description": null,
    "overlayGroupId": "0",
    "developerId": "com.bmc.arsys",
    "scope": "PUBLIC",
    "guid": "6cf135d208bc89478be8d9cc8c2e65b3",
    "fieldDefinitions": [
    ………..
    ………..
    }

Related topic

BMC Helix Single Sign-On in BMC Helix Single Sign-On documentation.

 

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