Authentication

The APIs can have their own authentication implementation implemented in the backend, or we can use our authentication solution created using Cognito.

Using API keys tied to usage plan is also a form of authentication in some way but cannot be considered secure since they are not changed, and anyone can check the value in the headers of sent requests.

As we already use Cognito for platform authentication, we can also use it in our APIs. Amazon Cognito helps you meet various security and compliance requirements, including in highly regulated organizations like businesses and healthcare vendors. Amazon Cognito is HIPAA qualified and compliant with PCI DSS, SOC, ISO/IEC 27001, ISO/IEC 27017, ISO/IEC 27018, and ISO 9001 certifications.

Generating access token

To generate an access token, it is necessary to verify the authentication endpoint in the OpenID settings in the Account Information menu. The token endpoint is in the token_endpoint property.

The /oauth2/token endpoint only supports HTTPS POST. The user pool client makes requests to this endpoint directly and not through the system browser.

Request parameters in headers

Authorization

After receiving the credentials, the client needs to pass the client_id and client_secret in the authorization header via [Basic HTTP] authorization (https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side). The format is Base64Encode(client_id:client_secret)..

Content-Type:

It must always be application/x-www-form-urlencoded.

Request body

grant_type

Must always be client_credentials Mandatory.

scope

It can be a combination of any custom scopes associated with a customer. Any requested scope must be pre-associated with the client, or it will be ignored during runtime. If the client does not request any scopes, the authentication server will use all custom scopes associated with the client. Mandatory.

Resource server

A resource server is a server for resources with protected access. It handles authenticated requests from an application that has an access token. A scope is a level of access that an application can request for a resource.

To secure an API with the resource server, it is necessary to enable the authentication option using Cognito as the authorizer and assign an OAuth scope to the endpoint. To do this with the serverless framework, you can use the example below:

functions:
  myFunction:
    handler: src/handlers/myFunction.handler
    events:
      - http:
          path: v1/my/endpoint
          method: get
          authorizer:
            name: authorizer
            arn: arn:aws:cognito-idp:${aws:region}:${aws:accountId}:userpool/${env:COGNITO_USER_POOL_ID}
            scopes:
              - https://mycustom.scope.com/read.employee

To create a new resource server, you need to provide the following information:

• Resource server name

• Identifier - must be unique in the environment

• List of scopes, with name and description

When created, it will be assigned directly to your account’s user group.

API Clients

An API client represents an organization or user that will consume authenticated resources using a resource server. They generate a client ID and client secret that should only be shared with people who should have access to the endpoints.

Creating an API client

To create an API client, you need to enter the following information:

• Customer name - must be unique in the environment

• Expiration time of access tokens, ID, and refresh token

• List of OAuth scopes

Generating a token

To generate a token, check the section token generation