Combine Authentication Methods

Introduction

Tyk provides flexible multi-authentication capabilities, allowing you to combine various authentication methods using different logical approaches:

• AND logic: All configured authentication methods must succeed before granting access
• OR logic: Any one of the configured authentication methods can grant access (Tyk OAS APIs only)

This enables scenarios such as requiring both Bearer Token authentication and Basic Auth simultaneously, or allowing access via either JWT validation or API key authentication.

    graph LR
    Client([Client]) -->|Request| Gateway[Tyk Gateway]
    
    subgraph "Multiple Authentication"
        Gateway --> Auth1[Authentication Method 1<br>e.g., API Key]
        Auth1 --> Auth2[Authentication Method 2<br>e.g., Basic Auth]
        Auth2 --> Auth3[Authentication Method N<br>e.g., JWT]
        Auth3 --> SessionCreation[Create Session<br>& Apply Policies]
        SessionCreation --> AccessDecision{Access<br>Decision}
    end
    
    AccessDecision -->|Granted| Upstream[(Upstream<br>API)]
    AccessDecision -->|Denied| Reject[Reject Request]
    
    %% Styling
    classDef client fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef gateway fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef auth fill:#e2f0fb,stroke:#0275d8,stroke-width:1px
    classDef session fill:#d1ecf1,stroke:#17a2b8,stroke-width:1px
    classDef decision fill:#cce5ff,stroke:#0275d8,stroke-width:2px
    classDef upstream fill:#f8f9fa,stroke:#6c757d,stroke-width:2px
    classDef reject fill:#f8d7da,stroke:#dc3545,stroke-width:2px
    
    class Client client
    class Gateway gateway
    class Auth1,Auth2,Auth3 auth
    class SessionCreation session
    class AccessDecision decision
    class Upstream upstream
    class Reject reject
  

Use Cases

• Multi-tenant APIs: Different tenants using different identity providers
• Migration scenarios: Supporting both legacy and modern auth during transitions
• Partner integrations: External partners use mTLS while internal users use JWT
• Mobile + Web: Different auth methods for different client types

Understanding Authentication Modes

    graph LR
    Client([Client]) -->|Request| Gateway[Tyk Gateway]
    
    subgraph "Tyk Multiple Authentication"
        Gateway --> AuthConfig{Authentication<br>Configuration}
        
        %% Legacy Mode
        AuthConfig -->|Legacy Mode| LegacyAuth["AND Logic<br>(All must pass)"]
        LegacyAuth --> Auth1[Auth Method 1]
        Auth1 --> Auth2[Auth Method 2]
        Auth2 --> SessionCreation["Create Session<br>(from BaseIdentityProvider)"]
        
        %% Compliant Mode
        AuthConfig -->|Compliant Mode| CompliantAuth["OR Logic<br>(Any group can pass)"]
        CompliantAuth --> Group1["Group 1<br>(AND Logic)"]
        CompliantAuth --> Group2["Group 2<br>(AND Logic)"]
        
        Group1 --> G1Auth1["Auth Method A"]
        G1Auth1 --> G1Auth2["Auth Method B"]
        
        Group2 --> G2Auth1["Auth Method C"]
        G2Auth1 --> G2Auth2["Auth Method D"]
        
        G1Auth2 --> DynamicSession1["Create Session<br>(from last auth in group)"]
        G2Auth2 --> DynamicSession2["Create Session<br>(from last auth in group)"]
        
        SessionCreation --> AccessDecision
        DynamicSession1 --> AccessDecision
        DynamicSession2 --> AccessDecision
        
        AccessDecision{Access<br>Decision}
    end
    
    AccessDecision -->|Granted| Upstream[(Upstream<br>API)]
    AccessDecision -->|Denied| Reject[Reject Request]
    
    %% Styling
    classDef client fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef gateway fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef auth fill:#e2f0fb,stroke:#0275d8,stroke-width:1px
    classDef group fill:#fff3cd,stroke:#ffc107,stroke-width:1px
    classDef session fill:#d1ecf1,stroke:#17a2b8,stroke-width:1px
    classDef decision fill:#cce5ff,stroke:#0275d8,stroke-width:2px
    classDef upstream fill:#f8f9fa,stroke:#6c757d,stroke-width:2px
    classDef reject fill:#f8d7da,stroke:#dc3545,stroke-width:2px
    
    class Client client
    class Gateway gateway
    class Auth1,Auth2,G1Auth1,G1Auth2,G2Auth1,G2Auth2,LegacyAuth,CompliantAuth auth
    class Group1,Group2 group
    class SessionCreation,DynamicSession1,DynamicSession2 session
    class AuthConfig,AccessDecision decision
    class Upstream upstream
    class Reject reject
  

Tyk OAS offers two modes for configuring multiple authentication methods:

• Legacy Mode (Default): Maintains backward compatibility with existing Tyk implementations using AND logic only
• Compliant Mode: Introduced in 5.10.0, provides enhanced flexibility by supporting both AND and OR logic between authentication methods

Legacy Mode

The Legacy mode is the traditional implementation of multi-auth, supported by Tyk Classic APIs and Tyk OAS APIs prior to Tyk 5.10.

In this mode, all configured authentication methods must be satisfied in the request (i.e., they are combined using AND logic).

How does the operation differ between Tyk Classic and Tyk OAS APIs?

• Tyk Classic API: All configured authentication methods must be satisfied in the request

• Tyk OAS API: Only the first security requirement object in the OpenAPI description’s security array is processed. All the authentication methods in the first object must be satisfied in the request, together with any proprietary auth methods enabled in the Tyk Vendor Extension.

  security:
    - api_key: []      # this security requirement is processed: both methods must be satisfied
      basic_auth: []  
    - jwt_auth: []     # Ignored in Legacy mode
  

Session Object Handling

In Legacy mode, the baseIdentityProvider setting determines which authentication method provides the session object. This setting must be configured to one of auth methods in the logical rule using the following mapping:

• auth_token - for token-based authentication
• jwt_claim - for JWT authentication
• basic_auth_user - for Basic Authentication
• hmac_key - for HMAC authentication
• custom_auth - for custom authentication plugin

Compliant Mode

The Compliant mode is named as such because Tyk complies with the security requirements declared in the OpenAPI description, combining different authentication methods using AND and OR logic as required.

OpenAPI Security Requirements

In OpenAPI, security is defined using Security Requirement Objects in the security section:

security:
  - api_key: []
    basic_auth: []  
  - jwt_auth: []
    oauth2: []

• Each security requirement object in the OAS security array represents an alternative, these are evaluated with OR logic.
• Within a single security requirement object, multiple security schemes can be declared and will combined using AND logic (i.e., all listed schemes must succeed together).
• A request is authorized if any one of the defined security requirement objects is successfully validated.
• The session object is determined dynamically based on which security requirement is satisfied
• This structure enables multi-auth configurations, supporting both combined (AND) and alternative (OR) authentication methods.

How OR Logic Works

When using Compliant mode with multiple security requirements:

• Tyk attempts each authentication method in sequence
• If any method succeeds, the request is authorized
• If all methods fail, the request is rejected with the error from the last attempted method

How AND Logic Works

Within a single security requirement object that contains multiple schemes:

• All schemes within that security requirement must be satisfied (AND logic)
• The request is only authorized if all schemes are valid
• If any scheme fails, the entire security requirement fails, and Tyk moves to the next one
• This allows for combining different authentication methods that must all be present

Examples

Here’s an example security object from an OpenAPI description with both AND and OR logic:

{
  "security": [
    {
      "scheme1": []
    },
    {
      "scheme2": [],
      "scheme3": []
    }
  ]
}

You will notice that the security object should contain references to security schemes that you’ve defined in the components.securitySchemes section of the OpenAPI description. In this example, the request will be authorized if either:

• scheme1 is provided (first security requirement)
• OR
• Both scheme2 AND scheme3 are provided (second security requirement with AND logic)

Session Object Handling

The session object (determining rate limits, quotas, and access rights) comes from the successful authentication method. This allows different auth methods to have different associated policies and permissions.

When using Compliant mode, the session object handling is more dynamic:

1. Between different security requirement objects (OR logic): The first security requirement that successfully authenticates will provide the session object.

2. Within a single security requirement object (AND logic): When multiple authentication methods are specified in the same requirement object (as in your example below), all methods must pass, and the last successfully processed authentication method will provide the session object.

Auth methods are always validated in the following order (and skipped if not included in the security requirement):

1. Tyk OAuth 2.0
2. External OAuth ((deprecated)
3. Basic Auth
4. HMAC
5. JWT
6. OpenID Connect (deprecated)
7. Custom Plugin Auth
8. Bearer / Auth Token (API Key)

For example, if this security requirement is satisfied in the request, the session metadata will come from the Auth Token, despite it being declared first in the security requirement:

security:
  - api_key: []
    basic_auth: []  

Choosing the Right Mode

Use Legacy Mode when:

• Migrating from or using Tyk Classic APIs
• You need the session metadata to be taken from an auth method earlier in the middleware processing order

Use Compliant Mode when:

• You need alternative auth methods (OR logic)
• Supporting multiple client types or identity providers
• For APIs that need to serve diverse client bases with different security requirements
• Building new APIs with flexible authentication requirements

Configuration Options

Security Processing Mode

The securityProcessingMode option in the Tyk Vendor Extension allows you to specify which mode to use when processing the security configuration in your API. This controls how Tyk will interpret the authentication settings in the OpenAPI description and the Vendor Extension.

x-tyk-api-gateway:
  server:
    authentication:
      securityProcessingMode: compliant // or legacy

Basic Example: API with Multiple Auth Methods

Here’s a simple example of an OpenAPI description that declares JWT and API Key security schemes:

# Example: API supporting either JWT OR API Key authentication
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: X-API-Key
      in: header
      description: "API key for service-to-service authentication"
    jwt_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "JWT token for user authentication"
security:
  - api_key: []      # Option 1: API key only
  - jwt_auth: []     # Option 2: JWT only

• If the securityProcessingMode in the Tyk Vendor Extension is set to compliant, Tyk will check incoming requests against each security option in turn, authenticating requests using Option 1 or Option 2.
• If the securityProcessingMode is set to legacy (or is omitted), Tyk will check requests only against the first security option (Option 1).

Configuring Multiple Auth Methods in the API Designer

You can configure chained authentication by following these steps:

1. Enable Authentication in the Servers section

2. Select the Multiple Authentication Mechanisms option from the drop-down list.

3. Select the Authentication Mode that you wish to use: Compliant or Legacy

   Select Compliant mode for full interpretation of the security requirements declared in the OpenAPI description, allowing for fully flexible authentication of your API clients:

   

   Use the API Editor view to configure the different security schemes and requirements to satisfy the client authentication needs of your API:

   

   Use Legacy mode for simple scenarios where you can select the Authentication methods that the client must satisfy in the request.

   You must identify the Base identity provider that will provide the session metadata:

   

   You can now configure each authentication method in the usual manner using the options in the API designer.

   

Advanced Configuration

Using Proprietary Auth Methods

Compliant mode allows you to combine standard OpenAPI security schemes with Tyk’s proprietary authentication methods by extending the OpenAPI security section into the Tyk Vendor Extension:

components:
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
    jwt_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - jwt_auth: []
x-tyk-api-gateway:
  server:
    authentication:
      securityProcessingMode: compliant
      security:
      - - hmac
        - api_key
      - - custom_auth
      securitySchemes:
        hmac:
          enabled: true
        custom_auth:
          enabled: true
          config:
            authType: coprocess

The extended security requirements in the vendor extension (x-tyk-api-gateway.server.authentication.security) are concatenated onto the requirements declared in the OpenAPI description. This configuration allows three authentication methods: JWT, API Key with HMAC, and Custom Auth.

Migration Considerations

Moving from Legacy to Compliant Mode

When migrating from Legacy to Compliant mode:

• Review your API’s authentication configuration
• Ensure all required security schemes are properly defined, for example any use of Tyk proprietary auth methods (HMAC, custom authentication) will need to be reflected with creation of new security requirements within the Vendor Extension’s security section and removal of requirements from the OpenAPI description’s security section
• Test thoroughly, as authentication behavior will change
• Be aware that the session object may come from different sources depending on which auth method succeeds

Backward Compatibility

Legacy mode ensures backward compatibility with existing Tyk implementations. If you’re unsure which mode to use, start with Legacy mode and migrate to Compliant mode when ready.

Troubleshooting

{
  "global": {
    "log_level": "debug"
  }
}