Introduction
Mutual TLS (mTLS) can be enforced for APIs on the Provider Gateway, often in combination with another authentication method, such as a JSON Web Token. With mTLS, API clients must present a valid client certificate and access token. APIs secured withAuth Token + mTLS or JWT + mTLS can be included in API Products on the Developer Portal.
In both of these scenarios, a static allow list of client certificates is registered within the API definition. The certificate presented by the API client must match an entry in that list (or, if an issuing certificate is included in the list it must be signed by that authority) for authentication to complete successfully.
All client certificates must be pre-registered in the Tyk Certificate Store to be used for authentication.
The client certificate allow list for APIs secured using JWT Auth is managed from the Provider Dashboard; whereas for APIs secured using Auth Token, where the access credential can be issued by the Developer Portal, the association between client certificate and token can be created using the Portal.
Associating Certificates with Developer Apps
For API Products that use the Auth Token + mTLS authentication method, the Developer Portal manages the association between a developer’s app and their client certificates. When access credentials are issued to the app, the associated certificate(s) are automatically added to the allow list for each API in the Product. The API Consumer must then provide one of these registered certificates when making a request to the Gateway to complete authentication. In Portal 1.16 an option was added to the API Product configuration for Products that grant access to APIs secured with Auth Token + mTLS - Mutual TLS Certificate Mode This has two options:
It is important to note that for APIs secured using JWT with mTLS, the ‘Managed’ and ‘Self-Serve’ certificate modes are not applicable. The association between the client certificate and the token is managed directly in the Provider Dashboard.
Managed Certificates
In the Managed mode, client certificates are centrally managed by the API Owner in the Admin Portal. Certificates are uploaded via the Provider or Portal and can be associated with one or more Organisations. When access credentials (Auth Tokens) are issued for a Developer App (i.e. when an access request is approved), all certificates associated with the Organisation will be added to the allow list for the APIs to which access has been granted.Self-Serve Certificates
In the Self-Serve mode, which was the only option prior to *Portal 1.16.0, the API Consumer must provide a client certificate when they request access to the API Product. When the request is approved, this certificate will be registered with the Provider’s Certificate Store and added to the allow list for the APIs to which access has been granted.
Certificate-Token Binding
In Portal 1.17.0 the Portal gained the option to implement Tyk’s Certificate-Token binding feature that was introduced in Tyk 5.12.0. If selected, the new option in API Product settings will link the token issued to the API Consumer with their client certificate(s). For self-serve mode this will be the certificate provided in the access request, for managed mode it will be all certificates associated with the Organisation. This feature prevents misuse of tokens by owners of other valid client certificates.
Developer Portal Certificate Store
Certificates used for client authentication are primarily stored and managed within the Provider’s Certificate Store. From Portal 1.17.0 the Admin Portal provides a facade to the Provider’s Certificate Store. Details of certificates within the Provider’s store are exposed to the Admin Portal on the API Consumers > Certificates screen.
- assign a name for easier recognition within the Portal (note that this is not transferred to the Provider)
- associate the certificate with one or more Organisations (required for API Products using Managed Certificates)
