Introduction

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol, which allows applications to verify the identity based on the authentication performed by an authorization server, as well as to obtain basic profile information in an interoperable and REST-like manner.

CAS Service API uses OpenID as authentication protocol and OAuth as authorization protocol. The client application should obtain a token using the Client Credentials Grant.

With Client Credentials Grant (defined in RFC 6749, section 4.4) a Non Interactive Client (a CLI, a daemon, or a Service running on your backend), can directly ask identity provider for an access_token, by using its Client Credentials (Client Id and Client Secret) to authenticate. In this case the token represents the Non Interactive Client itself, instead of an end user. Following are the steps related to this flow:

1. The application authenticates with the CAS authorization server using its Client Id and Client Secret.
2. The CAS authorization server validates and returns an Access Token.
3. The application caches the access token and uses it as Bearer token in the authorization header when calling API functions on the CAS API.
4. The application stops using the access token once it has expired. The token response indicates when this token will expire, see expires_in (defined in seconds). Alternatively, any API function will return a 401 Unauthorized response when using an expired token. A new access token can be requested using the same process.

Client Id / Client Secret

C4T onboarding or support will provide the Client Id and Client Secret, which you will need to get an OAuth 2.0 authorization token.

If you have multiple source systems that communicate with one of the CAS Service APIs, you will receive different sets of Client Ids and Client Secrets. The reference of your source system will be part of the Bearer token.

To view the details of a token returned using a certain Client Id and Client Secret you can just decode the JWT token or make a call to v1/authorizationStatus on the API endpoint. This method will echo following info:

• The Client ID which corresponds to the assigned tenant ID.
• The assigned source system reference.
• The assigned scopes.

Usage

After receiving the token from the OAuthToken API you will have to store this token as it needs to be provided for each call that is made to the APIs. The token validity duration is also returned in the callback message. We strongly advise to cache this token so you don't need to call the Authorization API with every request. You can then refresh the token within the alloted time period or wait for a 401 (Unauthorized) response to do so.

The token validity duration could be changed in the future for security reasons, so please use the value given in the 'expires_in' field and don't hard code the time period.

Authentication request

To authenticate, you need to make a request in "application/x-www-form-urlencoded" format to the relevant token endpoint to retrieve a bearer token.

https://login.customs4trade.com/oauth2/v2.0/token (production) or https://login-acc.customs4trade.com/oauth2/v2.0/token (acceptance)

An example of the body of the request is shown below. Replace the variables by the appropriate values for your tenant in CAS.

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=https%3A%2F%2Fc4t{env}b2c.onmicrosoft.com%2F{client_id}%2F.default

A successful request, will result in a JSON response containing the bearer token which can be used in the Authorization header as "Bearer {token}".

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "ext_expires_in": 3599,
    "access_token": "{token}"
}

Take care to use the correct scope for respectively the acceptance or production environment