Skip to main content

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