Skip to content

Authentication and Token Generation for API usage

Copyright IBM Corporation and GTD Solution Inc. 2018, 2021

This procedure is needed for systems integrating with the TradeLens platform, for example, a system user (program code) that calls the APIs.

Notes:

  • Important: If you have been onboarded onto a different stack than "platform", replace "platform" with your stack name, for example "maersk", in any of the URLs below that have "platform" in the domain.
  • Due to continuous enhancements, some of the functions and screen images might be different than what you see on the current level of TradeLens.
  • The URLs could change in the future; it is recommended that you use environment variables.

Glossary

Cloud IAM: The IBM Cloud Identity and Access Management service used to manage user logins, see https://cloud.ibm.com/docs/account?topic=account-iamoverview. A user logs into cloud IAM and receives a token they can use to prove their identity.

Solution Authorizer: This is a TradeLens service used to track provisioned (onboarded) organizations in the TradeLens platform. Each organization has a set of permissions allowing it to take certain actions within TradeLens applications. Users are associated with any number of orgs and when they use the Solution Authorizer they are granted a Solution Token (or bearer token) that identifies them as a member of one organization. The bearer token is then supplied to the platform to authenticate the user as a member of that organization.

Organization: A entry in the Solution Authorizer/Registry representing a company, port authority, national customs authority, and more, that tracks what operations the organization is allowed to perform in TradeLens applications. When a user is onboarded into TradeLens, TradeLens will create an Organization for them and store the organizationId in the Solution Registry. Members of the company that organization represents will be able to obtain a Solution Token from the Solution Authorizer and use that token as the bearer token when calling the TradeLens APIs.

Access token: The name of the token returned when logging into Cloud IAM. This is an intermediary token that is passed to Solution Manager in order to retrieve the final bearer token.

Bearer token: A token placed in the header of an HTTP request to authenticate and identify the user making the request. A user of the TradeLens platform obtains a bearer token from Solution Authorizer that identifies them as belonging to a particular organization (Solution Authorizer calls this the "solution_token" when it is returned to the user).

Overview

In order to use the TradeLens platform application to call any of the API endpoints as a system user with program code, the platform requires you to log into an identity service called Solution Authorizer. Solution Registry/Authorizer keeps track of organizations that have been provisioned for TradeLens, meaning that members of the organization are allowed to use the platform APIs. Once you have logged in, Solution Authorizer grants you a "solution_token" (to be used as the bearer token), a string that identifies who the user is. You then pass this bearer token in a header for all your API calls to the platform.

Logging into Solution Authorizer is a two-step process. You must first obtain an "access token" from another identity service known as "Cloud IAM". Then you call an endpoint in the Solution Authorizer API where you pass the access token as a parameter and receive a solution token that you use as the bearer token. This separation of the login process is done to keep the list of users (managed by Cloud IAM) separate from the list of organizations (managed by Solution Authorizer).

If you are using the APIs through Swagger for testing, the authentication process is handled for you through your login. See the API Documentation section for more details.

System user details

The case for a system user or application (block of code) to log in has two major differences from a human user logging in. First, whereas the human user has redirects to hide the two-step process of Cloud IAM → Solution Authorizer, a piece of code logging in has to manage the Cloud IAM step itself. Second, rather than a username and password, the application will only have a single key known as the API key that it will provide to Cloud IAM. This API key is associated with a Service ID, and this Service ID is associated with an organization in TradeLens. Having the API key is sufficient credentials to log in as a system user that is a member of the given organization. The user code calls the Cloud IAM login endpoint ".../identity/token", supplying the API key as a parameter. This returns an access token. The user code then calls the ".../sa/api/v1/auth/exchange_token/organizations/{organizationId}", providing the organizationId to which the user code intends to log in and the access token received from Cloud IAM. Solution Authorizer will return a solution token that will be used as the bearer token to identify the system user as a member of the chosen organization. The user code is responsible for storing this token and putting it into the authorization header of all HTTPS calls made to the APIs.

Note: Prior to 4/23/2021, the URL to obtain the solution token (bearer token) was ".../v1/iam/exchange_token/solution/{solutionId}/organization/{organizationId}", where the solutionId was "gtd-sandbox" for the sandbox zone and "gtd-prod" for the production zone. This old URL will be supported for a limited time to allow organizations to transition their code to using the new URL ".../sa/api/v1/auth/exchange_token/organizations/{organizationId}".

Procedure

High level summary of steps:

  1. Create a service ID and create an API key
  2. Create a system user - this connects the API key with system user
  3. Use the API key to generate the IAM access token
  4. Use the IAM access token as a body to generate the Solution Authorizer solution token
  5. Use the Solution Authorizer solution (bearer) token to publish, subscribe, or query
  6. Handle Solution Authorizer solution token expiration: before calling TradeLens APIs, check for expiration of the Solution Manager token, and if expired, go back to step 3

Note: The steps for getting the bearer token are detailed below. Steps 3-5 are for illustration purposes and use a posting mechanism to show the flow. However, you will most likely use code to perform steps 3-5 in your application and automate the process of getting an initial token, getting a new token if it has expired, and calling the APIs with the token. Here is some sample code (provided "AS IS" without warranty) that models this behavior: exampleSolutionAuthorizerService.zip.

The sample code above (exampleSolutionAuthorizerService.zip) contains additional comments regarding the public key, jwks, and PEM.

Detailed steps:

  1. Create a Service ID. If you already have a Service ID, skip to step 2.

    Note: The user that is creating the Service ID must be registered with IBM Cloud at https://cloud.ibm.com/registration/ in order to use the IAM service. An organization can have multiple Service IDs, but it is a best practice to not use the same Service ID for more than one organization.

    • Navigate to https://cloud.ibm.com/login and sign in with your IBMid. If you do not have an IBMid, you can sign up here.

    • Click Manage in the top menu, then select Access (IAM). Token Generation2a

    • Select Service IDs on the left and click the Create button. Token Generation7c

    • Enter a name and description. Click the Create button. Token Generationa7c

    • Important: Copy and Save the "ServiceId" value displayed by clicking Details near the top right of the screen, for example: "ServiceId-b93c3524-3846-497f-a568-087a3b6e5ad6". The Service ID is used as a System User in the User Management section for TradeLens. We will show this in step 2. Token Generationb7c Token Generationc7c

    • Click the API keys tab and then click the Create button. Token Generation8c

    • Enter a name and description. Click the Create button. Token Generation10c

    • Important: Copy or Download the API key and save it. The API key is used to get an access token from Cloud IAM. We will show this in step 3. Token Generation11c

    • After you have saved the API key, close the dialog box.

  2. Create a system user using the Service ID from step 1. If you have previously created the system user in TradeLens and associated it with your Service ID, you can skip this step. The system user can be created by an admin for your organization from the User Management UI, or through the APIs. This step connects the Service ID and API key to Solution Authorizer for your organization. Note: At least one Admin ID will be created during the provisioning (onboarding) process for your organization. Additional Admin IDs can be created from an existing Admin ID.

    • Log into TradeLens with your Administrator ID on Sandbox ( https://platform-sandbox.tradelens.com ) or Production ( https://platform.tradelens.com ) to access the Shipment Manager (SM) UI. Click on Account, then click on User Management, then click on Add New User. Token Generation4i Token Generation5g

    • In the "Add A New User To Your Organization" popup window:

      1. Enter the Service ID that was created from the Cloud IAM Service ID process (enter the entire Service ID, including the "ServiceId-" portion).

        Note: An organization can have multiple Service IDs, but it is a best practice to not use the same Service ID for more than one organization.

      2. Enter a brief description for the User Name and optional reason for adding the user.

      3. You can also select the Administrator checkbox if this Service ID will be used as an administrator (for example to call APIs that are only available to Administrators; this is probably not common for program code to do this).

      4. Submit the request by clicking Add New User. Token Generation6d

  3. Get an access token from Cloud IAM. Use the API key that was created as part of the Service ID process in step 1, or one that you had created before.

    • Send this request:
      POST https://iam.cloud.ibm.com/identity/token
      Header: Content-Type: application/x-www-form-urlencoded
      Body: grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=your_api_key

      For example (Note: raw was selected in the image below to show the body, but x-www-form-urlencoded should be selected when sending the request): Token Generation12c

    • Expect a response like:
      {
      "access_token": "ABC....",
      "refresh_token": "not_supported",
      "token_type": "Bearer",
      "expires_in": 3600,
      "expiration": 1520976069,
      "scope": "ibm openid"
      }

      For example: Token Generation13d

  4. Get an exchange token from Solution Authorizer.

    You will need to know your organization ID. The organizationId was provided to you as part of the TradeLens provisioning process (if you are an organization admin, you can also find your organizationId from the Shipment Manager UI User Management section), for example: 98e2f3cc-e801-4a34-9eef-e4b2e3a65ff1.

    Using your organization ID:

    • Send this request, where Solution_Authorizer_domain is: https://platform-sandbox.tradelens.com/ for Sandbox, and https://platform.tradelens.com/ for Production:
      POST https://Solution_Authorizer_domain/sa/api/v1/auth/exchange_token/
      organizations/organization_id
      Header: Content-Type: application/json
      Body: contents_from_response_cloud_iam_in_previous_step in raw format

      For example: Token Generation14e

    • Expect a response that includes the solution_token.

      For example: Token Generation15d

    Note: Prior to 4/23/2021, the URL to obtain the solution token (bearer token) was
    "Solution_Manager_domain/onboarding/v1/iam/exchange_token/solution/{solutionId}/
    organization/{organizationId}", where the solutionId was "gtd-sandbox" for the sandbox zone and "gtd-prod" for the production zone. This old URL will be supported for a limited time to allow organizations to transition their code to using the new URL
    "Solution_Authorizer_domain/sa/api/v1/auth/exchange_token/organizations/
    {organizationId}", where Solution_Authorizer_domain is "https://platform-sandbox.tradelens.com" for example for the Platform stack Sandbox environment.

  5. To call the TradeLens APIs, use the Solution Authorizer solution token from step 4 by setting it in the Authorization header as ”Bearer Solution_Authorizer_token".

    Three headers are required on the HTTPS request: Accept, Content-Type, and Authorization.

    For example, here is an API call for POST .../transportEvents/actualGateIn - Actual gate in. Token Generation16f Token Generation17f

    Example response: Token Generation18f

  6. Handle Solution Authorizer solution token expiration.

    The Solution Authorizer solution token is valid for 1 hour because the Cloud IAM token expires in 1 hour. When the solution token expires, only then is a new token required from Cloud IAM. Client code should not cache the IAM access_token, but instead get a new one when the Solution Authorizer solution token expires. So, the process should be: obtain Cloud IAM token => get solution (bearer) token from Solution Authorizer => cache and check for expiration of only the Solution Authorizer solution token and if it is expired, get a new Cloud IAM token and Solution Authorizer solution token. Note that the token could expire right as it is being used. If this happens, a 401 will be the response. The calling code should check for a 401 and handle it by getting a new Cloud IAM token and Solution Authorizer solution token.

    This is what the sample Java code (discussed at the top of this procedure section - exampleSolutionManagerService.zip) is doing:

    • getBearerToken() is called before sending any request. It checks if the token is still valid, checks expiration on checkSMToken(). If it has expired, then it calls loginToSM();, which "re-starts" the loop by calling IAM to get new token and exchanges it with Solution Manager token.