Skip to main content

Authentication

Overview​

The authentication system serves the purpose of securely signing-in and identification of users. It is possible to configure any number of authentication providers, but only one of these will typically be used for sign-in.

To implement your desired authentication system, you need to configure:

  1. the authentication provider, which will perform the sign-in requests.
  2. the organization provider, which will provide the users and groups information.

When a user performs the login using the authentication provider, Witboost will check if the user is part of the user list fetched by the organization provider, if said user is part of the fetched groups, and if they are allowed to access the system.

In the following sections, we will provide an overview of how to configure every supported provider, by configuring both the authentication and organization providers.

tip

You can configure every Authentication Provider to display a custom title and message in the login page. To do so, you can add the title and message fields to the provider configuration. The title field will be displayed as the title of the login page, while the message field will be displayed as a message in the login page.

For example, you can customize the Microsoft provider configuration as follows:

auth:
  providers:
    microsoft:
      default:
        clientId: <clientId>
        clientSecret: <clientSecret>
        tenantId: <tenantId>
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityAnnotation
        title: 'Microsoft Login'
        message: 'Please login with your Microsoft account'

Authenticated Guest User​

Witboost comes with the ability to access the platform using a fixed set of guest users authenticated with a set of known credentials. These useres are intended only as a first approach to access the platform, especially on the first moments of the platform lifecycle where other authentication providers are not yet configured.

The allowed set of authenticated guest users are:

UsernameDefault RBAC Preset role
guest_adminADMINISTRATOR
guest_developerDP_OWNER on global scope
guest_userREAD_ONLY
info

Only a subset of these users may be available, depending on the configuration of the source for the credentials.

In case none of these users are configured or enabled, this authentication method is disabled

The Guest User credentials are fetched from the Witboost configuration and/or the license file: The configuration auth.providers.simple_guest_users.<authenvironment>.users takes priority and is written as shown below. If credentials for one of the users are not provided on configuration, the platform will try to fetch them (if present) from the license provided with the platform, and they're registered on Witboost. If user credentials are not provided neither in the configuration file, nor the license, the user won't be registered, and if already existent, will be deleted. Passwords are stored as hashes using scrypt and a random salt.

auth:
  environment: default
  providers:
    simple_guest_users:
      default: # Same as auth.environment
        users:
        - username: guest_admin
          password: A.v3ry.53cur3.p4ssw0rd!
        - username: guest_developer
          password: ...
          ...
  ...

If RBAC is active and the RBAC preset is registered, these guest users will be assigned an appropriate role in order to allow the installation team to access the platform, configure it, and test it.

If RBAC roles subjects are already configured for other users when installing or updating Witboost, this authentication method will be disabled.

Disabling this authentication method is possible via endpoint by calling POST /api/guest-users-auth/disable using a token from a user with the rbac.role.edit permission. We strongly recommend doing so after other more secure authentication providers have been configured. After disable, the guest user entities will still be present on the catalog until the next entity provider refresh cycle arrives.

Common errors​

Error: User not Found​

This is usually because there is a misalignment between enabled users and User entities present on the catalog. Trigger a manual refresh of the Witboost catalog by calling POST /api/catalog/guestusers/refresh and try again.

Authentication rejected​

This means that the user doesn't exist on the platform or is disabled on the database. Ensure that the credentials for said user are correctly configured in configuration or the license file, and user is set to enabled on the database.

Microsoft​

This section will guide you through the configuration of the Microsoft authentication provider.

Basically, this provider will use:

  1. An App Registration in Microsoft Entra ID to authenticate users.
  2. The Microsoft Graph API to fetch the users and groups information.

Authentication Provider​

First of all, we need an App Registration to be created in the Azure Portal. Depending on how locked down your company is, you may need a directory administrator to do some or all of these instructions.

Go to Azure Portal > App registrations and find your existing app registration, or create a new one.

On your App Registration's overview page, add a new Web platform configuration, with the configuration:

On the API permissions tab, click on Add Permission, then add the following (not Delegated) permissions (they will be needed for for Microsoft Graph):

  • GroupMember.Read.All
  • User.Read.All

Then, in the API permissions tab, click on Add Permission, then add the following Delegated permission for the Microsoft Graph API.

  • email
  • offline_access
  • openid
  • profile
  • User.Read

Your company may require you to grant admin consent for these permissions. Even if your company doesn't require admin consent, you may wish to do so as it means users don't need to individually consent the first time they access Witboost. To grant admin consent, a directory admin will need to come to this page and click on the Grant admin consent for COMPANY NAME button.

Then, to configure the Microsoft authentication provider, you need to provide the following configuration:

auth:
  providers:
    microsoft:
      default:
        clientId: <clientId>
        clientSecret: <clientSecret>
        tenantId: <tenantId>
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityAnnotation

where the clientId, clientSecret, and tenantId are the App Registration ones.

Organization Provider​

The Microsoft Graph API will be used to fetch the users and groups information. You can use the App Registration defined in the azure portal to access the Microsoft Graph API.

By default the graph plugin requires the following Application permissions (not Delegated) for Microsoft Graph (we already defined them in the section above):

  • GroupMember.Read.All
  • User.Read.All

If your organization required Admin Consent for these permissions, that will need to be granted.

To configure the Microsoft organization provider, you need to provide the following configuration:

catalog:
  providers:
    microsoftGraphOrg:
      default:
        target: https://graph.microsoft.com/v1.0
        authority: https://login.microsoftonline.com
        # If you don't know you tenantId, you can use Microsoft Graph Explorer
        # to query it
        tenantId: <tenantId>
        # Client Id and Secret can be created under Certificates & secrets in
        # the App registration in the Microsoft Azure Portal.
        clientId: <clientId>
        clientSecret: <clientSecret>
        userGroupMember:
          filter: "displayName eq 'witboost'"
        group:
          filter: "displayName eq 'witboost'"
        schedule:
          frequency: { hours: 5 }
          timeout: { minutes: 30 }

where the clientId, clientSecret, and tenantId are the App Registration ones.

In the example above, the userGroupMember and group filters are used to fetch the users and groups, belonging only to groups with certain properties (here you can use ).

The schedule configuration is used to define the frequency and timeout of the fetching process. The frequency represents the time between two fetches, while the timeout represents the maximum time the fetching process can take.

note

By default, the plugin will import all users and groups from your directory. This can be customized through filters and search queries. Keep in mind that if you omit filters and search queries for the user or group properties, the plugin will automatically import all available users or groups.

LDAP​

This section will guide you through the configuration of the LDAP authentication provider.

The provider will use the LDAP endpoint to authenticate users and fetch the users and groups information.

Authentication Provider​

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

auth:
  environment: default
  providers:
    simple_ldap:
      default:
        url: ldap://my.ldap.host.com
        bindDN: cn=admin,dc=my-company,dc=com
        bindCredentials: StrongAdminPassword
        searchBase: ou=users,dc=my-company,dc=com
        searchFilter: (uid={{username}})

where:

  • url is the LDAP server URL.
  • bindDN is the distinguished name of the user that will be used to bind to the LDAP server.
  • bindCredentials is the password of the user that will be used to bind to the LDAP server.
  • searchBase is the base DN for the search.
  • searchFilter is the filter to use when searching for users.
  • environment defines the name of the environment to enable as each provider can be configured for different environments, matching the key under the provider object. It will default to default if not provided.

In addition, you can also add the tlsOptions in case you want to use a secure connection to the LDAP server (ldaps). The configuration will look like this:

auth:
  providers:
    simple_ldap:
      default:
        ...
        tlsOptions:
          host: my.ldap.host.com
          port: 636
          minDHSize: 1024
          servername: my.ldap.host.com
          timeout: 30000

Organization Provider​

To configure the LDAP organization provider, you need to provide the following configuration:

catalog:
  providers:
    ldapOrg:
      default:
        target: ldap://my.ldap.host.com
        bind:
          dn: cn=admin,dc=my-company,dc=com
          secret: StrongAdminPassword
        users:
          dn: ou=users,dc=my-company,dc=com
          map:
            name: uid
            displayName: displayName
            email: mail
        groups:
          dn: ou=groups,dc=my-company,dc=com
          map:
            name: cn
            displayName: cn
            userMembers: memberUid
        schedule:
          frequency: { hours: 5 }
          timeout: { minutes: 30 }

where:

  • target is the LDAP server URL.
  • bind is the distinguished name of the user that will be used to bind to the LDAP server and its password.
  • users is the base DN for the users search and the mapping of the user properties.
  • groups is the base DN for the groups search and the mapping of the group properties.

The schedule configuration is used to define the frequency and timeout of the fetching process. The frequency represents the time between two fetches, while the timeout represents the maximum time the fetching process can take.

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.)

Okta​

This section will guide you through the configuration of the Okta authentication provider.

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

Authentication Provider​

First of all, to add Okta authentication, you must create an Application from Okta:

  1. Log into Okta (e.g. company.okta.com)
  2. Navigate to Menu >> Applications >> Applications >> Create App Integration
  3. Fill out the Create a new app integration form:
  • Sign-in method: Okta Connect
  • Application type: Web Application
  • Click Next
  1. Fill out the New Web App Integration form:
  • App integration name: Witboost (or your custom app name)
  • Grant type: Authorization Code & Refresh Token
  • Sign-in redirect URIs: https://your-witboost.com/api/auth/okta/handler/frame (this will be the URL of your Witboost instance)
  • Sign-out redirect URIs: https://your-witboost.com (this will be the URL of your Witboost instance)
  • Controlled access: (select as appropriate)
  • Click Save

Then, to configure the Okta authentication provider, you need to provide the following configuration:

auth:
  environment: default
  providers:
    okta:
      default:
        clientId: <clientId>
        clientSecret: <clientSecret>
        audience: <audience>
        authServerId: <authServerId> # Optional
        idp: <idp> # Optional
        additionalScopes: <additionalScopes> # Optional
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityProfileEmail

where:

  • clientId is the client ID that you generated on Okta, e.g. 3abe134ejxzF21HU74c1
  • clientSecret is the client secret shown for the Application.
  • audience is The Okta domain shown for the Application, e.g. https://company.okta.com. If you are using custom domains, you can find the current domain by clicking on your name in the top right corner of the Okta top bar.
  • authServerId (Optional) is the authorization server ID for the Application
  • idp (Optional) is the identity provider for the application, e.g. 0oaulob4BFVa4zQvt0g3
  • additionalScopes (Optional) is a string of space separated scopes, that will be combined with the default scope value of openid profile email offline_access to adjust the scope sent to Okta during OAuth. This will have an impact on the dependent claims returned. For example, setting the additionalScopes value to groups will result in the claim returning a list of the groups that the user is a member of that also match the ID token group filter of the client app.

All the values referenced above are found on the Application page on your Okta site.

Organization Provider​

This integration will be used to fetch the users and groups information.

To enable this type of integration, you will need to grant your application at least the okta.groups.read and okta.users.read scopes. To do so, you will need to go to the Okta Admin Console, navigate to the Applications section, and edit the application you created for Witboost. Then, go to the Okta API Scopes tab, and assign the okta.groups.read and okta.users.read scopes to the application.

Then, you will need to create an API token to be used by Witboost:

  1. In the Admin Console, go to Security > API
  2. Click the Tokens tab.
  3. Click Create token.
  4. In the What do you want your token to be named? field, enter a token name (like "Witboost")
  5. From the API calls made with this token must originate from dropdown list, select an option to specify where you allow connections to come from.
  6. Click Create token.
  7. Click Copy to clipboard (Copy token) and paste the token in a secure location, such as a password manager. The only time you can view and copy the token is during the creation process. After the token is created, it's stored as a hash for your protection.

Then you can configure the Okta organization provider, by providing the following configuration:

catalog:
  providers:
    okta:
      default:
        orgUrl: <orgUrl>
        token: <apiToken>
        userFilter: profile.department eq "engineering" # Optional
        groupFilter: profile.name eq "Everyone" # Optional
        hierarchyConfig: # Optional
          key: profile.orgId
          parentKey: profile.parentOrgId
        schedule:
          frequency: { hours: 5 }
          timeout: { minutes: 10 }
          initialDelay: { minutes: 1 }

where:

  • orgUrl is the URL of your Okta organization, e.g. https://company.okta.com
  • apiToken is the API token you created in the previous steps
  • userFilter (Optional) is a filter to apply to the users fetched from Okta
  • groupFilter (Optional) is a filter to apply to the groups fetched from Okta
  • hierarchyConfig (Optional) is a configuration to define the hierarchy of the groups. The key is the property that will be used as the group ID, while the parentKey is the property that will be used as the parent group ID.
  • schedule is used to define the frequency and timeout of the fetching process. The frequency represents the time between two fetches, while the timeout represents the maximum time the fetching process can take.
note

Try to keep the initialDelay value around 1 minute to avoid any issues with the initial fetch, since the Okta service may take some time to setup to the first interaction.