Authentication through SAML 2.0

WARNING

The SAML connector is unmaintained, likely vulnerable to authentication bypass vulnerablities, and is under consideration for deprecation (see #1884). Please consider switching to OpenID Connect, OAuth2, or LDAP for identity providers that support these protocols. If you have domain expertise in SAML/XMLDSig and would like to volunteer to maintain the connector please comment on the discussion.

Overview

The SAML provider allows authentication through the SAML 2.0 HTTP POST binding. The connector maps attribute values in the SAML assertion to user info, such as username, email, and groups.

The connector uses the value of the NameID element as the user’s unique identifier which dex assumes is both unique and never changes. Use the nameIDPolicyFormat to ensure this is set to a value which satisfies these requirements.

Unlike some clients which will process unprompted AuthnResponses, dex must send the initial AuthnRequest and validates the response’s InResponseTo value.

Caveats

The connector doesn’t support refresh tokens since the SAML 2.0 protocol doesn’t provide a way to requery a provider without interaction. If the “offline_access” scope is requested, it will be ignored.

The connector doesn’t support signed AuthnRequests or encrypted attributes.

Group Filtering

The SAML Connector supports providing a whitelist of SAML Groups to filter access based on, and when the groupsattr is set with a scope including groups, Dex will check for membership based on configured groups in the allowedGroups config setting for the SAML connector.

If filterGroups is set to true, any groups not part of allowedGroups will be excluded.

Configuration

  1. connectors:
  2. - type: saml
  3.   # Required field for connector id.
  4.   id: saml
  5.   # Required field for connector name.
  6.   name: SAML
  7.   config:
  8.     # SSO URL used for POST value.
  9.     ssoURL: https://saml.example.com/sso
  11.     # CA to use when validating the signature of the SAML response.
  12.     ca: /path/to/ca.pem
  14.     # Dex's callback URL.
  15.     #
  16.     # If the response assertion status value contains a Destination element, it
  17.     # must match this value exactly.
  18.     #
  19.     # This is also used as the expected audience for AudienceRestriction elements
  20.     # if entityIssuer isn't specified.
  21.     redirectURI: https://dex.example.com/callback
  23.     # Name of attributes in the returned assertions to map to ID token claims.
  24.     usernameAttr: name
  25.     emailAttr: email
  26.     groupsAttr: groups # optional
  28.     # List of groups to filter access based on membership
  29.     # allowedGroups
  30.     #   - Admins
  32.     # CA's can also be provided inline as a base64'd blob.
  33.     #
  34.     # caData: ( RAW base64'd PEM encoded CA )
  36.     # To skip signature validation, uncomment the following field. This should
  37.     # only be used during testing and may be removed in the future.
  38.     #
  39.     # insecureSkipSignatureValidation: true
  41.     # Optional: Manually specify dex's Issuer value.
  42.     #
  43.     # When provided dex will include this as the Issuer value during AuthnRequest.
  44.     # It will also override the redirectURI as the required audience when evaluating
  45.     # AudienceRestriction elements in the response.
  46.     entityIssuer: https://dex.example.com/callback
  48.     # Optional: Issuer value expected in the SAML response.
  49.     ssoIssuer: https://saml.example.com/sso
  51.     # Optional: Delimiter for splitting groups returned as a single string.
  52.     #
  53.     # By default, multiple groups are assumed to be represented as multiple
  54.     # attributes with the same name.
  55.     #
  56.     # If "groupsDelim" is provided groups are assumed to be represented as a
  57.     # single attribute and the delimiter is used to split the attribute's value
  58.     # into multiple groups.
  59.     groupsDelim: ", "
  61.     # Optional: Requested format of the NameID.
  62.     #
  63.     # The NameID value is is mapped to the user ID of the user. This can be an
  64.     # abbreviated form of the full URI with just the last component. For example,
  65.     # if this value is set to "emailAddress" the format will resolve to:
  66.     #
  67.     #     urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  68.     #
  69.     # If no value is specified, this value defaults to:
  70.     #
  71.     #     urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  72.     #
  73.     nameIDPolicyFormat: persistent

A minimal working configuration might look like:

  1. connectors:
  2. - type: saml
  3.   id: okta
  4.   name: Okta
  5.   config:
  6.     ssoURL: https://dev-111102.oktapreview.com/app/foo/exk91cb99lKkKSYoy0h7/sso/saml
  7.     ca: /etc/dex/saml-ca.pem
  8.     redirectURI: http://127.0.0.1:5556/dex/callback
  9.     usernameAttr: name
  10.     emailAttr: email
  11.     groupsAttr: groups