Skip to main content

Authentication

Overview​

The authentication is designed to provide a secure way to authenticate users against an existing.

The authentication system serves the purpose of 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.

What happens is that Witboost will fetch all the configured groups and users from the organization provider. Then, when a user performs the login using the authentication provider, Witboost will check if the user is part of the fetched groups and if the user is 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:
      development:
        clientId: <clientId>
        clientSecret: <clientSecret>
        tenantId: <tenantId>
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityAnnotation
        title: 'Microsoft Login'
        message: 'Please login with your Microsoft account'

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:
      development:
        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: development
  providers:
    simple_ldap:
      development:
        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 is the name of the environment to enable. It will default to development 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:
      development:
        ...
        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:
      development:
        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.

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: OIDC - OpenID 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: development
  providers:
    okta:
      development:
        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.