SAML

Introduction to SAML authentication

Security Assertion Markup Language (SAML) Specification is an open standard for exchanging authentication and authorization data between parties, particularly between an identity provider and a service provider. SAML is useful for implementing secure single sign-on (SSO) in enterprise environments, allowing users to access multiple applications with a single set of credentials.

Refresh tokens are not supported

The SAML 2.0 connector in the platform does not support refresh tokens as the SAML 2.0 protocol does not provide a way to requery a provider without interaction. For more information, see the dex documentation for SAML 2.0.

1. Create platform Config For SAML v2.0

   The platform can use SAML v2.0 flow to identify the end user. To configure the platform to use SAML for SSO, follow these steps:

   1. Navigate to Admin > Config in the platform.
   2. Adjust your configuration as shown in the example below.
   3. Obtain the necessary values from your SAML identity provider (IdP) for the required fields.
   Configure the platform to use SAML

   auth:
     # Tell vCluster Platform to use saml authentication
     saml:
       #
       #
       # REQUIRED CONFIGURATION
       #
       #
       # SSO URL used for POST value.
       ssoURL: https://saml.example.com/sso
       # CA to use when validating the signature of the SAML response.
       ca: /path/to/ca.pem
       # Alternatively, CA can be provided inline as a base64-encoded blob
       # caData: (RAW base64-encoded PEM encoded CA)
       # Callback URL in the form of https://your-vcluster-platform-domain/auth/saml/callback
       redirectURI: https://vcluster-platform.my.domain/auth/saml/callback
       # Name of attributes in the returned assertions to map to ID token claims.
       usernameAttr: name
       emailAttr: email
       groupsAttr: groups # optional
       #
       #
       # OPTIONAL CONFIGURATION
       #
       #
       # (Optional) List of groups to filter access based on membership
       allowedGroups: ["Admins"]
       # (Optional) To skip signature validation, uncomment the following field. This should
       # only be used during testing and may be removed in the future
       insecureSkipSignatureValidation: true
       # (Optional) Manually specify vCluster Platform's Issuer value.
       # When provided vCluster Platform will include this as the Issuer value during AuthnRequest.
       # It will also override the redirectURI as the required audience when evaluating
       # AudienceRestriction elements in the response.
       entityIssuer: https://vcluster-platform.my.domain/auth/saml/callback
       # (Optional) Issuer value expected in the SAML response.
       ssoIssuer: https://saml.example.com/sso
       # (Optional) Delimiter for splitting groups returned as a single string.
       #
       # By default, multiple groups are assumed to be represented as multiple
       # attributes with the same name.
       #
       # If "groupsDelim" is provided groups are assumed to be represented as a
       # single attribute and the delimiter is used to split the attribute's value
       # into multiple groups.
       groupsDelim: ", "
       # (Optional) Requested format of the NameID.
       #
       # The NameID value is is mapped to the user ID of the user. This can be an
       # abbreviated form of the full URI with just the last component. For example,
       # if this value is set to "emailAddress" the format will resolve to:
       #
       #     urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
       #
       # If no value is specified, this value defaults to:
       #
       #     urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
       #
       nameIDPolicyFormat: persistent

2. Authenticate via SAML

   1. The platform should restart automatically.
   2. You should now be able to log in via SAML.
   3. Test the authentication by logging out and logging back in.

3. Disable Username + Password Authentication (optional)

   To turn off password-based authentication, navigate to Admin > Config add these two lines to your config:

   Disable password-based authentication

   auth:
     oidc: ...             # This is your SSO configuration (make sure this is working!)
     password:
       disabled: true      # Disable password-based authentication