How To Configure OAuth
Aleph ships with a built-in password authentication system. However, we recommend delegating authentication to an OAuth identity provider. If you’re organization already uses an identity provider, this allows your users to use Aleph without setting up a separate account. Even if you do not yet use an identity provider, this provides additional security features such as multi-factor authentication.
Disable password authentication
When setting up an external identity provider, you most like won’t want users to create accounts using Aleph’s built-in password authentication system. You can disable password authentication by setting the ALEPH_PASSWORD_LOGIN configuration option to false.
If you do not disable password authentication, anyone will still be able to create an account or sign in using password authentication.
Configure OAuth
Aleph has built-in support for the identity providers listed below. Other identity providers that support the OpenID Connect standard may work with Aleph, too.
However, we can unfortunately not guarantee that the instructions below are always up to date. If you’re using one of the identity providers listed below and find that the instructions are outdated or if you use an identity provider not listed we’d appreciate if you could open a pull request with updated instructions.
User groups are not standardized in OpenID and Aleph currently doesn’t support syncing user groups when using Google as an identity provider.
-
Create an OAuth client in the Google Cloud console. Please refer to the Google Cloud documentation for detailed instructions.
-
If you want to allow only users in your organization to access your Aleph instance, make sure to select the correct user type.
-
In the Google Cloud console, add Aleph’s OAuth endpoint as an authorized redirect URI. For example, if your Aleph instance is available at
https://example.org, add the following authorized redirect URI:https://example.org/api/2/sessions/callback -
After creating a new OAuth client in the Google Cloud console, set the following Aleph configuration options:
Configuration option Value ALEPH_OAUTHtrueALEPH_OAUTH_KEYClient ID ALEPH_OAUTH_SECRETClient secret ALEPH_OAUTH_METADATA_URLhttps://accounts.google.com/.well-known/openid-configuration
Keycloak
-
In Keycloak, create a new OpenID Connect client. Please refer to the Keycloak documentation for detailed instructions.
-
In Keycloak, add Aleph’s OAuth endpoint as a redirect URI. For example, if your Aleph instance is available at
https://example.org, add the following redirect URI:https://example.org/api/2/sessions/callback -
You also need the OpenID configuration endpoint of your Keycloak instance. For example, if your Keycloak instance is hosted at
https://keycloak.example.organd you use a realm nameddefaultthe OpenID configuration endpoint would be:https://keycloak.example.org/auth/realms/general/.well-known/openid-configurationYou can also find the OpenID configuration endpoint in the realm settings in the Keycloak admin interface.
-
After creating a new client in Keycloak, set the following Aleph configuration options:
Configuration option Value ALEPH_OAUTHtrueALEPH_OAUTH_KEYClient ID ALEPH_OAUTH_SECRETClient secret ALEPH_OAUTH_METADATA_URLOpenID configuration endpoint (see previous step)
Microsoft Entra ID (formerly Azure Active Directory)
-
Register a new application in the Microsoft Entra admin center. Please refer to the Microsoft Entra ID documentation for detailed instructions.
-
If you want to allow only users in your organization to access your Aleph instance, make sure to select the correct account type.
-
In the Microsoft Entra admin center, add Aleph’s OAuth endpoint as a redirect URI. For example, if your Aleph instance is available at
https://example.org, add the following redirect URI:https://example.org/api/2/sessions/callback -
You also need the OpenID configuration endpoint of the app you created in the first step. Please refer to the Microsoft Entra ID documentation for instructions on how to find your OpenID configuration endpoint.
-
After creating a new client in Keycloak, set the following Aleph configuration options:
Configuration option Value ALEPH_OAUTHtrueALEPH_OAUTH_KEYClient ID ALEPH_OAUTH_SECRETClient secret ALEPH_OAUTH_METADATA_URLOpenID configuration endpoint (see previous step)