Version: v4.4 Stable

OpenID Connect

OIDC authentication

OpenID Connect Specification is an authentication layer built on top of OAuth 2.0, providing secure and standardized user authentication for applications. Implementing OIDC in the platform offers several benefits:

Enhanced security through token-based authentication
Simplified user management with centralized identity providers
Improved user experience with single sign-on (SSO) capabilities

Create platform config for OIDC

To configure OIDC for SSO, follow these steps:

Navigate to Admin > Config in the platform.
Adjust your configuration as shown in the example below.

Platform OIDC configuration
auth:
  # Tell vCluster Platform to allow OIDC for authentication
  oidc:
    #
    #
    # REQUIRED CONFIGURATION
    #
    #
    # IssuerURL is the URL the provider signs ID Tokens as.
    # If using Keycloak provide the realm as well, only providing the base URL will return a 404. Ex. https://your-keycloak/realms/YOUR-REALM
    issuerUrl: https://accounts.google.com
    # ClientID the JWT must be issued for, the "sub" field. Can be string literal or pulled from the environment.
    clientId: $CLIENTID
    # ClientSecret to issue tokens from the OIDC provider. Can be string literal or pulled from the environment.
    clientSecret: $CLIENTSECRET
    # Callback URL in the form of https://your-loft-domain/auth/oidc/callback
    redirectURI: https://vcluster-platform.my.domain/auth/oidc/callback
    #
    #
    # OPTIONAL CONFIGURATION
    #
    #
    # (Optional) Path to a PEM encoded root certificate of the provider.
    caFile: /tmp/ca-file.crt
    # (Optional) Specify whether to communicate without validating SSL certificates
    insecureCa: false
    # (Optional) UsernameClaim is the JWT field to use as the user's username.
    # If not set defaults to email.
    usernameClaim: email
    # (Optional) If specified, causes claims mapping to username to be prefix with
    # the provided value.
    usernamePrefix: my-prefix-
    # (Optional) If specified, causes the OIDCAuthenticator to try to populate the user's
    # groups with an ID Token field.
    groupsClaim: groups
    # (Optional) If specified, causes claims mapping to group names to be prefixed with the
    # value.
    groupsPrefix: group-prefix-
    # (Optional) If groups is non empty, access is denied if the user is not part of at least one
    # of the specified groups. This requires groupsClaim to be set!
    groups: ["my-oidc-group"]
    # (Optional) If specified, tells the OIDCAuthenticator to try to populate the user's
    # information from the UserInfo. This might be necessary for slim tokens such as used
    # by Okta
    getUserInfo: false
    # (Optional) Scopes that should be sent to the server. If empty, defaults to "email" and "profile".
    scopes: ["profile", "email"]
    # (Optional) EmailClaim is the JWT field to use as the user's email.
    emailClaim: "email"
    # (Optional) vCluster PlatformUsernameClaim is the JWT field to use as the user's ID (Kubernetes name) and username
    loftUsernameClaim: "name"
    # (Optional) PreferredUsername is the JWT field to use as the user's display name
    preferredUsername: "preferred_username"
    # (Optional) AllowedExtraClaims are claims of interest that are provided by the OIDC provider but may not already be
    # covered by a User field. These additional claims of interest will be copied to User.Spec.ExtraClaims.
    # Like other claims, User.Spec.ExtraClaims is only updated when the User logs in using the OIDC provider. A user must
    # login after changes to AllowedExtraClaims for them to be reflected in a User's User.Spec.ExtraClaims.
    allowedExtraClaims: ["department"]

Obtaining OIDC credentials

To obtain the required clientId and clientSecret, refer to your OIDC provider's documentation. Common providers include:

Authenticate via OIDC
After saving the new configuration, the platform should restart. You should then be able to log in via your OIDC provider.

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

OIDC authentication​

OIDC authentication