SAML

Refresh Tokens

The SAML 2.0 connector in vCluster Platform does not support refresh tokens "since the SAML 2.0 protocol doesn't provide a way to requery a provider without interaction" (see dex documentation for SAML 2.0).

1. Create vCluster Platform Config For SAML v2.0

   vCluster Platform is able to use SAML v2.0 flow to identify the end user.

   To tell vCluster Platform to use SAML for SSO, navigate to Admin > Config in vCluster Platform and adjust your config as shown below:

   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
       # CA's can also be provided inline as a base64'd blob.
       #
       # caData: ( RAW base64'd 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

   After saving the new vCluster Platform configuration, vCluster Platform will restart itself and you should be able to log in via SAML.

3. Disable Username + Password Authentication (optional)

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

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