saml-auth

Authenticates users with a SAML identity provider.

Category AuthenticationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin saml-authPriority 2598

What it does

saml-auth signs people in at a SAML identity provider before their browser reaches the route's backend. The people live at the identity provider at IdP URI, not on a consumer. The gateway takes part as a service provider named by SP issuer, signs its requests with the SP private key and checks the provider's answers against the IdP certificate.

Login callback URI, Logout URI and Logout callback URI are paths of the route, /saml/callback for example, and not full addresses. Authentication explains callers who sign in at an identity provider.

When to use it

• The company's identity provider speaks SAML, and an internal web application behind the gateway should use the same sign-in as every other company application.
• A backend that has no sign-in of its own should be reached only by people the identity provider signed in.
• People sign out at one path of the route and land on a page of your choice, under Logout redirect URI.

Not for an OpenID Connect provider or bearer tokens on API calls — see openid-connect (Authenticates users against an OpenID Connect provider), a CAS server — see cas-auth (Authenticates users against a CAS server) or a directory name and password a program sends on every call — see ldap-auth (Authenticates consumers against an LDAP directory).

Set it up

Sign users in through your identity provider with SAML

Under Basics set IdP URI to https://idp.example.com/saml/sso, set IdP certificate to <certificate PEM>, set SP issuer to https://api.example.com/saml/metadata, set SP certificate to <certificate PEM>, set SP private key to <private key PEM>, set Secret to <secret>, set Login callback URI to /saml/callback, set Logout URI to /saml/logout, set Logout callback URI to /saml/logout/callback and set Logout redirect URI to https://www.example.com/signed-out. Under Behavior fill IdP issuers as in the JSON below and set Replay dictionary to plugin-saml-auth-replay.

saml-auth · as the console saves it

{
  "idp_uri": "https://idp.example.com/saml/sso",
  "idp_cert": "<certificate PEM>",
  "idp_issuers": [
    "https://idp.example.com/saml/metadata"
  ],
  "sp_issuer": "https://api.example.com/saml/metadata",
  "sp_cert": "<certificate PEM>",
  "sp_private_key": "<private key PEM>",
  "secret": "<secret>",
  "replay_dict": "plugin-saml-auth-replay",
  "login_callback_uri": "/saml/callback",
  "logout_uri": "/saml/logout",
  "logout_callback_uri": "/saml/logout/callback",
  "logout_redirect_uri": "https://www.example.com/signed-out"
}

Things to know

• SP private key — The authentication request is signed with RSA-SHA512, so an elliptic-curve key is stored and then answers 500 on every request.
• Logout URI — Write a path on this route, such as /saml/logout: a full URL never matches and the request goes to the identity provider. Requests to it never reach the upstream; without a session cookie they get 401.
• Logout URI — An address that starts with //, //idp.example.com/logout for example, is refused when you save.
• Login callback URI — A full address in place of a path is refused when you save.
• Logout callback URI — A full address in place of a path is refused when you save.
• Secret — A secret shorter than 8 characters is refused when you save.
• Auth protocol binding method — With HTTP-POST the session cookie is also marked Secure and SameSite=None.
• Auth protocol binding method — Only HTTP-POST and HTTP-Redirect can be set; HTTP-Artifact is refused when you save.
• Replay dictionary — Only plugin-saml-auth-replay can be set; a dictionary of any other name is refused when you save.
• AdviceRegister the SP issuer and the Login callback URI at the identity provider exactly as they are written here, and serve the route over HTTPS only.
• On a consumer or a consumer group it runs only after the consumer has been identified by a credential; it does not identify the consumer itself.

Settings

The fields as the console shows them, section by section.

Basics

IdP URIidp_uristringRequired

example https://idp.example.com/saml/sso

IdP certificateidp_certstringRequired

SP issuersp_issuerstringRequired

SP certificatesp_certstringRequired

SP private keysp_private_keystringRequired

Sent to the engine and never shown again.

SecretsecretstringRequired

The secret the session keys are derived from: a random value, the same on every node. Stored on the engine and shown only to roles that manage this object.

8 to 32 characters

Login callback URIlogin_callback_uristringRequired

a path starting with one slash, or a $secret:// or $env:// reference

pattern

^(/(?!/)|[$]secret://.+|[$][Ee][Nn][Vv]://.+)

Logout URIlogout_uristringRequired

a path starting with one slash, or a $secret:// or $env:// reference

pattern

^(/(?!/)|[$]secret://.+|[$][Ee][Nn][Vv]://.+)

Logout callback URIlogout_callback_uristringRequired

a path starting with one slash, or a $secret:// or $env:// reference

pattern

^(/(?!/)|[$]secret://.+|[$][Ee][Nn][Vv]://.+)

Logout redirect URIlogout_redirect_uristringRequired

Behavior

Auth protocol binding methodauth_protocol_binding_methodstringdefault HTTP-Redirect

How the identity provider carries its answer back to the login callback. HTTP-POST also makes the session cookie Secure and SameSite=None, and this form has no separate switches for either.

one of HTTP-POST, HTTP-Redirect

IdP issuersidp_issuersarray of strings

Issuers an assertion may come from; unset accepts any, an empty list accepts none.

Audiencessp_audiencesarray of strings

Audiences an assertion must name; unset, the SP issuer is expected.

Clock skewclock_skewnumber

Tolerated clock difference with the identity provider; unset, a minute.

at least 0 · in seconds

Replay dictionaryreplay_dictstring

Records accepted assertions on this node so none is accepted twice; the one dictionary the engine declares. Not set, a one-time assertion is accepted and only logged.

at least 1 character · one of plugin-saml-auth-replay

Advanced

Secret fallbackssecret_fallbacksarray of strings

Older secrets a cookie may still be signed with while a new one rolls out. Stored on the engine and shown only to roles that manage this object.

each 8 to 32 characters

Replay record timereplay_ttlnumber

How long an assertion without an expiry of its own stays recorded; read only with a replay dictionary, and unset means ten minutes.

at least 1 · in seconds

ACS URLsp_acs_urlstring

The absolute external address of the assertion consumer; unset, it is derived from the request.

an http or https address

pattern

^https?://

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.