AWS API Authentication Service

Authentication

Your 47Lining Enterprise PaaS - Adoption Catalyst uses Amazon Cognito for Authentication and Authorization. The process begins by passing in your credentials and authorization tokens are generated for you to use in all your subsequent requests.

Authenticate using Adoption Catalyst Portal

You can use your username and password to log into your 47Lining Adoption Catalyst Portal. When you are logged in, you can obtain the access token needed to initiate OSDU Data Platform API calls from the Portal. When logged into the Portal, click on arrow in upper right of screen next to user name and select "Copy Token". This will copy a string of format bearer <ACCESS_TOKEN> onto your clipboard. You can use this string directly in the authorization headers of Data Platform API calls, or you can strip the leading "bearer " to set the ACCESS_TOKEN environment variable used in the scripts in the next section and the API usage examples elsewhere within this User Guide.

export ACCESS_TOKEN='<paste-token-here-inside-single-quotes>'
# do not include leading "bearer " authentication type inside single quotes

Authenticate Using Command Line or Programatically

In certain cases, you may need to generate tokens using your credentials in an automated fashion.

To use this method, you will need the application client information (APP_CLIENT_ID, APP_CLIENT_SECRET) and Cognito User Pool ID for your subscription. You can obtain these by creating a support ticket using 47Lining Enterprise PaaS Support.

The first step is to generate tokens from Cognito. The Cognito endpoint InitiateAuth takes your user credentials and app client credentials and returns tokens that are used in subsequent steps. Learn more: Cognito InitiateAuth.

The pre-step to authenticating is to generate a SECRET_HASH value. The secret hash is generated using your username together with the application client id and application client secret used in your 47Lining Adoption Catalyst subscription.

export COGNITO_USER_NAME="your username"
export APP_CLIENT_ID="your subscription's app client id"
export APP_CLIENT_SECRET="your subscription's app client secret"
echo -n ${COGNITO_USER_NAME}${APP_CLIENT_ID} | openssl dgst -sha256 -hmac ${APP_CLIENT_SECRET} -binary | base64

You should create an initiate.json file to use. In this example, it is in a config sub-directory. Ensure the values match your information.

config/initiate.json

{
    "AuthParameters" : {
        "USERNAME" : "YourUser",
        "PASSWORD" : "YourPassword",
        "SECRET_HASH":"Computed Base64 Hash Value"
    },
   "AuthFlow" : "USER_PASSWORD_AUTH",
   "ClientId" : "Cognito app client ID",
   "UserPoolId": "Cognito user pool ID"
}

Send the authentication request payload to the Amazon Cognito endpoint for the AWS Region where your Adoption Catalyst subscription is deployed:

export AWS_REGION=us-east-1
curl -X POST -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' -H 'Content-Type: application/x-amz-json-1.1' \
-d @config/initiate.json \
 https://cognito-idp.${AWS_REGION}.amazonaws.com > initiateAuth-response.json

This will populate the file initiateAuth-response.json with this formation and similar content:

initiateAuth-response.json

{
    "AuthenticationResult": {
        "AccessToken": "abcxyz",
        "ExpiresIn": 1800,
        "IdToken": "defuvw",
        "RefreshToken": "ghijkl",
        "TokenType": "Bearer"
    },
    "ChallengeParameters": {}
}

In the subsequent data platform API calls, the AccessToken will be used within the authorization header.

You can set an environment variable that can be used to construct the authorization header required for HTTP requests:

export ACCESS_TOKEN=`cat initiateAuth-response.json |jq '.AuthenticationResult.AccessToken' | sed 's/"//g'`

The script auth.sh, shown below, can also be used to set the envrionment variable in a more automated manner if desired:

auth.sh

#!/bin/bash

curl -X POST --data @config/initiate.json  \
 -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
 -H 'Content-Type: application/x-amz-json-1.1' \
 https://cognito-idp.us-east-1.amazonaws.com > initiateAuth-response.json

unset ACCESS_TOKEN
export ACCESS_TOKEN=`cat initiateAuth-response.json |jq '.AuthenticationResult.AccessToken' | sed 's/"//g'`

Refesh Authentication Tokens

Once authenticated, tokens typically last for 60 minutes. Once they expire, they can be refreshed for typically up to 30 days. To obtain refreshed tokens, you can call the same initiateAuth endpoint, providing user authentication information including the REFRESH_TOKEN that was returned by the initial authentication process. The same mechanism demonstrated in this refresh.sh script can be used in your own scripts and services prior to calling data platform endpoints, to be sure the tokens are up to date and current.

Obtain Refresh Token from Initial Authentication Response

#!/bin/bash

unset  REFRESH_TOKEN
export REFRESH_TOKEN=`cat initiateAuth-response.json |jq '.AuthenticationResult.RefreshToken' | sed 's/"//g'`

Create Body for Refresh Request

config/refresh.json

{
   "AuthParameters" : {
      "REFRESH_TOKEN" : "Refresh Token generated during original authentication, now in ${REFRESH_TOKEN}"
   },
   "AuthFlow" : "REFRESH_TOKEN_AUTH",
   "ClientId" : "Your Cognito ClientId",
   "UserPoolId": "Your Cognito UserPoolId"
}

Invoke Refresh Request and Obtain New Access Token

refresh.sh

#!/bin/bash

curl -s -X POST --data @config/refresh.json \
-H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
-H 'Content-Type: application/x-amz-json-1.1' \
https://cognito-idp.us-east-1.amazonaws.com > initiateAuth-refresh.json

unset ACCESS_TOKEN
export ACCESS_TOKEN=`cat initiateAuth-refresh.json |jq '.AuthenticationResult.AccessToken' | sed 's/"//g'`