External Authentication Providers

  • Updated on Dec 11, 2024
  • Published on Sep 23, 2024
  • 5 minute(s) read

Overview

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://<domain controller>

  • FORMS_LDAP_AUTH_ACTIVE_DIRECTORY_DOMAIN=<domain>

  • FORMS_LDAP_AUTH_SEARCH_BASE=<search base>

  • FORMS_LDAP_ADMIN_GROUP=<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: <hyperscience url>/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=<ODIC app config client id>

HS_OIDC_RP_CLIENT_SECRET<OIDC app config 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://<OIDC provider>/oauth2/v3/authorize


URL of the authorization endpoint of your OIDC provider.

Mandatory

HS_OIDC_OP_TOKEN_ENDPOINT=https://<OIDC provider>/oauth2/v3/token


URL of the token endpoint of your OIDC provider.

Mandatory

HS_OIDC_OP_USER_ENDPOINT=https://<OIDC provider>/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://<OIDC provider>/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=<OIDC 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://<OIDC provider>/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=<OIDC identifier of a Hyperscience system administrators 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:

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.

HS_OIDC_ADMIN_USERNAMES=<[email protected] [email protected]>

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.

HS_OIDC_DEFAULT_USER_AUTHENTICATION_GROUP=<oidc_companyX_user>
HS_OIDC_DEFAULT_USER_PERMISSION_GROUP=<name_of_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 and Directory API 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 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.

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.

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:

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:

HS_OIDC_GOOGLE_SERVICE_ACCOUNT_USER_EMAIL=<[email protected]>

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:

HS_OIDC_GOOGLE_SERVICE_ACCOUNT_JSON_FILE_NAME=<name_of_file.json>

SAML configuration

We added support for SAML authentication in v28. To learn more about enabling SAML for your Hyperscience application, see SAML.