7 Obtaining ORDS Service Credentials

ORDS services use OAUTH 2 for authentication. All services are authenticated. What this means in practice is that a short-lived token is used for authentication. That token is generated using a well-known service, which authenticates using basic auth. The basic auth credentials (that is, client id and client secret) are obtained from Retail Home.

For pre-production environments (for example, stage, dev, uat), administrator users for Retail Home must be assigned the following roles (groups) through the authentication provider for the environment:

  • RETAIL_HOME_ADMIN_PREPROD
  • PLATFORM_SERVICES_ADMINISTRATOR_PREPROD
  • PLATFORM_SERVICES_ADMINISTRATOR_ABSTRACT_PREPROD

For production environments, administrator users for Retail Home must be assigned the following roles (groups) through the authentication provider for the environment:

  • RETAIL_HOME_ADMIN
  • PLATFORM_SERVICES_ADMINISTRATOR
  • PLATFORM_SERVICES_ADMINISTRATOR_ABSTRACT

  1. In Retail Home, navigate to Manage OAUTH Clients page by tapping settings (1), then tapping the Application Administration menu item (2), and lastly tapping the Manage OAUTH Clients menu item to arrive at the Manage OAUTH Clients page (4).


    Manage OAUTH Clients page

  2. Tap the + button.


    IDCS OAuth Clients

  3. A popup dialog will appear. Provide an App Name and Description. Leave Scope blank. Tap OK.


    Create OAuth client

  4. A new dialog window will appear with a Display Name, Client ID, and Client Secret. Retain this information. It will not be displayed again. Tap Done when the information has been copied. Note that new credentials can be created at any time and that production, stage, and development will have different credentials.


    new client

Consult Retail Home Application Administration Guide for additional details on managing OAUTH clients.

Note that, the OCI IAM service is rate limited (see API Rate Limits). Best practice is to reuse tokens until they expire (one hour). If you encounter a 429 error when requesting a token or authenticating, you have hit the rate limit. When you encounter a rate limit, back off for one minute to reset the rate limiter.

Before proceeding:

  1. Verify that a client id and secret can be created in Retail Home.

  2. Retain the client id and secret for future use.

Generating an ORDS Access Token

You will need an IDCS Authorization Server endpoint URL and ORDS service credentials to perform the steps described below.

One uses an IDCS Authorization Server to generate an ORDS access token. Two access token generation techniques will be described, curl and POSTMAN. One is likely to use both techniques during the development process.

Generating an Access Token Using cURL

The cURL command for generating an access token has five components:

  1. The IDCS Authorization Server endpoint URL

  2. A content type

  3. An authorization

  4. A grant type

  5. A scope

Only the IDCS Authorization Server endpoint URL and authorization are customer-specific. Content type, grant type, and scope are the same for all customers.

The endpoint URL has the following form:

https://<idcs authorization server host>/oauth2/v1/token

The authorization uses Basic Auth. You will need to base64 encode your Basic Auth credentials using the following format:

clientId:clientSecret

Replace Client ID and Client Secret with credentials obtained using the method described in the 4.3.2 Obtaining ORDS Service Credentials section above. Then use a base64 encoding tool to encode the string.

The cURL command to generate a token is as follows:

curl --location --request \
POST 'https://<idcs authorization server host>/oauth2/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <base64 clientId:clientSecret>’ \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=urn:opc:idm:__myscopes__'

Generating an Access Token Using POSTMAN

Generating is access token in POSTMAN is typically an integral part of calling other services. In this section, we will illustrate the process of generating a token directly and generating it as part of another service invocation. Use the following steps to generate a token directly:

  1. Open POSTMAN and create a new request by clicking on the New button in the top left corner of the screen.

  2. Select HTTP.

  3. In the new request tab, select the POST method from the drop-down menu.

  4. Enter the IDCS Authorization Server endpoint URL in the "Enter request URL" field.

  5. Click the Authorization tab to configure authorization.

  6. In the Type drop-down menu, select Basic Auth.

  7. Enter your username (client id) and password (client secret) in the fields provided.

  8. Next click the Body tab to add the grant type and scope parameters.

  9. In the menu, select x-www-form-urlencoded.

  10. Next enter two key-value pairs:

    Key Value

    grant_type

    client_credentials

    scope

    urn:opc:idm:__myscopes__

  11. Once you have configured your request, click on the "Send" button to execute it.

  12. The response from the service will be displayed in the "Response" section below the request configuration. You can view the response headers and body, as well as any errors or status codes. The response is JSON formatted and should have the following form:

    {
    "access_token": "<token>",
    "token_type": "Bearer",
    "expires_in": 3600
}

  13. You can also save the request for future use by clicking on the "Save" button in the top right corner of the screen and giving it a name.

To use OAuth2 in Postman to invoke a ORDS service, you can follow these steps.

  1. Open POSTMAN and create a new request.

  2. Select the Authorization tab from the top of the request builder.

  3. Select the OAuth 2.0 type from the drop-down menu.

  4. Scroll down to Configure New Token.

  5. Choose a name for the token configuration.

  6. Select client credentials as the grant type.

  7. Enter your IDCS Authoization server endpoint URL, client id, client secret, and scope as you did above.

  8. Set client authentication to Send as Basic Auth Header.

  9. Scroll down to get new access token.

  10. POSTMAN will then display the token details, such as the access token, refresh token, and token expiration time.

  11. Finally, click the Use Token to apply the token to your service.

Before proceeding verify your understanding and validate your ORDS service credentials:

  1. Unless you do not expect to use cURL, verify your that you can generate a token using cURL.

  2. Unless you do not plan to use POSTMAN, then verify your understanding by generating a token using POSTMAN.

  3. More than likely, you do not have an ORDS service with which to test authentication at this point. If you do and you expect to use POSTMAN, then verify your understanding by invoking an ORDS service.