OpenID Connect (OIDC)

  • Updated on Jan 23, 2025
  • Published on Nov 5, 2024
  • 8 minute(s) read

The steps required to set up OpenID Connect (OIDC) depend on what kind of Hyperscience instance you are using.

On-premise / private cloud instances

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:

Option

Configuration

Application type

Web

Allowed grant types

Authorization Code

Login redirect URIs

/oidc/callback/

Logout redirect URIs

(Leave empty)

Login initiated by

App Only

Permissions to request OpenID scopes

By default, Hyperscience requests the openid, email, profile, and groups scopes.

Claims required by Hyperscience

  • By default, Hyperscience uses the email claim to create an account in Hyperscience; see the HS_OIDC_USERNAME_CLAIM property.

  • Hyperscience uses the groups claim to assign permissions to users; see the HS_OIDC_RP_SCOPES property.

Creating this configuration generates 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.

The code block below lists the available configuration properties for setting up OpenID authentication in Hyperscience. You can enter these properties as variables in your application’s “.env” file. 

###############################################################################
# AUTHENTICATION - OpenID Connect
###############################################################################

### Required: 

# Enables OpenID authentication. Should be set to true to enable OpenID authentication for Hyperscience application.
HS_LOGIN_ENABLE_OPENID=True

# Set the client_id and client_secret from your OIDC identity provider
HS_OIDC_RP_CLIENT_ID=<ODIC app config client id>
HS_OIDC_RP_CLIENT_SECRET=<OIDC app config client secret>

# URL of the authorization endpoint of your OIDC provider.
HS_OIDC_OP_AUTHORIZATION_ENDPOINT=https://<OIDC provider>/oauth2/v1/authorize

# URL of the token endpoint of your OIDC provider.
HS_OIDC_OP_TOKEN_ENDPOINT=https://<OIDC provider>/oauth2/v1/token

# URL of the userinfo endpoint of your OIDC provider.
HS_OIDC_OP_USER_ENDPOINT=https://<OIDC provider>/oauth2/v1/userinfo

# Sets the algorithm used by your OIDC provider to sign ID tokens. Possible values are RS256 and HS256. 
# Default value: RS256
HS_OIDC_RP_SIGN_ALGO=RS256

# URL of the JWKS endpoint of your OIDC provider.
# Reqired when HS_OIDC_RP_SIGN_ALGO=RS256.
HS_OIDC_OP_JWKS_ENDPOINT=https://<OIDC provider>/oauth2/v1/keys

# Defines after how many seconds the ID token should be renewed.
# Default value: 5400
HS_OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS=5400

# [Available in 38.0.3+] Controls the mechanism used to refresh the OIDC ID token. 
# - When true, Hyperscience uses the refresh token to issue a new ID token automatically. 
# - When false, the user is redirected to the OIDC provider's authorization endpoint. 
# Default value: false
HS_OIDC_RENEW_ID_TOKEN_WITH_REFRESH_TOKEN=false

# Display name of your OIDC provider. This value will appear in the HyperSience login page as  a “Log In With <OIDC provider Name>” button.
HS_OIDC_UI_PROVIDER_NAME=<OIDC provider name>

# 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 <OIDC provide name>“ button.
HS_OIDC_UI_PROVIDER_LOGO_URL=https://<OIDC provider>/favicon.ico

# The 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.
HS_OIDC_ADMIN_GROUP=<OIDC identifier of a Hyperscience system administrators group>

# 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.
# Note that for different OpenID providers scopes could have different names. For example, in Azure AD, OpenID "groups" scope is named "GroupMember.Read.All"
# Default value: openid email groups profile
HS_OIDC_RP_SCOPES=openid email groups profile

# Defines the claim (attribute of the user) used by Hyperscience to create an account in its database. 
# Default value: email
HS_OIDC_USERNAME_CLAIM=email

### Optional:

# Enables local group management. If set to true, Hyperscience won't consume OIDC groups, even if you send them. This should be used in the rare cases where you want to use OIDC
# for authentication, but handle the authorisation manually with list of admin users and default permission group for everyone else.
# Default value: false
HS_OIDC_LOCAL_GROUP_MANAGEMENT_ENABLE=false

# Local group management only. Space-delimeted list of usernames that will be assigned to admin user accounts.
# The type of username depends on HS_OIDC_USERNAME_CLAIM (default: email).
[email protected] [email protected]

# Local group management only. Sets authentication and permission group names in case of local group management.
# Default value for permission group: data_clerk_staff
HS_OIDC_DEFAULT_USER_AUTHENTICATION_GROUP=default_local_user_group
HS_OIDC_DEFAULT_USER_PERMISSION_GROUP=data_clerk_staff

# Defines the log level of Hyperscience openid logger. 
# NOTE: Level DEBUG should be used only for debugging purposes, because at this level messages may contain personal identifiable information. 
# Default value: INFO.
HS_OIDC_LOGGER_LEVEL=INFO

# [Available in v40 and later] Determines whether the OIDC client verifies the kid (key ID) claim for JWT tokens.
# Default value: true
OIDC_VERIFY_KID=true
 
# [Available in v40 and later] Does one of the following:
# - (Default) Determines whether the OIDC client verifies the SSL certificate of the OIDC provider (OP) responses.
# - Specifies the path of the SSL certificate bundle.
# Can be either a boolean value (defaults to true) or a path to a certificate bundle
# Default value: true
OIDC_VERIFY_SSL=true

Any user who exists in the OIDC admin group will be able to log in and be granted admin privileges.

Once the application has started with the new settings, you can log in to it with an account belonging to the HS_OIDC_ADMIN_GROUP group and map additional groups in the UI.

To learn how to map authentication groups from your identity provider to Hyperscience permission groups, see the "Managing Authentication Groups" article for your version of Hyperscience ( v35 | v36 | v37 | v38 | v39 | v40 ).

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 On-premise / private cloud instances 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 On-premise / private cloud instances section above also apply to Google OIDC, your Google OIDC implementation will require the following variables and variable values.

###############################################################################
# AUTHENTICATION - Google OIDC specific
###############################################################################

## 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>

SaaS instances

The steps required to integrate your OIDC IdP with Hyperscience depend on the version of Hyperscience you’re running.

New deployments of v38 and later

If you want to integrate your OIDC IdP with Hyperscience, you can set up and manage that integration in the Hyperscience application.

This feature is only available for new deployments of v38 and later. If you’ve upgraded to v38 and currently have OIDC authentication set up in your instance, your integration will still be managed by Hyperscience. See v37 and earlier / Upgrades to v38 for more information.

Prerequisites

Before starting the setup process described below, ensure that you have:

  • Communicated to your Hyperscience representative that you want to manage your OIDC setup in your application.

  • Added at least one user record to your SAML or OIDC authentication provider.

Integrating your IdP with Hyperscience

  1. In your IdP, create an application. Hyperscience will use this application to connect to your IdP.

  2. In your IdP, create at least one user group for Hyperscience administrators and assign a user to it. You need this group name for the next steps.

  3. In the Hyperscience application, go to the System Settings page (Administration > System Settings), and in the View drop-down menu at the top of the page, click on Security & Identity.

  4. In the Identity Provider card, click Edit.

  5. Select the Enabled checkbox.

  6. In the Identity Provider Name field, enter a name for the IdP. This name will appear on the Log In button on the login page (Log In With <Identity Provider Name>, e.g., Log In With Azure AD).

  7. In the Identity Provider Organization field, enter a name for the main point of contact for the IdP at your organization.

  8. Click on OIDC.

  9. Enter the requested information in the top seven fields. The information is required in order to complete the integration.

  10. In the bottom five fields (Token Signing Algorithms up to and including Delimiter to Use When Groups Claim Is String Rather Than Array), enter the requested field mappings from your IdP to Hyperscience.

  11. Click Show Hyperscience configuration for selected identity provider.

  12. Copy the information from the Information to use with your identity provider window that appears, and paste it into the respective fields in your IdP.

  13. Click Save at the top of the Identity Provider card.

  14. Create additional groups in your IdP for non-admin users, and map them to their Hyperscience roles by following the instructions in “Managing Authentication Groups” for your version of Hyperscience ( v35 | v36 | v37 | v38 | v39 | v40 ).

v37 and earlier / Upgrades to v38

You can integrate your OpenID Connect authentication provider with Hyperscience by providing the following information to your Hyperscience representative:

  • The OIDC group name for users accessing the Hyperscience instance

  • The OIDC group name for users who should be in the System Admin permission group in Hyperscience

  • Client ID

  • Client Secret

  • The following endpoints:

    • Issuer

    • Authorization

    • Token

    • JWKS

    • Userinfo

After we receive this information, we will set up the integration with your IdP and Hyperscience.