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:
- the authentication provider, which will perform the sign-in requests.
- 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:
- An App Registration in Microsoft Entra ID to authenticate users.
- 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.
- 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.
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.