# External Authentication Providers - Published on May 6, 2026 - 5 minute(s) read Hyperscience supports three mechanisms for external authentication: - LDAP - OpenID Connect (OIDC) - SAML This configuration is managed through the ENV file in the supplied bundle. ## LDAP configuration Here’s an example LDAP configuration: - FORMS_LOGIN_ENABLE_LDAP=True - FORMS_LDAP_AUTH_URL=ldap:// - FORMS_LDAP_AUTH_ACTIVE_DIRECTORY_DOMAIN= - FORMS_LDAP_AUTH_SEARCH_BASE= - FORMS_LDAP_ADMIN_GROUP= The bind to the LDAP server will be done using ‘@’ where is taken from what is typed into the username box during login. Any user who exists under the and is in the will be able to log in and is granted admin privileges. Use the full LDAP Group DN in (e.g., CN=HS_ADMIN,OU=HSCORP,DC=corp,DC=hyperscience,DC=com). An admin can configure additional LDAP groups and related permissions through the UI. ## OIDC configuration Our support of OIDC allows us to integrate with identity-management systems like Okta, Microsoft Identity platform (e.g., Azure AD), Google Identity Platform, and more. To use OIDC, you'll first want to create an application configuration for Hyperscience in your OIDC identity provider. Follow their documentation for creating an application configuration using the following settings: - Application type: web - Allowed grant types: Authorization code - Login redirect URIs: /oidc/callback/ - Logout redirect URIs: leave it empty - Login initiated by: App Only - Permissions to request OpenID scope: by default Hyperscience requests openid, email, profile and groups scopes. - Claims required by Hyperscience: - by default Hyperscience uses **email** claim to create an account in Hyperscience; See HS_OIDC_USERNAME_CLAIM property - Hyperscience uses **groups** claim to assign permissions to users; See HS_OIDC_RP_SCOPES property This will generate a client_id and a client_secret for communication between Hyperscience and your OIDC identity provider. You'll use these credentials in your OIDC configuration within Hyperscience. Configuration properties for setting up OpenID authentication in Hyperscience. | OpenID authentication configuration properties | | HS_LOGIN_ENABLE_OPENID=True
Should be set to True to enable OpenID authentication for Hyperscience application. | | HS_OIDC_RP_CLIENT_ID=
HS_OIDC_RP_CLIENT_SECRET
You need to create an application configuration in your OIDC provider. As a result you will have client_id and client_secret which should be set here.
Mandatory | | HS_OIDC_OP_AUTHORIZATION_ENDPOINT=https:///oauth2/v3/authorize
URL of the authorization endpoint of your OIDC provider.
Mandatory | | HS_OIDC_OP_TOKEN_ENDPOINT=https:///oauth2/v3/token
URL of the token endpoint of your OIDC provider.
Mandatory | | HS_OIDC_OP_USER_ENDPOINT=https:///oauth2/v3/userinfo
URL of the userinfo endpoint of your OIDC provider.
Mandatory | | HS_OIDC_RP_SIGN_ALGO=RS256
Sets the algorithm used by your OIDC provider to sign ID tokens.
Possible values are RS256 and HS256
Mandatory, Default value is RS256. | | HS_OIDC_OP_JWKS_ENDPOINT=https:///oauth2/v3/keys
URL of the JWKS endpoint of your OIDC provider.
Mandatory when HS_OIDC_RP_SIGN_ALGO is set to RS256. | | HS_OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS=5400
Defines after how many seconds the ID token should be renewed.
Default value: 5400 | | HS_OIDC_UI_PROVIDER_NAME=
Display name of your OIDC provider. This value will appear in the Hyperscience login page as a “Log In With ” button.
Mandatory. | | HS_OIDC_UI_PROVIDER_LOGO_URL=https:///favicon.ico
URL of an image file representing the logo of your OIDC provider. It will appear in the Hyperscience login page as part of the “Log In With “ button.
Mandatory. | | HS_OIDC_ADMIN_GROUP=
Hyperscience application maintains a mapping between OIDC groups and Hyperscience Permission groups.
Based on these mappings and the membership in OIDC groups Hyperscience assigns permissions to users.
Hyperscience ensures that for the group identified by HS_OIDC_ADMIN_GROUP there is a mapping to “system_admin” permission group.
Mandatory. | | HS_OIDC_RP_SCOPES=openid email groups profile
OpenID Scopes that will be requested from your OIDC provider during login by Hyperscience. Scopes define what information about the users Hyperscience will have access to.
Scopes should be separated with a single space character. The order does not matter.
Mandatory, default: openid email groups profile
Note that for different OpenID providers scopes could have different names.
For example in Azure AD OpenID groups scope is named GroupMember.Read.All and in this case HS_OIDC_RP_SCOPES should look like this:
HS_OIDC_RP_SCOPES=openid email profile GroupMember.Read.All | | HS_OIDC_USERNAME_CLAIM=email
Defines the claim (attribute of the user) used by Hyperscience to create an account in its database.
Mandatory, default: email | | HS_OIDC_LOGGER_LEVEL=INFO
Defines the log level of Hyperscience openid logger. By default the level is **INFO**.
The level could be set to **DEBUG** for troubleshooting authentication problems with your OIDC provider.
NOTE: Level DEBUG should be used only for debugging purposes, because at this level messages may contain personal identifiable information. | An admin can configure additional authentication groups and related permissions through the UI. ### Local group management settings A separate set of variables allows you to enable and configure local groups. #### Enable local group management We don't consume OIDC groups, even if you send them to us. To turn on local group management, enter the following variable: Bash ```bash HS_OIDC_LOCAL_GROUP_MANAGEMENT_ENABLE=True ``` #### Assign system administrator permissions To assign _system_admin_ permissions, use the HS_OIDC_ADMIN_USERNAMES variable to enter a space-delimited list of usernames that should be assigned admin permissions in the application. These users can log in immediately and further configure the group mappings inside the system. Bash ```bash HS_OIDC_ADMIN_USERNAMES= ``` #### Manage default access for non-admin users By default, we create an authentication group for non-admin users called _default_local_user_group_ and assign it _data_clerk_staff_ permissions. Every user who successfully authenticates with OIDC and is not listed in HS_OIDC_ADMIN_USERNAMES is assigned to this group. After users are authenticated and created locally in the system, an administrator can assign them to different groups. To change these settings, specify your default authentication and permission groups using the variables below. If you are not changing our default settings, you can omit these variables. Bash ```bash HS_OIDC_DEFAULT_USER_AUTHENTICATION_GROUP= HS_OIDC_DEFAULT_USER_PERMISSION_GROUP= ``` ### Using Google groups with OIDC By default, Google does not natively support groups scope via OIDC. To retrieve a user's groups, we first authenticate the user via OIDC and then submit a request to the Google Directory API. To learn more, see Google's [OpenID Connect (opens in new tab)](https://developers.google.com/identity/protocols/oauth2/openid-connect) and [Directory API (opens in new tab)](https://developers.google.com/admin-sdk/directory/v1/reference/groups/list) documentation. Before configuring the Hyperscience application, complete the following tasks in your company's Google account: - Create a service account with domain-wide delegation by following the steps in Google's [OpenID Connect](https://developers.google.com/identity/protocols/oauth2/openid-connect) documentation. - During account creation, Google will generate a JSON file containing the needed security information. You will need to provide this file name in the HS_OIDC_GOOGLE_SERVICE_ACCOUNT_JSON_FILE_NAME variable, as described in the "Variables" section below. - When delegating API scopes to the service account, use only _https://www.googleapis.com/auth/admin.directory.group.readonly_. Using more scopes may cause issues. - To allow us to make API requests with the service account, enable Google's Admin SDK from the [Google Cloud Console (opens in new tab)](https://console.developers.google.com/apis/library/admin.googleapis.com). #### Endpoints Google has specified their own OIDC endpoints that differ from those given in the "OIDC configuration" section above. For a list of Google's endpoints, along with other information about Google OIDC, see Google's [OpenID Configuration (opens in new tab)](https://accounts.google.com/.well-known/openid-configuration). #### Variables While most of the variables described in the "OIDC configuration" section above also apply to Google OIDC, your Google OIDC implementation will require the following variables and variable values. #### Scopes Because Google does not support groups scopes, using the default value for HS_OIDC_RP_SCOPES will result in an error. Instead, use the following: Bash ```bash HS_OIDC_RP_SCOPES=openid profile email ``` #### Service account email A user's service account has domain-wide delegation authority to access user data on the user's behalf. Because the service account submits queries to the system via its administrator user, the administrator user needs permissions to request lists of groups. To grant those permissions, enter the following variable: Bash ```bash HS_OIDC_GOOGLE_SERVICE_ACCOUNT_USER_EMAIL= ``` #### Service account JSON The security information used by the service account can be found in the JSON file generated during the account's creation. This file should be placed in the _certs_ directory of each host running our frontend services. By default, _certs_ has a directory path of _/mnt/hs/certs_. To place the file in the directory, enter the following variable: Bash ```bash HS_OIDC_GOOGLE_SERVICE_ACCOUNT_JSON_FILE_NAME= ``` ## SAML configuration We added support for SAML authentication in v28. To learn more about enabling SAML for your Hyperscience application, see [SAML](https://help.hyperscience.ai/deployment/docs/saml).