SAML 2.0 Authentication

Refresh Tokens

The SAML 2.0 connector in dex 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).

STEP 1

Choose DEX_HOSTNAME And Configure DNS

Loft uses the CNCF project dex for single sign-on.

The easiest case is this one:

$LOFT_HOSTNAME = loft.mycompany.tld (where Loft is running)
$DEX_HOSTNAME = dex.mycompany.tld (where dex should be running)

STEP 2

Create Dex Config For SAML 2.0

Create the file dex-config.yaml with the following dex configuration:

ingress:
  enabled: true
  hosts:
  - dex.yourcompany.tld                                     # Use $DEX_HOSTNAME
config:
  issuer: https://dex.yourcompany.tld                       # "https://" + $DEX_HOSTNAME
  connectors:
  - type: saml
    id: saml
    name: SAML
    config:
      ssoURL: https://saml.example.com/sso                  # Your SSO POST URL
      # caData: ( base64 encoded PEM file )                 # CA to use when validating the signature of the SAML response.
      # insecureSkipSignatureValidation: true               # Not recommended (testing only)
      redirectURI: https://dex.yourcompany.tld/callback     # Use https:// + $DEX_HOSTNAME + /callback
      # entityIssuer: https://dex.yourcompany.tld/callback  # Optional: Use https:// + $DEX_HOSTNAME + /callback
      
      # Name of attributes in the returned assertions to map to ID token claims.
      usernameAttr: name
      emailAttr: email
      groupsAttr: groups # optional

      # List of groups to filter access based on membership
      # allowedGroups
      #   - Admins

      # Optional: Manually specify dex's Issuer value.
      #
      # When provided dex 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.

      # 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
  staticClients:
  - name: Loft
    id: loft                                              # Define a $DEX_CLIENT_ID
    secret: XXXXXXXXXXXXXX                                # Define a $DEX_CLIENT_SECRET (can be any secret key)
    redirectURIs:
    - 'https://loft.mycompany.tld/auth/oidc/callback'     # Loft URL + /auth/oidc/callback
  oauth2:
    skipApprovalScreen: true
  web:
    http: 0.0.0.0:5556
  storage:
    type: kubernetes
    config:
      inCluster: true

For details about configuring dex for SAML 2.0, take a look at the dex documentation for SAML 2.0.

STEP 3

Deploy Dex via Helm

After creating the file dex-config.yaml, you can now install dex via helm:

helm install dex dex --repo https://wiremind.github.com/wiremind-helm-charts \
  --create-namespace --namespace dex \
  -f dex-config.yaml \
  --wait

STEP 4

Configure Loft To Use Dex For Authentication

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

auth:
  oidc:
    issuerUrl: https://dex.mycompany.tld  # Use $DEX_HOSTNAME (see above)
    clientId: ""                          # Use $DEX_CLIENT_ID (see above)
    clientSecret: ""                      # Use $DEX_CLIENT_SECRET (see above)
    type: "github"                        # Optional: SSO Login Button Icon ("", github, gitlab, microsoft, google)
    usernameClaim: "email"                # Optional: Which part of the dex token to use as Loft username (default: email)
    usernamePrefix: ""                    # Optional: Add prefix to usernameClaim for Loft username
    groupsClaim: "groups"                 # Optional: Add Kubernetes groups for this user
    groupsPrefix: "loft-"                 # Optional: Prefix for Kubernetes groups
    caFile: ""                            # Optional: Path to a CA cert of dex within the Loft container (default: '')

STEP 5

Authenticate via Dex + SAML 2.0

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

STEP 6

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