SAML

This plugin provides Security Assertion Markup Language (SAML) v2.0 authentication and authorization between Kong Gateway and an identity provider.

The SAML specification defines three roles:

• A principal
• An identity provider (IdP)
• A service provider (SP)

The SAML plugin acts as the SP and is responsible for initiating a login to the IdP. This is called an SP Initiated Login.

The minimum configuration required is:

• An IdP certificate (idp_certificate): The SP needs to obtain the public certificate from the IdP to validate the signature. The certificate is stored on the SP and is used to verify that a response is coming from the IdP.
• The ACS Endpoint (assertion_consumer_path): This is the endpoint provided by the SP where SAML responses are posted. The SP needs to provide this information to the IdP.
• The IdP sign-in URL (idp_sso_url): This is the IdP endpoint where SAML will issue POST requests. The SP needs to obtain this information from the IdP.
• The issuer (issuer): This is the unique identifier of the IdP application.

The plugin validates the SAML response signature whenever you set idp_certificate, even when validate_assertion_signature is false. If you set validate_assertion_signature to false and don’t configure idp_certificate, the plugin skips signature validation and accepts unsigned responses, which is insecure. Always set idp_certificate.

The plugin currently supports SAML 2.0 with Microsoft Entra. Refer to the Microsoft Entra SAML documentation for more information about SAML authentication with Azure AD.

As the SP-initiated mode of SAML requires the client to authenticate to the IdP using a web browser, the plugin is only useful when it’s used with a browser-based web application.

It’s designed to intercept requests sent from the client to the upstream to detect whether a session has been established by authenticating with the IdP. If no session is found, the request is redirected to the IdP’s login page for authentication. Once the user has successfully authenticated, the user is redirected to the application and the original request is sent to the upstream server.

The authentication process can only be initiated when the request is coming from a web browser. The plugin determines this by matching the request’s Accept header. If it contains the string "text/html", the request is redirected to the IdP, otherwise it’s responded to with a 401 (Unauthorized) status code.

The plugin initiates the redirection to the IdP’s login page by responding with an HTML form that contains the authentication request details in hidden parameters and some JavaScript code to automatically submit the form. This is needed because the authentication parameters need to be transmitted to Microsoft Entra’s SAML implementation using a POST request, which cannot be done with a HTTP redirect response.

The plugin supports initiating the IdP authentication flow from a POST request, to support the use case that the session expires while the user is filling out a web form. In such scenarios, the plugin transmits the posted form parameters to the IdP in the RelayState parameter in encrypted form. When the authentication process finishes, the IdP sends the RelayState back to the plugin. After decryption, the plugin then responds back to the web browser with another automatically self-submitting form containing the original form parameters as hidden parameters. This feature is only available with forms that use "application/x-www-form-urlencoded" as their content type. Forms that use "text/plain" or "multipart/form-data" are not supported.

When the authentication process has finished, the plugin creates and maintains a session inside of Kong Gateway. A cookie in the browser is used to track the session. Data that is attached to the session can be stored in Redis, Memcached, or in the cookie itself.

Note: The lifetime of the session that is created by the IdP needs to be configured in the plugin.

If your plugin uses a Redis datastore, you can authenticate to it with a cloud Redis provider. This allows you to seamlessly rotate credentials without relying on static passwords.

The following providers are supported:

• AWS ElastiCache
• Azure Managed Redis
• Google Cloud Memorystore (with or without Valkey)

Each provider also supports an instance and cluster configuration.

config:
  session_storage: redis
  redis:
    host: $INSTANCE_ADDRESS
    username: $INSTANCE_USERNAME
    port: 6379
    cloud_authentication:
      auth_provider: aws
      aws_cache_name: $AWS_CACHE_NAME
      aws_is_serverless: false
      aws_region: $AWS_REGION
      aws_access_key_id: $AWS_ACCESS_KEY_ID
      aws_secret_access_key: $AWS_ACCESS_SECRET_KEY

config:
  session_storage: redis
  redis:
    cluster_nodes:
    - ip: $CLUSTER_ADDRESS
      port: 6379
    username: $CLUSTER_USERNAME
    port: 6379
    cloud_authentication:
      auth_provider: aws
      aws_cache_name: $AWS_CACHE_NAME
      aws_is_serverless: false
      aws_region: $AWS_REGION
      aws_access_key_id: $AWS_ACCESS_KEY_ID
      aws_secret_access_key: $AWS_ACCESS_SECRET_KEY

config:
  session_storage: redis
  redis:
    host: $INSTANCE_ADDRESS
    username: $INSTANCE_USERNAME
    port: 10000
    cloud_authentication:
      auth_provider: azure
      azure_client_id: $AZURE_CLIENT_ID
      azure_client_secret: $AZURE_CLIENT_SECRET
      azure_tenant_id: $AZURE_TENANT_ID

config:
  session_storage: redis
  redis:
    cluster_nodes:
    - ip: $CLUSTER_ADDRESS
      port: 10000
    username: $CLUSTER_USERNAME
    port: 10000
    cloud_authentication:
      auth_provider: azure
      azure_client_id: $AZURE_CLIENT_ID
      azure_client_secret: $AZURE_CLIENT_SECRET
      azure_tenant_id: $AZURE_TENANT_ID

config:
  session_storage: redis
  redis:
    host: $INSTANCE_ADDRESS
    port: 6379
    cloud_authentication:
      auth_provider: gcp
      gcp_service_account_json: $GCP_SERVICE_ACCOUNT

config:
  session_storage: redis
  redis:
    cluster_nodes:
    - ip: $CLUSTER_ADDRESS
      port: 6379
    port: 6379
    cloud_authentication:
      auth_provider: gcp
      gcp_service_account_json: $GCP_SERVICE_ACCOUNT

You may have a valid certificate specified in the idp_certificate field, but you get the following error:

[saml] user is unauthorized with error: public key in saml response does not match

If you provide a certificate through the idp_certificate field, the certificate must have the header and footer removed.

For example, a standard certificate might look like this, with a header and footer:

-----BEGIN CERTIFICATE-----
<certificate contents>
-----END CERTIFICATE-----

Remove the header and footer before including the certificate in the idp_certificate field:

<certificate contents>