OpenID Connect (OIDC)

  • Updated on Nov 5, 2024
  • Published on Nov 5, 2024
  • 3 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.

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

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.