OpenID Connect (OIDC)

  • Updated on Nov 19, 2024
  • Published on Nov 5, 2024
  • 5 minute(s) read

Configuring Hyperscience for OpenID Connect

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:

  • 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/v1/authorize

URL of the authorization endpoint of your OIDC provider.

Mandatory

HS_OIDC_OP_TOKEN_ENDPOINT=https:///oauth2/v1/token

URL of the token endpoint of your OIDC provider.

Mandatory

HS_OIDC_OP_USER_ENDPOINT=https:///oauth2/v1/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/v1/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_RENEW_ID_TOKEN_WITH_REFRESH_TOKEN=true 

[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_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.

HS_OIDC_LOCAL_GROUP_MANAGEMENT_ENABLE=true

 

Enables local group management. If not set to true, Hyperscience won't consume OIDC groups, even if you send them.

 

Optional.

OIDC_VERIFY_KID=true

[Available in v40 and later] Determines whether the OIDC client verifies the kid (key ID) claim for JWT tokens.

Boolean

Optional, default value: true

OIDC_VERIFY_SSL=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 of the following:

  • A boolean value (default value: true)

  • A path to a certificate bundle

Optional, default value: true

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

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 ).

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.