Authentication/Authorization Process
=============================================================================

|en| |tms| applications must authenticate against |enim| to retrieve an access token that will allow them to register any Web-Hooks with |encd| and to publish containers for tracing. The |auth|_ documentation explains the details of the authentication process, but this guide describes how this process will work for |en| |tms|.

Registering A Client
-----------------------------------------------------------------------------

The first step to integrate an |en| |tms| application with |entt| is to register a client that can authenticate against |enim|. Clients are registered against one of the |ienv| where |encd| and the related |entt| services are deployed.

Early in the development process, you'll want to register a client for the development/test environments. As your integration is reaching completion, you'll want to register a client for the staging/sandbox environment. Finally, you'll register a client for the production environment when you're ready to ship the application.

Registering a client will provide a client id and secret that uniquely identify that client. |en| |tms| applications will be issued a single client id and secret that they need to deploy to each of their installations. It is the responsibility of the application to keep the client id and secret secure.

..  important::
    Applications must insure that they deploy their client id and secret in a secure way, and that they are kept secure in their deployment environment (customer's system, cloud service, etc.).

|en| |tms| applications are trusted internal applications; therefore, their clients will be granted the client credentials guarantee. This will allow them to use the client credentials workflow for authentication which is only requires a single HTTP request to retrieve an access token.

Client Credentials Authentication Workflow
-----------------------------------------------------------------------------

As trusted applications, |en| |tms| clients will be issued a **Client Credentials** id and secret. This type of clients are also referred to as **Service Accounts** in the context of |enim|. It allows applications to access |en| services without a user log in, which simplifies the authentication workflow.

Clients can retrieve an access and refresh token by sending a single request to the authentication URL.

..  code-block:: shell

    POST https://envase.auth.us-east-1.amazoncognito.com/oauth2/token

The request should include the client id and secret issued for their application.

..  note::
    Applications should use an HTTP client available for their programming language. These clients will have a mean to provide the client id and secret, so that the authentication process is done correctly.

The response body will contain a **JWT** (JSON Web Token) with multiple sections. The two important sections are the **access_token**, which provides the token needed for subsequent requests to services, and the **refresh_token**, which contains a token that allows applications to refresh the access token when it expires.

The **access_token** value will be used in subsequent requests to |en| services as the value for the **Authorization** header.

The |auth|_ documentation provides more details about how the process works for |enim|.