Skip to main content

​
Introduction

IETF RFC6750 opens with:
Any party in possession of a bearer token (a “bearer”) can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.
The bearer token is a cryptic string, usually generated by the server. When the client makes a request to consume an API on the server, it must send this token in a header, typically as: Authorization: Bearer <token>. When the server receives the token, it checks its validity and authentcates that the “bearer” of the token is the entity to which the token was issued. The OpenAPI Specification defines an API Key as:
a token that a client provides when making API calls. API keys are supposed to be a secret that only the client and server know … API key-based authentication is only considered secure if used together with other security mechanisms such as HTTPS/SSL.
Bearer Token, API Key, Authentication Token… from the perspective of Tyk these are different names for the same thing: a “token” string that can be used to access an API secured using Tyk’s Auth Token authentication method.

​
An Overview of the Auth Token method

Tyk’s “Auth Token” authentication method is a flexible mechanism that functions like a Bearer Token but is defined as an ‘API Key’ according to OpenAPI 3.0 standards.
  • Tyk Gateway issues Auth Tokens (called Keys in the Tyk Dashboard App)
  • For each token, a session state object is created with the Redis key containing the token string
    • this session object contains details of the access rights and consumption limits to be applied to the client presenting the token
  • The client can present the token in a header, query parameter or cookie
    • the location is configurable within the API definition
  • The Bearer identifier is optional when using a header for the token
  • When the token is presented, it is used as a simple key lookup against the Redis keys and validated if a matching session object is found
  • From Tyk 5.12.0 the token can be bound to a client certificate to provide an extra layer of authentication security
    • when this is in use, Tyk validates that the certificate presented with the token matches that bound to the session

​
Configuring your API to use Auth Token

The OpenAPI Specification indicates the use of Auth Tokens (API Keys) in the components.securitySchemes object using type: apiKey. It also includes specification of the location (in) and key (name) that are to be used when providing the token to the API, for example: 
components:
  securitySchemes:
    myAuthScheme:
      type: apiKey
      in: header
      name: Authorization
      
security:
  - myAuthScheme: []
With this configuration provided by the OpenAPI description, all that is left to be configured in the Tyk Vendor Extension is to enable authentication and to select this security scheme. 
x-tyk-api-gateway:
  server:
    authentication:
      enabled: true
      securitySchemes:
        myAuthScheme:
          enabled: true
Note that URL query parameter keys and cookie names are case sensitive, whereas header names are case insensitive. You can optionally strip the auth token from the request prior to proxying to the upstream using the authentication.stripAuthorizationData field (Tyk Classic: strip_auth_data).

​
Multiple Auth Token Locations

The OpenAPI Specification’s securitySchemes mechanism allows only one location for the auth token, but in some scenarios an API might need to support multiple potential locations to support different clients. The Tyk Vendor Extension supports this by allowing configuration of alternative locations in the auth token entry in server.authentication.securitySchemes. Building on the previous example, we can add optional query and cookie locations as follows: 
x-tyk-api-gateway:
  server:
    authentication:
      enabled: true
      securitySchemes:
        myAuthScheme:
          enabled: true
          query:
            enabled: true
            name: query-auth
          cookie:
            enabled: true
            name: cookie-auth

​
Client Certificate - Token Binding

In Tyk 5.12.0 we introduced an option when combining the Auth Token method with static mTLS to form a binding association between the Auth Token issued to a client and their client certificate. This works as follows:
  1. The client certificate must first be registered with the Tyk Certificate Store and added to the statically declared allow list in the API definition, the act of doing this enforces the mTLS handshake for requests to the API.
  2. When the Auth Token is issued by Tyk, the certificate is bound to the session object that is created in Redis (the certificateID is stored in the mtls_static_certificate_bindings field in the session object)
  3. When a request is made by the client, they must provide a certificate to satisfy the mTLS handshake. This certificate is then checked against the allow list in the API definition and then the binding in the session object. If it is not present in the allow list or not in the bound certificates list, authentication will fail and the request will be rejected.
Multiple client certificates can be bound to a token, for additional flexibility. Proactive maintenance of the list of bound certificates supports seamless rotation of certificates, as the new certificate can be registered and bound prior to the client switching to use it. This feature is fully backward-compatible. Existing tokens that do not have certificate bindings will continue to work as before, as the binding check is simply skipped. No additional configuration is required in the Tyk Gateway configuration nor in the API Definition.
Policies do not currently support certificate-token binding. This will be added in a future release.

​
Dynamic mTLS with Auth Token

The Auth Token method can support Dynamic mTLS where the client can provide a TLS certificate in lieu of a standard Auth Token. This can be configured for an API using the enableClientCertificate option (Tyk Classic: auth.use_certificate). You can use your own identity provider to generate access tokens, then import them to Tyk via POST /tyk/keys/{keyID} in the Tyk Gateway API. This lets Tyk manage access control, quotas, and rate limiting for you.

​
Legacy Options

​
Dynamic mTLS with Auth Token

Dynamic mTLS became a standalone authentication method in Tyk 5.12.0 and is now more accurately called Certificate Authentication
Prior to Tyk 5.12.0, Dynamic mTLS was configured via the Auth Token method by setting the enableClientCertificate flag (Tyk Classic: auth_configs.authToken.use_certificate). 
server:
    authentication:
      enabled: true
      securitySchemes:
        authToken:
          enabled: true
          enableClientCertificate: true
This was later changed to Certificate Authentication, as explained here.

​
Auth Token with Signature

If you are migrating from platforms like Mashery, which use request signing, you can enable signature validation alongside auth token by configuring the additional signatureValidation field (Tyk Classic: auth.signature). You can configure:
  • the location of the signature
  • the algorithm used to create the signature (MasherySHA256 or MasheryMD5)
  • secret used during signature
  • an allowable clock skew

​
Using Tyk Dashboard to Configure Auth Token

Using the Tyk Dashboard, you can configure the Auth Token authentication method from the Server section in the API Designer by enabling Authentication and selecting Auth Token from the drop-down: Configuring the Auth Token method
  • select the location(s) where Tyk should look for the token
  • provide the key name for each location (we prefill the default Authorization for the header location, but you can replace this if required)
  • select Strip authorization data to remove the auth token locations from the request prior to proxying to the upstream, as described here
Note that the auth token + signature option is not available in the Tyk Dashboard API Designer.

​
Binding a Client Certificate to a Token

Certificates are bound to tokens when the tokens are issued or when the session object is subsequently updated. When an API secured by Auth Token and mTLS is selected in the Access Rights tab of the API Security > Keys screen, an additional tab will be displayed: Authentication. Creating an API Key for an API secured with Auth Token and mTLS On the Authentication tab there is an option to bind certificates to the token: Optionally bind a client certificate to the API Key If you select this option, you can then select the client certificate to bind to the new token. You can choose from the existing client certificates in the Tyk Certificate Store or, if required, you can upload new certificates (in PEM format). Tyk will register these within the Tyk Certificate Store so that they are available for use. Select Attach Certificate. Uploading a client certificate to bind to the API Key The certificate will be added to a list of bound certificates. The new cert is shown in the list of bound certificates You can optionally add more certificates, or proceed to issue the key by selecting Create Key. You can add and remove certificate bindings for existing tokens from the Update Key screen: The new cert is shown in the list of bound certificates
NoteBinding a certificate to an Auth Token does not automatically add that certificate to the static allow list for the API(s) that the token is authorised to access. When a request is made using the token, the presented client certificate will be checked against the allow list after the mTLS handshake has completed and before the binding is checked. Authentication will fail if the certificate is not in the allow list.

​
Using Tyk Classic APIs

As noted in the Tyk Classic API documentation, a new Tyk Classic API will use the auth (bearer) token method by default with the token expected in the Authorization header, so configuration is slightly different as there is no need to enable this method. You should configure the auth object for any non-default settings, such as a different token location or Dynamic mTLS.