SAML

Refresh Tokens

The SAML 2.0 connector in vCluster.Pro 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.Pro Config For SAML v2.0**

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

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

   auth:
     # Tell vCluster.Pro 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-pro-domain/auth/saml/callback
       redirectURI: https://vcluster-pro.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.Pro's Issuer value.
       # When provided vCluster.Pro 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-pro.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.Pro configuration, vCluster.Pro 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