Oauth2

This section will guide you through the configuration of a generic Oauth2 authentication provider, using OpenID Connect.

The provider will use the Oauth2 endpoint to authenticate users; users and groups must exist, and can be fetched using one of the other integrations proposed.

Authentication Provider

To configure the Oauth2 authentication provider, you need to provide the following configuration:

auth:
  session:
    secret: <secret>
  providers:
    oidc:
      default:
        clientId: <clientId>
        clientSecret: <clientSecret>
        metadataUrl: <metadataUrl>
        scope: openid #Optional
        prompt: auto
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityProfileEmail

where:

• secret is a unique string that will act as a session secret. There are no constraint on this value, but using a secret that cannot be guessed will reduce the ability to hijack a session to only guessing the session ID. You can configure this as an environment variable or reading it from a secret manager.
• clientId is the client ID of the Oauth2 application.
• clientSecret is the client secret of the Oauth2 application.
• metadataUrl is the URL of the OpenID Connect metadata, usually it should point to the published .well-known endpoint.
• callbackUrl (Optional) is the URL where the Oauth2 provider will redirect the user after the authentication process.
• scope (Optional) is a list of scopes requested to the application. It is a string with space-separated values.
• prompt should always be set to auto to show the end user the login window.

With this basic configuration (emailMatchingUserEntityProfileEmail), users are resolved by matching their email against the users loaded into Witboost by the chosen Organization Provider. If you need to customize the way users are resolved, you can remove the whole signIn section and add a custom logIn one, like:

auth:
  providers:
    oidc:
      default:
        clientId: <clientId>
        clientSecret: <clientSecret>
        metadataUrl: <metadataUrl>
        scope: openid #Optional
        prompt: auto
        logIn:
          user:
            annotation: 'microsoft.com/email'
          profile:
            attribute: 'result.fullProfile.userinfo.email'

In the example above, the user section is used to define the user entity as saved inside Witboost, while the profile section is used to define the profile entity fetched from the provider; in this case, the user is resolved by matching the userinfo.email returned by OpenId COnnect, against the entity annotation microsoft.com/email. You can change the profile's attribute to match the one returned by the provider, and you can use two different values for the Witboost user:

• annotation to match any of the user entity annotations (like microsoft.com/email, backstage.io/ldap-rdn, etc.)
• attribute to match any of the user entity attributes (like metadata.name, spec.profile.email, etc.)