Authentication and Authorization

​

Introduction

• Authentication: Confirms the identity of the user or system making the API request. This step validates “who” is attempting to access the API, commonly through methods like tokens, passwords, or certificates.
• Authorization: Determines if the authenticated user or system has the right permissions to perform the requested action. This step defines “what” they are allowed to do based on assigned roles, scopes, or policies.

​

Set Up OAuth 2.0 Authorization

​

Integrating OAuth 2.0

​

Option 1: Integrate Existing OAuth 2.0 Flow

1. Manage Tokens Within Your Application: Utilize your existing OAuth 2.0 implementation or a preferred library to generate and manage tokens.
2. Create Sessions in Tyk: Once your API issues a token, create corresponding key sessions within Tyk using the Gateway REST API.
3. Configure API Access in Tyk:
   • Set “Auth Token” as your API’s authentication mode within Tyk.
   • Configure the “Authorization” header.
   • Consider adding OAuth-specific endpoints (/access, /authorize) to your API’s ignored_paths list for direct access if required.

​

Option 2: Using Tyk as The OAuth 2.0 Provider

1. Simplify Authorization with Tyk: Designate Tyk as your OAuth 2.0 provider, streamlining token generation and management.
2. Seamless Application Integration: Integrate your application with Tyk’s API and notification endpoints for streamlined OAuth 2.0 functionality.

​

Understanding the OAuth 2.0 Flow within Tyk

1. Register a Client ID in Tyk:
   • Start by registering a new OAuth client on the Tyk dashboard. This generates a Client ID and Client Secret for your app, which you’ll use for secure access requests.
2. Request Authorization for the Client:
   • Your app directs the user to Tyk’s authorization URL (/oauth/authorize/) with the Client ID, prompting Tyk to check that the request follows OAuth standards and that the Client ID is active and valid.
3. Redirect to User Login and Authorization:
   • If the authorization request is valid, Tyk redirects the user to your app’s Login and Authorization page. Here, the user logs in, approves access, and grants permissions to the app, similar to a standard OAuth consent flow.
4. Authorize the Client in Tyk:
   • After the user approves, your app calls Tyk’s Authorization API (/authorize-client/), sending the Client ID and user permissions. Tyk then generates an Authorization Code for your app.
5. Redirect the User Back to Your App:
   • Tyk redirects the user to your app’s specified redirect URL, including the newly generated authorization code.
6. Exchange Authorization Code for an Access Token:
   • Your app now exchanges the authorization code for an access token by calling Tyk’s token endpoint (/oauth/token). This token lets the app access the user’s data per the permissions granted.
7. Optional: Receive Notifications via Webhook:
   • If needed, set up a webhook endpoint in your app to receive notifications from Tyk whenever a new access token is issued. This helps your app keep track of the user’s access status in real time.

• Step 1: Registering a Client ID (done in Tyk dashboard)
• Step 3: Creating a login and authorization page for users to approve app access
• Step 7: Setting up a webhook to track access tokens (optional)

​

Enabling OAuth 2.0 via the Dashboard

1. Select OAuth 2.0 for Your API: On the Tyk Dashboard, Navigate to APIs, select the API you want to affect and select “edit”. Enable
2. Configure Grant Type Settings: Define allowed access and authorize types aligned with your chosen OAuth 2.0 grant type (e.g., Authorization Code).
3. Set Redirection URLs: For grant types involving redirects, provide the OAuth login redirect URL and the OAuth notification URL.
4. Create an Access Policy: Establish a policy that explicitly grants access to this API.
5. Register a New OAuth Client: Go to the “OAuth Clients” section for your API and add a new client.
   • Specify a valid redirect URI.
   • Associate the client with the access policy you created.
   
6. Access Client Credentials: After client creation, view the generated Client ID and Secret.

​

Enabling OAuth 2.0 via an API Definition

{
  "name": "OAuth Test API",
  // ... other API settings
  "use_oauth2": true,
  "oauth_meta": {
    "allowed_access_types": ["authorization_code", "refresh_token"],
    "allowed_authorize_types": ["code", "token"],
    "auth_login_redirect": "http://yourapp.com/login"
  },
  "notifications": {
    "shared_secret": "your-shared-secret",
    "oauth_on_keychange_url": "http://yourapp.com/oauth_notifications"
  }
  // ... other API settings
}

• name: Specifies the name of the API, in this case, “OAuth Test API.”
• use_oauth2: Enables OAuth 2.0 authentication for this API (true indicates OAuth 2.0 is used).
• oauth_meta: Contains OAuth 2.0-specific configuration options:
  • allowed_access_types: Defines which OAuth 2.0 access types are allowed, such as authorization_code and refresh_token.
  • allowed_authorize_types: Defines which OAuth 2.0 authorization methods are permitted, like code (authorization code) and token (implicit flow).
  • auth_login_redirect: Specifies the URL to which users are redirected after successful login, typically the login page of your application.
• notifications: Manages notifications for OAuth events:
  • shared_secret: A secret key shared between Tyk and your app, used to secure notifications.
  • oauth_on_keychange_url: The URL to which Tyk sends a notification when an OAuth key changes (e.g., token revocation or regeneration).

​

Manage Quotas and Limits

{
  "allowance": 1000,
  "rate": 1000,
  "per": 60,
  "expires": -1,
  "quota_max": -1,
  "quota_renews": 1406121006,
  "quota_remaining": 0,
  "quota_renewal_rate": 60,
  "access_rights": {
    "APIID1": {
      "api_name": "HMAC API",
      "api_id": "APIID1",
      "versions": [
        "Default"
      ]
    }
  },
  "org_id": "1",
  "oauth_client_id": "client-id-here",
  "hmac_enabled": false,
  "hmac_string": ""
}

​

Configure Notifications

• oauth_on_keychange_url: Set the URL where Tyk will send notifications.
• shared_secret: Use this secret for secure communication between Tyk and your application; the secret is sent as a header (X-Tyk-Shared-Secret) with every notification.

{
  "auth_code": "",
  "new_oauth_token": "",
  "refresh_token": "",
  "old_refresh_token": "",
  "notification_type": ""
}

​

Supported Grant Types

• Authorization Code
• Refresh Token
• Username and Password
• Client Credentials
• Authorization Token Flow (Ideal for server-side web applications)

​

Use Authorization Code Grant

• Redirect to a login page
• Request an authorization code
• Exchange the code for a token

Redirect the User to a Login Page

curl -X POST \
  https://tyk.cloud.tyk.io/oauth-api/oauth/authorize/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'response_type=code&client_id=ed59158fa2344e94b3e6278e8ab85142&redirect_uri=http%3A%2F%2Fexample.com%2Fclient-redirect-uri'

Request an Authorization Code

curl -X POST \
  https://admin.cloud.tyk.io/api/apis/oauth/25b854d3fdc84703679f49ea33981aa9/authorize-client/ \
  -H 'Authorization: 70c3d834d46a4d6076e1585b0ef2e93e' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'response_type=code&client_id=ed59158fa2344e94b3e6278e8ab85142&redirect_uri=http%3A%2F%2Fexample.com%2Fclient-redirect-uri'

{
  "code": "EaG1MK7LS8GbbwCAUwDo6Q",
  "redirect_to": "http://example.com/client-redirect-uri?code=EaG1MK7LS8GbbwCAUwDo6Q"
}

Exchange the Authorization Code for an Access Token

curl -X POST \
  https://tyk.cloud.tyk.io/oauth-api/oauth/token/ \
  -H 'Authorization: Basic ZWQ1OTE1OGZhMjM0NGU5NGIzZTYyNzhlOGFiODUxNDI6TUdRM056RTJNR1F0WVRVeVpDMDBaVFZsTFdKak1USXRNakUyTVRNMU1tRTNOMk0x' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&client_id=ed59158fa2344e94b3e6278e8ab85142&code=EaG1MK7LS8GbbwCAUwDo6Q&redirect_uri=http%3A%2F%2Fexample.com%2Fclient-redirect-uri'

{
  "access_token": "580defdbe1d21e0001c67e5c2a0a6c98ba8b4a059dc5825388501573",
  "expires_in": 3600,
  "refresh_token": "NWQzNGVhMTItMDE4Ny00MDFkLTljOWItNGE4NzI1ZGI1NGU2",
  "token_type": "bearer"
}

{
  "auth_code": "EaG1MK7LS8GbbwCAUwDo6Q",
  "new_oauth_token": "580defdbe1d21e0001c67e5c2a0a6c98ba8b4a059dc5825388501573",
  "refresh_token": "NWQzNGVhMTItMDE4Ny00MDFkLTljOWItNGE4NzI1ZGI1NGU2",
  "old_refresh_token": "",
  "notification_type": "new"
}

​

Use Username and Password Grant

Token Request

curl -X POST \
  https://tyk.cloud.tyk.io/oauth-api/oauth/token/ \
  -H 'Authorization: Basic ZWQ1OTE1OGZhMjM0NGU5NGIzZTYyNzhlOGFiODUxNDI6TUdRM056RTJNR1F0WVRVeVpDMDBaVFZsTFdKak1USXRNakUyTVRNMU1tRTNOMk0x' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&client_id=ed59158fa2344e94b3e6278e8ab85142&username=oauthapiusername&password=oauthapipassword'

Response

{
  "access_token": "580defdbe1d21e0001c67e5ce3ea17db02be4c62ba15089bbcfd1f80",
  "expires_in": 3600,
  "refresh_token": "YjdhOWFmZTAtNmExZi00ZTVlLWIwZTUtOGFhNmIwMWI3MzJj",
  "token_type": "bearer"
}

​

Use Refresh Token Grant

• Obtain a Refresh Token during the initial authorization.
• Use the Refresh Token to request a new Access Token.

Request new token

curl -X POST \
  https://tyk.cloud.tyk.io/oauth-api/oauth/token/ \
  -H 'Authorization: Basic ZWQ1OTE1OGZhMjM0NGU5NGIzZTYyNzhlOGFiODUxNDI6TUdRM056RTJNR1F0WVRVeVpDMDBaVFZsTFdKak1USXRNakUyTVRNMU1tRTNOMk0x' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=ed59158fa2344e94b3e6278e8ab85142&client_secret=MGQ3NzE2MGQtYTUyZC00ZTVlLWJjMTItMjE2MTM1MmE3N2M1&refresh_token=YjdhOWFmZTAtNmExZi00ZTVlLWIwZTUtOGFhNmIwMWI3MzJj'

Response

{
  "access_token": "580defdbe1d21e0001c67e5c2a0a6c98ba8b4a059dc5825388501573",
  "expires_in": 3600,
  "refresh_token": "NWQzNGVhMTItMDE4Ny00MDFkLTljOWItNGE4NzI1ZGI1NGU2",
  "token_type": "bearer"
}

​

Use Client Credentials Grant

• Request an Access Token

Token Request

curl -X POST \
  https://tyk.cloud.tyk.io/oauth-api/oauth/token/ \
  -H 'Authorization: Basic ZWQ1OTE1OGZhMjM0NGU5NGIzZTYyNzhlOGFiODUxNDI6TUdRM056RTJNR1F0WVRVeVpDMDBaVFZsTFdKak1USXRNakUyTVRNMU1tRTNOMk0x' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=ed59158fa2344e94b3e6278e8ab85142&client_secret=MGQ3NzE2MGQtYTUyZC00ZTVlLWJjMTItMjE2MTM1MmE3N2M1'

Response

{
  "access_token": "580defdbe1d21e0001c67e5c40e93eac3d23494697470b90d7c81593",
  "expires_in": 3600,
  "token_type": "bearer"
}

​

Use Bearer Tokens

What is a bearer token ?

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.

Enable bearer tokens in your API Definition with the Dashboard

1. Select your API from the System Management > APIs menu
2. Scroll to the Authentication options
3. Select Authentication Token from the drop-down list
4. Select Strip Authorization Data to strip any authorization data from your API requests
5. Tyk will by default assume you are using the Authorization header, but you can change this by setting the Auth Key Header name value
6. You can select whether to use a URL query string parameter as well as a header, and what parameter to use. If this is left blank, it will use the Auth Key Header name value.
7. You can select whether to use a cookie value. If this is left blank, it will use the Header name value.
8. You can select to use a client certificate. This allows you to create dynamic keys based on certificates.

Enable bearer tokens in your API Definition with file-based

"auth": {
  "auth_header_name": "authorization",
  "use_param": false,
  "param_name": "",
  "use_cookie": false,
  "cookie_name": ""
},

...
"auth": {
  "validate_signature": true,
  "signature": {
    "algorithm": "MasherySHA256",
    "header": "X-Signature",
    "secret": "secret",
    "allowed_clock_skew": 2
  }
}
...

• MasherySHA256
• MasheryMD5

• Can hold a dynamic value, by referencing $tyk_meta or $tyk_context variables.
• Example: "secret": "$tyk_meta.individual_secret". Which effectively means that you have created/imported the api key into Tyk, and have stored the shared secret in the field individual_secret of the session token’s meta-data.

Enabling bearer tokens with Tyk Operator

​

Revoke OAuth Tokens

• From a Gateway API endpoint (in compliance with https://tools.ietf.org/html/rfc7009). See the OAuth section of our Swagger doc for the Gateway REST API for details.
• Via a Dashboard API calls - Revoke a token and revoke all tokens
• Via a Portal Developer API call - Revoke a token and revoke all tokens
• Via the Developer menu from the Tyk Dashboard

​

Submit a Request to Revoke the Token

curl -X POST \
  https://auth-server.com/oauth2/revoke \
  -H 'Authorization: Basic ZWQ1OTE1OGZhMjM0NGU5NGIzZTYyNzhlOGFiODUxNDI6TUdRM056RTJNR1F0WVRVeVpDMDBaVFZsTFdKak1USXRNakUyTVRNMU1tRTNOMk0x' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=ACCESS_TOKEN&token_type_hint=access_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'

​

Other Authentication Methods

​

Use Basic Authentication

​

How does Basic Authentication work?

Basic base64Encode(username:password)

GET /api/widgets/12345 HTTP/1.1
Host: localhost:8080
Authorization: Basic am9obkBzbWl0aC5jb206MTIzNDU2Nw==
Cache-Control: no-cache

The problem with Basic Authentication

Protect your API with Basic Authentication

​

Enable Basic Auth

Enable Basic Authentication using the Tyk Dashboard

1. Select your API from the API Management > APIs menu
2. Scroll to the Authentication options
3. Select Basic Authentication from the drop-down list
4. Select Strip Authorization Data to strip any authorization data from your API requests.
5. Tyk will by default assume you are using the Authorization header, but you can change this by setting the Auth Key Header name value
6. You can select whether to use a URL query string parameter as well as a header, and what parameter to use. If this is left blank, it will use the Auth Key Header name value.
7. You can select whether to use a cookie value. If this is left blank, it will use the Header name value.

Enable Basic Authentication in your file-based API Definition

{
  "name": "Tyk Test API",
  ...
  "use_basic_auth": true,
  ...
}

Enable basic authentication using Tyk Operator

​

Create a Basic Authentication user

Using Tyk Dashboard

$ curl http://localhost:8080/basicauth/get \
  --header "Authorization: Basic $(echo -n 'myusername:mypassword' | base64)"
<200 response>

$ curl http://myusername:mypassword@localhost:8080/basicauth/get
<200 response from upstream>

Using the Tyk Gateway API

curl -X POST -H "x-tyk-authorization: 352d20fe67be67f6340b4c0605b044c3" \
 -s \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{
    "allowance": 1000,
    "rate": 1000,
    "per": 1,
    "expires": -1,
    "quota_max": -1,
    "org_id": "53ac07777cbb8c2d53000002",
    "quota_renews": 1449051461,
    "quota_remaining": -1,
    "quota_renewal_rate": 60,
    "access_rights": {
        "{API-ID}": {
            "api_id": "{API-ID}",
            "api_name": "{API-NAME}",
            "versions": ["Default"]
        }
    },
    "meta_data": {},
    "basic_auth_data": {
        "password": "mickey-mouse"
    }
 }' http://{your-tyk-gateway-host}:{port}/tyk/keys/testuser | python -mjson.tool

Using the Tyk Dashboard API

curl -X POST -H "Authorization: 907aed9f88514f175f1dccf8a921f741"
 -s
 -H "Content-Type: application/json"
 -X POST
 -d '{
    "allowance": 1000,
    "rate": 1000,
    "per": 1,
    "expires": -1,
    "quota_max": -1,
    "org_id": "53ac07777cbb8c2d53000002",
    "quota_renews": 1449051461,
    "quota_remaining": -1,
    "quota_renewal_rate": 60,
    "access_rights": {
      "{API-ID}": {
        "api_id": "{API-ID}", 
        "api_name": "{API-NAME}", 
        "versions": [
            "Default"
        ]
      }
    },
    "meta_data": {},
    "basic_auth_data": {
      "password": "minnie-mouse"
    }
 }' http://{your-tyk-dashboard-host}:{port}/api/apis/keys/basic/testuser2 | python -mjson.tool

​

Extract credentials from the request body

"basic_auth": {
    "extract_from_body": true,
    "body_user_regexp": "<User>(.*)</User>",
    "body_password_regexp": "<Password>(.*)</Password>"
}

​

Integrate External OAuth Middleware

​

OAS contract

externalOAuthServer:
  enabled: true,
  providers: # only one item in the array for now (we're going to support just one IDP config in the first iteration)
  - jwt: #validate JWTs generated by 3rd party Oauth servers (like Okta)
      enabled: true
      signingMethod: HMAC/RSA/ECDSA # to verify signing method used in jwt
      source: key # secret to verify signature
      issuedAtValidationSkew: 0
      notBeforeValidationSkew: 0
      expiresAtValidationSkew: 0
      identityBaseField: # identity claimName
    introspection: # array for introspection details
      enabled: true/false
      clientID: # for introspection request
      clientSecret: # for introspection request, if empty will use oAuth.secret
      url: # token introspection endpoint
      cache: # Tyk will cache the introspection response when `cache.enabled` is set to `true`
        enabled: true/false,
        timeout: 0 # The duration (in seconds) for which Tyk will retain the introspection outcome in its cache. If the value is "0", it indicates that the introspection outcome will be stored in the cache until the token's expiration.
      identityBaseField: # identity claimName

​

Tyk Classic API definition contract

"external_oauth": {
  "enabled": true,
  "providers": [
    {
      "jwt": {
        "enabled": false,
        "signing_method": rsa/ecdsa/hmac,
        "source": # jwk url/ base64 encoded static secret / base64 encoded jwk url
        "identity_base_field": # identity claim name
        "expires_at_validation_skew": # validation skew config for exp
        "not_before_validation_skew": # validation skew config for nbf
        "issued_at_validation_skew" : # validation skew config for iat
      },
      "introspection": {
        "enabled": true,
        "url": # introspection endpoint url
        "client_id": # client id used for introspection
        "client_secret": # client secret to be filled here (plain text for now, TODO: decide on a more secure mechanism)
        "identity_base_field": # identity claim name
        "cache": {
          "enabled": true,
          "timeout": # timeout in seconds
        }
      }
    }
  ]
}

• externalOAuthServer set enabled to true to enable the middleware.
• providers is an array of multiple IDP configurations, with each IDP config being an element in the providers array.
• You can use this config to use JWT self validation using jwt or use introspection via instropection in the providers section .
  For now, you’ll be limiting providers to have only one element, ie one IDP configured.

​

JWT

• enabled - enables JWT validation.
• signingMethod - specifies the signing method used to sign the JWT.
• source - the secret source, it can be one of:
  • a base64 encoded static secret
  • a valid JWK url in plain text
  • a valid JWK url in base64 encoded format
• issuedAtValidationSkew , notBeforeValidationSkew, expiresAtValidationSkew can be used to configure clock skew for json web token validation.
• identityBaseField - the identity key name for claims. If empty it will default to sub.

Example: Tyk OAS API definition with JWT validation enabled

"securitySchemes": {
  "external_jwt": {
    "enabled": true,
    "header": {
      "enabled": true,
      "name": "Authorization"
    },
    "providers": [
      {
        "jwt": {
          "enabled": true,
          "signingMethod": "hmac",
          "source": "dHlrLTEyMw==",
          "identityBaseField": "sub"
        }
      }
    ]
  }
}

Example: Tyk Classic API definition with JWT validation enabled

"external_oauth": {
  "enabled": true,
  "providers": [
      {
          "jwt": {
              "enabled": true,
              "signing_method": "hmac",
              "source": "dHlrLTEyMw==",
              "issued_at_validation_skew": 0,
              "not_before_validation_skew": 0,
              "expires_at_validation_skew": 0,
              "identity_base_field": "sub"
          },
          "introspection": {
              "enabled": false,
              "url": "",
              "client_id": "",
              "client_secret": "",
              "identity_base_field": "",
              "cache": {
                  "enabled": false,
                  "timeout": 0
              }
          }
      }
  ]
}

​

Introspection

• enabled - enables OAuth introspection
• clientID - clientID used for OAuth introspection, available from IDP
• clientSecret - secret used to authenticate introspection call, available from IDP
• url - endpoint URL to make the introspection call
• identityBaseField - the identity key name for claims. If empty it will default to sub.

Caching

"introspection": {
  ...
  "cache": {
    "enabled": true,
    "timeout": 60 // in seconds
  }
}

Example: Tyk OAS API definition external OAuth introspection enabled

"securitySchemes": {
  "keycloak_oauth": {
    "enabled": true,
    "header": {
      "enabled": true,
      "name": "Authorization"
    },
    "providers": [
      {
        "introspection": {
          "enabled": true,
          "url": "http://localhost:8080/realms/tyk/protocol/openid-connect/token/introspect",
          "clientId": "introspection-client",
          "clientSecret": "DKyFN0WXu7IXWzR05QZOnnSnK8uAAZ3U",
          "identityBaseField": "sub",
          "cache": {
            "enabled": true,
            "timeout": 3
          }
        }
      }
    ]
  }
}

Example: Tyk Classic API definition with external OAuth introspection enabled

"external_oauth": {
  "enabled": true,
  "providers": [
      {
          "jwt": {
              "enabled": false,
              "signing_method": "",
              "source": "",
              "issued_at_validation_skew": 0,
              "not_before_validation_skew": 0,
              "expires_at_validation_skew": 0,
              "identity_base_field": ""
          },
          "introspection": {
              "enabled": true,
              "url": "http://localhost:8080/realms/tyk/protocol/openid-connect/token/introspect",
              "client_id": "introspection-client",
              "client_secret": "DKyFN0WXu7IXWzR05QZOnnSnK8uAAZ3U",
              "identity_base_field": "sub",
              "cache": {
                  "enabled": true,
                  "timeout": 3
              }
          }
      }
  ]
}

​

Authenticate Using Go Plugins

​

Sign Requests with HMAC

Base64Encode(HMAC-SHA1("date: Mon, 02 Jan 2006 15:04:05 MST", secret_key))

Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha1",signature="Base64Encode(HMAC-SHA1(signing string))"

Mon, 02 Jan 2006 15:04:05 MST

Supported headers

A sample signature generation snippet

...

refDate := "Mon, 02 Jan 2006 15:04:05 MST"

// Prepare the request headers:
tim := time.Now().Format(refDate)
req.Header.Add("Date", tim)
req.Header.Add("X-Test-1", "hello")
req.Header.Add("X-Test-2", "world")

// Prepare the signature to include those headers:
signatureString := "(request-target): " + "get /your/path/goes/here"
signatureString += "date: " + tim + "\n"
signatureString += "x-test-1: " + "hello" + "\n"
signatureString += "x-test-2: " + "world"

// SHA1 Encode the signature
HmacSecret := "secret-key"
key := []byte(HmacSecret)
h := hmac.New(sha1.New, key)
h.Write([]byte(signatureString))

// Base64 and URL Encode the string
sigString := base64.StdEncoding.EncodeToString(h.Sum(nil))
encodedString := url.QueryEscape(sigString)

// Add the header
req.Header.Add("Authorization", 
  fmt.Sprintf("Signature keyId="9876",algorithm="hmac-sha1",headers="(request-target) date x-test-1 x-test-2",signature="%s"", encodedString))

...

Date header not allowed for legacy .Net

Clock Skew

Additional notes

​

Setting up HMAC using the Dashboard

1. Select your API from the System Management > APIs menu
2. Scroll to the Authentication options
3. Select HMAC (Signed Authetication Key) from the drop-down list
4. Configure your HMAC Request Signing settings.
5. Select Strip Authorization Data to strip any authorization data from your API requests.
6. Tyk will by default assume you are using the Authorization header, but you can change this by setting the Auth Key Header name value
7. You can select whether to use a URL query string parameter as well as a header, and what parameter to use. If this is left blank, it will use the Auth Key Header name value.
8. You can select whether to use a cookie value. If this is left blank, it will use the Header name value.

​

Setting up HMAC using an API Definition

{
  "name": "Tyk Test API",
  ...
  "enable_signature_checking": true,
  "use_basic_auth": false,
  "use_keyless": false,
  "use_oauth2": false,
  "auth": {
    "auth_header_name": ""
  },
  ...
}

​

Setting up an HMAC Session Object

{
  ...
  "hmac_enabled": true,
  "hmac_string": "",
  ...
}

​

Upstream HMAC request signing

"request_signing": {
  "is_enabled": true,
  "secret": "xxxx",
  "key_id": "1",
  "algorithm": "hmac-sha256"
}

1. hmac-sha1
2. hmac-sha256
3. hmac-sha384
4. hmac-sha512

​

Use OpenID Connect

​

Use JSON Web Tokens (JWT)

​

Protecting an API with JWT

• Set Authentication Mode
• Set the JWT Signing Method
• Set the Identity Source and Policy Field Name
• Set a Default Policy
• Generate a JWT

Set Authentication Mode

1. Select JSON Web Tokens as the Authentication mode
2. Set the cryptographic signing method to HMAC (shared) and the public secret as tyk123
3. Set the Identity Source and Policy Field Name

Set a Default Policy

Generate a JWT

$ curl http://localhost:8080/my-jwt-api/get \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.7u0ls1snw4tPEzd0JTFaf19oXoOvQYtowiHEAZnan74"

​

Use the JWT

curl -X GET \
  https://api.example.com/protected-resource \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

​

JWT and Auth0 with Tyk

Prerequisites

• A free account with Auth0
• A Tyk Self-Managed or Cloud installation

Create an Application in Auth0

1. Log in to your Auth0 account.
2. Select APIs from the Applications menu.
3. Click Create API and enter a name and identifier for your API.
4. From the Test tab, follow the instructions on how to get an access token.
5. From the cURL tab, copy the token request command.
   Copy

   Ask AI

   curl --request POST \
     --url https://dev-yjd8e8u5.us.auth0.com/oauth/token \
     --header 'content-type: application/json' \
     --data '{"client_id":{CLIENT_ID},"client_secret":{CLIENT_SECRET},"audience":{AUDIENCE},"grant_type":"client_credentials"}'
   

6. Paste the command in a terminal window to generate your token. Save this token locally.
   Copy

   Ask AI

   {
     "access_token": "xxxxxxxxxxx",
     "token_type": "Bearer"
   }
   

7. After creating your API, a new Auth0 Application will be created. Go to the Applications section to view it.
8. Copy the Domain from the Basic Information. You will use this when adding an API to Tyk.

Create your API in Tyk

1. Log in to your Tyk Dashboard
2. Create a new HTTP API (the default http://httpbin.org upstream URL is fine)

1. From the Authentication section, select JSON Web Token (JWT) as your authentication mode.
2. Select RSA public Key as the JWT signing method.
3. Enter your Auth0 Application Domain from Step 8 above to complete the jwks_uri end point https://<<your-auth0-domain>>/.well-known/jwks.json
4. Copy your jwks_uri in to the Public Key field.

1. Add an Identity Source and Policy Field Name. The defaults of sub and pol are fine.
2. Save your API.
3. From the System Management section, select Policies
4. Click Add Policy
5. Select your Auth0 API

1. You can keep the rest of the access rights at the defaults.
2. Click the Configurations tab and enter a Policy Name and a Keys Expiry after period.

1. Click Create Policy.
2. Edit your JWT Auth0 API and add the policy you created as the Default Policy from the Authentication section.

1. From the top of the API copy the API URL
2. From a terminal window using the API URL and the Auth0 generated token.

curl -X GET {API URL}  -H "Accept: application/json" -H "Authorization: Bearer {token}"

18. If using the httpbin upstream URL as in the example Tyk API, you should see the HTML returned for the httpbin service in your terminal.
19. If there is an error with the request, you will see the following error message.

{
  "error": "Key not authorized:Unexpected signing method."
}

​

JWT and Keycloak with Tyk

Prerequisites

• A Keycloak installation
• A Tyk Self-Managed or Cloud installation

Create an Application in Keycloak

1. Access your Keycloak admin dashboard.
2. Navigate to the Administration console.
3. Create a Keycloak realm from the top left-hand side dropdown.
4. Create a Keycloak client.
5. Enter the necessary client details.
6. Enable client authentication and Service account roles under Authentication flow.
7. Set the redirection URL rules.
8. Save.
9. Retrieve the client secret from the Credentials tab under the client you just created.
10. Generate your JWT using curl. This is the token you will use to access your services through the Tyk Gateway. You can generate your JWT using either of the following methods. Make sure to replace the KEYCLOAK prefixed parameters with the appropriate values. Password Grant Type:
    Copy

    Ask AI

    curl -L --insecure -s -X POST 'https://KEYCLOAK_URL/realms/KEYCLOAK_REALM/protocol/openid-connect/token' \
       -H 'Content-Type: application/x-www-form-urlencoded' \
       --data-urlencode 'client_id=KEYCLOAK_CLIENT_ID' \
       --data-urlencode 'grant_type=password' \
       --data-urlencode 'client_secret=KEYCLOAK_SECRET' \
       --data-urlencode 'scope=openid' \
       --data-urlencode 'username=KEYCLOAK_USERNAME' \
       --data-urlencode 'password=KEYCLOAK_PASSWORD'
    

    Client Credentials Grant Type:
    Copy

    Ask AI

    curl -L --insecure -s -X POST 'https://KEYCLOAK_URL/realms/KEYCLOAK_REALM/protocol/openid-connect/token' \
       -H 'Content-Type: application/x-www-form-urlencoded' \
       --data-urlencode 'client_id=KEYCLOAK_CLIENT_ID' \
       --data-urlencode 'grant_type=client_credentials' \
       --data-urlencode 'client_secret=KEYCLOAK_SECRET'
    

    A typical response will look something like this:
    Copy

    Ask AI

    {
       "access_token": "...", 
       "expires_in": 300,
       "refresh_expires_in": 1800,
       "refresh_token": "...",
       "token_type": "Bearer",
       "id_token": "...",
       "not-before-policy": 0,
       "session_state": "...",
       "scope": "openid profile email"
    }
    

Running in k8s

​

Create Your JWT API in Tyk

1. Log in to your Tyk Dashboard.
2. Create a new HTTP API (the default http://httpbin.org upstream URL is fine).
3. Scroll to the Authentication mode section and select JWT from the list.
4. Select RSA public Key as JWT Signing method.
5. Add your JSON Web Key Sets (JWKS) URL in the Public Key box. This can be found through the well-known config endpoint or is typically https://KEYCLOAK_URL/realms/KEYCLOAK_REALM/protocol/openid-connect/certs.
6. Add an Identity Source and Policy Field Name. The defaults of sub and pol are fine.
7. Click on the update button to save the API.
8. Create a policy to manage access to your API.
9. Navigate to the Policies section on the left-hand side menu.
10. Click on Add Policy on the top right-hand side of your screen.
11. Select your API from the Add API Access Rights list.

12. Click on the Configurations tab and choose a policy name and TLL.
13. Add the default policy to the API.
14. Test access to the API using curl.
15. Retrieve the API URL.
16. Test with curl. Make sure to replace TOKEN with the JWT you received from the curl earlier.
    Copy

    Ask AI

    curl 'friendly-slipper-gw.aws-use1.cloud-ara.tyk.io/keycloak.jwt/get' \
        -H "Authorization: Bearer TOKEN"
    

​

Split Token

Introduction to Split Token Flow

How Tyk Implements Split Token Flow

Request a JWT Access Token

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
https://keycloak-host/auth/realms/tyk/protocol/openid-connect/token \
-d grant_type=client_credentials \
-d client_id=efd952c8-df3a-4cf5-98e6-868133839433 \
-d client_secret=0ede3532-f042-4120-bece-225e55a4a2d6 -s | jq

Split the JWT

• Header: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
• Payload: eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJlbWFpbCI6ImhlbGxvQHdvcmxkLmNvbSJ9
• Signature: EwIaRgq4go4R2M2z7AADywZ2ToxG4gDMoG4SQ1X3GJ0

Create a Virtual Endpoint in Tyk

function login(request, session, config) {
    var credentials = request.Body.split("&")
        .map(function(item, index) {
            return item.split("=");
        }).reduce(function(p, c) {
            p[c[0]] = c[1];
            return p;
        }, {});

    var newRequest = {
        "Headers": {"Content-Type": "application/x-www-form-urlencoded"},
        "Method": "POST",
        "FormData": {
            grant_type: credentials.grant_type,
            client_id: credentials.client_id,
            client_secret: credentials.client_secret
        },
        "Domain": "https://keycloak-host",
        "resource": "/auth/realms/tyk/protocol/openid-connect/token",
    };

    var response = TykMakeHttpRequest(JSON.stringify(newRequest));
    var usableResponse = JSON.parse(response);

    if (usableResponse.Code !== 200) {
        return TykJsResponse({
            Body: usableResponse.Body,
            Code: usableResponse.Code
        }, session.meta_data)
    }

    var bodyObj = JSON.parse(usableResponse.Body);
    var accessTokenComplete = bodyObj.access_token;
    var signature = accessTokenComplete.split(".")[2];

    log("completeAccessToken: " + accessTokenComplete);

    // Create key inside Tyk
    createKeyInsideTyk(signature, bodyObj);

    // Override signature
    bodyObj.access_token = signature;
    delete bodyObj.refresh_expires_in;
    delete bodyObj.refresh_token;
    delete bodyObj.foo;

    var responseObject = {
        Body: JSON.stringify(bodyObj),
        Code: usableResponse.Code
    }
    return TykJsResponse(responseObject, session.meta_data);
}

$ curl localhost:8080/basic-protected-api/get -H "Authorization: MEw….GJ0"

​

Configure your JWT Setup

Set Up JWT Signing Method

• RSA public key
• HMAC shared secret
• ECDSA
• Public JWKS URL
  : Leave the field blank to configure at the key level.

openssl genrsa -out key.rsa 
openssl rsa -in key.rsa -pubout > key.rsa.pub

Set Up Individual JWT Secrets

1. Set up your token with the following fields:
   Copy

   Ask AI

   "jwt_data": {
     "secret": "Secret"
   }
   

2. Ensure the kid header field is included in the JWT for validation.
   • If the kid header is missing, Tyk will check the sub field. This is not recommended but supported.

Configure Identity Source and Policy Field Name

• Identity Source: Select which identity claim to use (e.g., sub) for rate-limiting and quota counting.
• Policy Field Name: Add a policy ID claim to the JWT that applies a specific security policy to the session.

Enable Dynamic Public Key Rotation Using JWKs

1. Use the JWKs URL to dynamically maintain and rotate active public keys.
2. Ensure JWTs contain the kid header, matching the kid in the JWK payload for verification.

$ curl http://keycloak_host:8081/auth/realms/master/protocol/openid-connect/certs
{
  "keys": [
      {
          "kid": "St1x2ip3-wzbrvdk4yVa3-inKWdOwbkD3Nj3gpFJwYM",
          "kty": "RSA",
          "alg": "RS256",
          "use": "sig",
          "n": "k-gUvKl9-sS1u8odZ5rZdVCGTe...m2bMmw",
          "e": "AQAB",
          "x5c": [
              "MIICmzCCAYMCBgFvyVrRq....K9XQYuuWSV5Tqvc7mzPd/7mUIlZQ="
          ],
          "x5t": "6vqj9AeFBihIS6LjwZhwFLmgJXM",
          "x5t#S256": "0iEMk3Dp0XWDITtA1hd0qsQwgES-BTxrz60Vk5MjGeQ"
      }
  ]
}

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "St1x2ip3-wzbrvdk4yVa3-inKWdOwbkD3Nj3gpFJwYM"
}

Adjust JWT Clock Skew Configuration

• jwt_issued_at_validation_skew
• jwt_expires_at_validation_skew
• jwt_not_before_validation_skew

Map JWT Scopes to Policies

1. Specify scope-to-policy mapping:

  "jwt_scope_to_policy_mapping": {
    {
    "admin": "59672779fa4387000129507d",
    "developer": "53222349fa4387004324324e"
  },
  "jwt_scope_claim_name": "our_scope"
}

• "jwt_scope_to_policy_mapping" provides mapping of scopes (read from claim) to actual policy ID. I.e. in this example we specify that scope “admin” will apply policy "59672779fa4387000129507d" to a key
• "jwt_scope_claim_name" identifies the JWT claim name which contains scopes. This API Spec field is optional with default value "scope". This claim value could be any of the following:
  • a string with space delimited list of values (by standard)
  • a slice of strings
  • a string with space delimited list of values inside a nested key. In this case, provide "jwt_scope_claim_name" in dot notation. For eg. "scope1.scope2", "scope2" will be having the list of values nested inside "scope1"
  • a slice of strings inside a nested key. In this case, provide "jwt_scope_claim_name" in dot notation. For eg. "scope1.scope2", "scope2" will be having a slice of strings nested inside "scope1"

2. Set the claim name that contains the scopes (default: scope):
   Copy

   Ask AI

   "jwt_scope_claim_name": "our_scope"
   

   Several scopes in JWT claim will lead to have several policies applied to a key. In this case all policies should have "per_api" set to true and shouldn’t have the same API ID in access rights. I.e. if claim with scopes contains value "admin developer" then two policies "59672779fa4387000129507d" and "53222349fa4387004324324e" will be applied to a key (with using our example config above).

Visualize JWT Flow in Tyk API Gateway

​

Use Open (Keyless) Authentication

​

Configure the API as Open or Keyless in Tyk

{
  ...
  "use_keyless": true,
  "auth": {
      "auth_header_name": ""
  },
  ...
}

​

Request a Public Resource

curl -X GET \
  https://api.example.com/public-resource

​

Combine Authentication Methods

​

Multiple (Chained) Authentication

​

Enable Multi (Chained) Authentication with the Dashboard

1. Browse to the “Authentication” Section First, navigate to the Endpoint Designer and view the “Core Settings” tab. In this section, you can choose various authentication methods. For this setup, you will configure multiple auth providers, which works slightly differently than setting up a single auth method.
2. Select the Multiple Auth Mechanisms Option Select the Use Multiple Auth Mechanisms option from the drop-down list. This will open a window that provides checkboxes for each supported auth type to be chained. Note that it is not possible to set the order of chained auth methods.
3. Select Your Preferred Auth Methods and Base Identity Provider Choose the authentication methods you want to chain together and select the base identity provider. The baseline provider will be the one that provides the current request context with the session object, defining the “true” access control list, rate limit, and quota to apply to the user. Once these are set up, you will see the traditional configuration screens for each of the auth methods selected in the checkboxes. Configure them as you would regular authentication modes.

​

Enable Multi (Chained) Authentication in Your API Definition

• AuthToken
• HMACKey
• BasicAuthUser
• JWTClaim
• OIDCUser
• OAuthKey
• UnsetAuth

​

Enable Multi (Chained) Authentication with Tyk Operator

​

Use Python CoProcess and JSVM Plugin Authentication

• See Custom Authentication with a Python plugin for a detailed example of a custom Python plugin.
• See JavaScript Middleware for more details on using JavaScript Middleware.

​

Set Physical Key Expiry and Deletion

• When a key expires, it remains in the Redis storage but is no longer valid. Consequently, it is no longer authorized to access any APIs. If a key in Redis has expired and is passed in an API request, Tyk will return HTTP 401 Key has expired, please renew.
• When a key is deleted from Redis, Tyk no longer knows about it, so if it is passed in an API request, Tyk will return HTTP 400 Access to this API has been disallowed.

​

Key expiry

​

Key lifetime

1. At the API level
2. At the Gateway level

​

API-level key lifetime control

"session_lifetime": 86400

​

Gateway-level key lifetime control

​

Summary of key lifetime precedence

​

Enable Mutual TLS

​

Why Use Mutual TLS?

​

Concepts

​

How Does Mutual TLS Work?

1. When a client attempts to connect to the server, the server requests the client’s TLS certificate.
2. The client provides its certificate, which the server verifies against a trusted Certificate Authority (CA).

1. Simultaneously, the client also verifies the server’s certificate against a trusted CA.

​

Benefits of Mutual TLS

• Enhanced Security: Provides two-way authentication, ensuring both the client and server are verified and trusted.
• Data Integrity: Protects the data exchanged between client and server by encrypting it, preventing tampering or interception.
• Compliance: Helps meet stringent security and compliance requirements, especially in regulated industries.

​

What is Mutual TLS?

​

Certificates

In cryptography, a public key certificate, also known as a digital certificate or identity certificate, is an electronic document used to prove the ownership of a public key. The certificate includes information about the key, information about the identity of its owner (called the subject), and the digital signature of an entity that has verified the certificate’s contents (called the issuer). If the signature is valid, and the software examining the certificate trusts the issuer, then it can use that key to communicate securely with the certificate’s subject.

1. Certificates without public keys used for authorization and authentication
2. Certificates with private keys used for upstream access, and server certificates (in other words when we need to sign and encrypt the request or response).

​

Certificate Management

• Create: POST /tyk/certs with PEM body. Returns {"id": "<cert-id>", ... }
• Delete: DELETE /tyk/certs/<cert-id>
• Get info: GET /tyk/certs/<cert-id>. Returns meta info about the certificate, something similar to:

{ 
  "id": "<cert-id>",
  "fingerprint": <fingerprint>,
  "has_private_key": false, 
  "issuer": <issuer>,
  "subject": "<cn>", ... 
}

• Get info about multiple certificates: GET /tyk/certs/<cert-id1>,<cert-id2>,<cert-id3>. Returns array of meta info objects, similar to above.
• List all certificate IDs: GET /tyk/certs. Returns something similar to:

{ "certs": "<cert-id1>", "<cert-id2>", ...  }

• Endpoints start with /api instead of /tyk, e.g. /api/certs, /api/certs/<cert-id>, etc.
• All certificates are managed in the context of the organization. In other words, certificates are not shared between organizations.

openssl x509 -noout -fingerprint -sha256 -inform pem -in <cert>.

MDCB

​

Authorization

Fallback to HTTP Authorization

​

Authentication

Using with Authorization

Upstream Access

HTTP/HTTPS Protocol

• BAD https://api.production.myupstream.com
• GOOD api.production.myupstream.com.

Wild Cards

​

Tips and Tricks

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

openssl x509 -noout -fingerprint -sha256 -inform pem -in <cert>

curl --cert client_cert.pem --key client_key.pem https://localhost:8181

​

mTLS for cloud users

• Cloud users can secure their upstream services with mTLS but mTLS between the client (caller of the API) and Tyk’s gateway cannot be done for the time being.
• Multi cloud users - since you own and manage the gateways, you can use mTLS for gateway <—> upstream as well as client <—> gateway connections.

​

Client mTLS

​

Dynamic Client mTLS

• Protect the API: Configure the API in the API Designer by setting the authentication type to Auth Token and enabling Client Certificate.
• Generate a Self-Signed Certificate: Use OpenSSL to generate a self-signed certificate and key if you don’t have one.
• Add a Key in the Dashboard: In the Tyk Dashboard, create a key for the API and upload only the public certificate.
• Make an API Request: Use curl with your certificate and key to make an API request to the protected API, ensuring the request returns a 200 response.
• Allow Developers to Upload Certificates: Create a policy and catalog entry for the API, allowing developers to request keys and upload their public certificates through the Developer Portal. Developers can then make API requests using their cert and private key.

Developer Portal - Self Serve Cert Trust

1. Create a policy for the API we set up above
2. Create a catalog entry for this policy
3. As a developer on the Portal, request a key for this API. This will take us to this screen:

$ curl -k \
       --cert cert.pem \
       --key key.pem \
       https://localhost:8080/mtls-api/my-endpoint

<200 response>

Protect the API

Generate a Self-Signed Key Pair

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Add a Key through the Dashboard

Make an API Request Using the Certificate

curl -k --cert cert.pem --key key.pem https://localhost:8080/mtls-api/my-endpoint

Allow Developers to Upload Certificates

1. Create a Policy: Create a policy for the API you set up earlier.
2. Create a Catalog Entry: Create a catalog entry for this policy.
3. Request a Key through the Portal: As a developer, request a key for the API through the Portal. This will present a screen where the developer can upload their public certificate.
4. Make an API Request Using the Uploaded Certificate: After adding the public certificate, developers can make API requests using their cert + private key:
   Copy

   Ask AI

   curl -k --cert cert.pem --key key.pem https://localhost:8080/mtls-api/my-endpoint
   

   A successful request should return a 200 response.

​

Static mTLS

Configure the API

Set the Base Identity

Setup Static mTLS in Tyk Operator using the Tyk Classic API Definition

1. Generate Self-Signed Key Pair:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

2. Create Kubernetes Secret:

kubectl create secret tls my-test-tls --cert cert.pem --key key.pem

3. Create API Definition:

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: httpbin-client-mtls
spec:
  name: Httpbin Client MTLS
  protocol: http
  active: true
  proxy:
    target_url: http://httpbin.org
    listen_path: /httpbin
    strip_listen_path: true
  version_data:
    default_version: Default
    not_versioned: true
    versions:
      Default:
        name: Default
  use_mutual_tls_auth: true
  client_certificate_refs:
    - my-test-tls

Setup Static mTLS in Tyk Operator using Tyk OAS API Definition

# Secret is not created in this manifest.
# Please store client certificate in k8s TLS secret `tls-cert`.

apiVersion: v1
data:
  test_oas.json: |-
    {
        "info": {
          "title": "Petstore",
          "version": "1.0.0"
        },
        "openapi": "3.0.3",
        "components": {},
        "paths": {},
        "x-tyk-api-gateway": {
          "info": {
            "name": "Petstore",
            "state": {
              "active": true
            }
          },
          "upstream": {
            "url": "https://petstore.swagger.io/v2"
          },
          "server": {
            "listenPath": {
              "value": "/petstore/",
              "strip": true
            }
          }
        }
      }
kind: ConfigMap
metadata:
  name: cm
  namespace: default
---
apiVersion: tyk.tyk.io/v1alpha1
kind: TykOasApiDefinition
metadata:
  name: petstore
spec:
  tykOAS:
    configmapRef:
      name: cm
      namespace: default
      keyName: test_oas.json
  clientCertificate: 
      enabled: true
      allowlist: [tls-cert]

FAQ

• Why am I getting an error stating that certificates are not enabled for this API? This issue can occur because client mTLS is an extension of Auth Token authentication mode. To enable this feature, ensure the API definition has auth.use_certificate set to true.
• Can I upload a full certificate chain when creating a key for dynamic client mTLS? Yes, you can do this when manually creating a key as an Admin Dashboard user. However, through the Portal, you must upload only the public key (certificate).
• Can I use a root CA with client mTLS? Yes, Tyk allows you to upload a root CA certificate for static mTLS authentication. This setup allows clients with certificates signed by the registered CA to be validated. Key Points:
  • The root CA certificate can be uploaded as a client certificate.
  • Clients presenting certificates signed by this CA will be validated.
  • Tyk traverses the certificate chain for validation.
  Root CA certificates are compatible only with Static mTLS and not with Dynamic mTLS.

​

Upstream mTLS

​

Key Features of Upstream mTLS

• Certificate Per Host: You can specify one certificate per host and define a default certificate.
• API-Level or Global Configuration: Upstream certificates can be defined at the API level or globally via the Gateway configuration file.
• JSVM Middleware Support: Specified client certificates will be used not only for internal Tyk calls but also for HTTP calls inside your JSVM middleware.

​

How To Set Up Upstream mTLS

{
  "upstream_certificates": {
    "example.com": "<cert-id>"
  }
}

​

Via Dashboard

1. Navigate to the API Designer.
2. Go to the Advanced Options panel.
3. Find the Upstream Certificates section and attach the appropriate certificate.

​

Via Tyk Operator using the Tyk Classic API Definition

• upstream_certificate_refs: Configure using certificates stored within Kubernetes secret objects.
• upstream_certificates: Configure using certificates stored within Tyk Dashboard’s certificate store.

upstream_certificate_refs

# First apply this manifest using the command
# "kubectl apply -f config/samples/httpbin_upstream_cert.yaml"
#
# The operator will try to create the ApiDefinition and will succeed but will log an error that a certificate is missing
# in the cluster for an upstream
#
# Generate your public-private key pair , for test you can use the following command to obtain one fast:
# "openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out tls.crt -keyout tls.key"
#
# Run the following command to obtain the values that must be put inside the yaml that contians the secret resource:
# "kubectl create secret tls my-test-tls --key="tls.key" --cert="tls.crt" -n default -o yaml --dry-run=client"
#
# Apply your TLS certificate using the following command: (we already have an example one in our repo)
# "kubectl apply -f config/sample/simple_tls_secret.yaml"
#
# NOTE: the upstream_certificate_refs can hold references to multiple secrets which are used for the domain
# mentioned in the key (currently "*" is used as a wildcard for all the domains)
apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: httpbin
spec:
  name: httpbin
  use_keyless: true
  upstream_certificate_refs:
    "*": my-test-tls
  protocol: http
  active: true
  proxy:
    target_url: http://httpbin.org
    listen_path: /httpbin
    strip_listen_path: true
  version_data:
    default_version: Default
    not_versioned: true
    versions:
      Default:
        name: Default

kubectl create secret tls my-test-tls --key="keyfile.key" --cert="certfile.crt" -n default -o yaml --dry-run=client
kubectl apply -f path/to/your/tls_secret.yaml

upstream_certificates

# Skip the concatenation and .pem file creation if you already have a certificate in the correct format

# First generate your public-private key pair , for test use you can use the following command to obtain one fast:
# "openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out tls.crt -keyout tls.key"

# Concatenate the above files to obtain a .pem file which we will upload using the dashboard UI
# "cat tls.crt tls.key > cert.pem"

# Upload it to the tyk certificate store using the dashboard

# Fill in the manifest with the certificate id (the long hash) that you see is given to it in the dashboard
# (in place of "INSERT UPLOADED CERTIFICATE NAME FROM DASHBOARD HERE")
# Optional: Change the domain from "*" to something more specific if you need to use different
# upstream certificates for different domains

# Then apply this manifest using the command
# "kubectl apply -f config/samples/httpbin_upstream_cert_manual.yaml"

# The operator will try create the ApiDefinition and will succeed and it will have the requested domain upstream certificate
# in the cluster for an upstream

# NOTE: the upstream_certificate can hold multiple domain-certificateName pairs
# (currently "*" is used as a wildcard for all the domains)

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: httpbin
spec:
  name: httpbin
  use_keyless: true
  upstream_certificates:
    "*": #INSERT UPLOADED CERTIFICATE NAME FROM DASHBOARD HERE#
  protocol: http
  active: true
  proxy:
    target_url: http://httpbin.org
    listen_path: /httpbin
    strip_listen_path: true
  version_data:
    default_version: Default
    not_versioned: true
    versions:
      Default:
        name: Default

apiVersion: tyk.tyk.io/v1alpha1
 kind: TykOasApiDefinition
 metadata:
   name: petstore
   namespace: default
 spec:
   tykOAS:
     configmapRef:
       name: petstore
       namespace: default
       keyName: petstore.json
   mutualTLS:
     enabled: true
     domainToCertificateMapping:
       - domain: "petstore.com"
         certificateRef: petstore-domain
       - domain: "petstore.co.uk"
         certificateRef: petstore-uk-domain

​

Domain Configuration

​

Wildcards

​

Default Upstream Certificate

{
  "upstream_certificates": {
    "*": "<cert-id>"
  }
}

​

Conclusion