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.

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:

• Redirect URI: https://your-witboost.com/api/auth/microsoft/handler/frame (this will be the URL of your Witboost instance)
• Front-channel logout Url: blank
• Implicit grant and hybrid flows: All unchecked

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:
  providers:
    simple_ldap:
      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.

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