OpenID Connect settings

Starting from Omniscope 2021.1 you can use OpenID Connect to authenticate users with different providers. 

This guide discusses the different OpenID Connect options provided by Omniscope. These are available from the permission dialog in the per-provider settings. You will need to add a given provider in the OpenID Connect section to see these settings. For more information regarding folder permission see here.

Depending on the provider you may see different options here. Each option in the dialog has a little "i" next to it which provides a description.

When setting up OpenID Connect it is important to note that providers require you to enter an actual domain name rather than IP address for callback URLs. If this is not configured, then Omniscope would not be able to authenticate the user with a given provider.

This restriction is not an Omniscope restriction, but actually of OpenID Connect protocol implemented by different providers.

In Omniscope this domain name is referred to as the External URL domain. This is used for both OpenID Connect settings, and to creating URLs for Report sharing. You can configure this from Admin Section > (Web server) > Network section.

NOTE: This URL domain should be full domain including protocol and port. 

For example: https://[yourdomain]:[port]/ -> https://acme.com:8080

Warning: Many OpenID Connect providers require the protocol for callback URL to be HTTPS and not HTTP. You can configure this in the same section where you configure the external URL domain.

Settings 

If you want guidance / tips on what to choose for Login/Logout/Refresh mode see here.

• Client ID
  This is retrieved from the actual provider configuration portal. 

• Client secret
  This is also retrieved from the provider configuration portal

• Login mode
  
  This controls how the user is logged into Omniscope. It depends on the per-organisation basis to control the login behaviour:

• Explicit login with forced re-authentication
  
  No SSO (single-sign-on). Users must explicitly choose to log into Omniscope, and every time they do, they will be required to re-authenticate at the provider (subject to provider support). Typically used in high security environments, in conjunction with Logout mode 'Provider'.
  
  
• Explicit login
  
  No SSO. Users must explicitly choose to log into Omniscope. When they choose to do so, they may need to sign-in again at the provider, or may be signed in automatically if they already have a sign-in session at the provider, subject to provider support.
  
  
• Implicit login for previous users
  
  Partial SSO. New users must explicitly choose to sign into Omniscope. Previous users who have not signed out will automatically be signed in again, until the provider requires them to re-authenticate, typically periodically. Typically used in cloud/public facing deployments, in conjunction with Logout mode 'Local'.
  
  
• Implicit login, always
  
  Full SSO. An attempt will be made to silently and automatically sign in all visitors. If the visitor already has a sign-in session at the provider, and the provider supports this, the user will be signed in automatically to Omniscope, near-invisibly, subject to provider support. If not, the user will be redirected to the provider to sign in, which for most providers will typically last for several days. This option can only be enabled for a single configured provider. Typically used in internal/intranet enterprise deployments with a single identity provider, in conjunction with Logout mode 'None'.

• Logout mode
  
  This controls the logout behaviour when the user clicks on Logout button from the Profile icon you see in Omniscope.
  
  NOTE: Not all providers support all the logout behaviour so you may not see some of the options listed below.

• None
  
  No logout option will be presented in Omniscope. Users will remain logged in for as long as the provider allows. Some providers may require periodic re-authentication, however. Typically used in conjunction with Login mode 'Implicit login, always'.
• Local
  
  A logout option will be presented, which will sign out of the local Omniscope session. The sign-on session at the provider will not be affected, and depending on the login mode and provider support, may allow the user to sign into Omniscope again without needing to re-authenticate. Typically used in conjunction with Login mode 'Implicit login for previous users'.
• Provider
  
  A logout option will be presented, which will sign out of both the local Omniscope session and the provider. Next time sign-in is attempted, the user will be required to sign in again at the provider. Typically used in conjunction with Login mode 'Explicit login with forced re-authentication'. This type of logout option is supported by Microsoft, OKTA and Keycloak other providers may not support it.
  
  

• Expiry
  
  The duration in seconds that Omniscope should trust a login session for before consulting the provider again. It will be impossible to stop a blocked or deleted user from using Omniscope during this period, unless the Omniscope server is restarted. Depending on provider support and Refresh mode setting, Omniscope will attempt to automatically renew the local authentication session without disrupting the user's experience. For some providers, or periodically, the user may be required to go through an interactive re-authentication process at the provider to extend the session. The default (36000) is for 10 hours.
  
  
• Refresh mode
  
  This controls how refresh of the user's session is performed. 

• None
  
  When the expiry time passes, the user will be logged out, and will need to explicitly log in again to continue. For use in high security situations where, for example, you require an explicit daily login.
  
  
• Prompt
  
  Shortly before the expiry time passes, the user will be asked if they want to extend their session. For use in cases where you want sessions to be extended only if the user is still present.
  
  
• Keep
  
  Shortly before the expiry time passes, an attempt will be made to automatically extend the login session. For use in cases where you want silent session extension without disrupting the user, including where no user is present such as an always-on dashboard.

• Custom scopes
  
  This is an advanced setting. It allows you to use custom scopes defined on the provider to further authenticate the user. You must define the list of scopes here and then use them appropriately "Restrict by claims" section in the per-group OpenID Connect mechanism.
  
  NOTE : 'OpenID', 'Profile' and 'Email' are already included by default. Should be space separated.

Per-group OpenID Connect mechanism

On a per-group basis you can further customise how the OpenID Connect provider is used to authenticate the user. 

Currently two ways are supported on per-group basis:

Restrict by email

This means that user's email address (used to login with) MUST match one of the emails listed here.

Restrict by claims

This allows you to further authenticate the user based on their claims (which are retrieved from the provider itself). You MUST ensure that the claim's scopes are registered in the provider configuration as mentioned above).

The validation of claims can be performed in two ways:

• By value
  Use this for claims which are simple key value pairs such as roles.
  
• By property value
  Use this for complex claims i.e. objects.
  
  The property path is expected path to the property that would be used to validate the value. This path is dot separated path to the property. For example: a.b.c will look for property named c within b object which is contained within object a and then try to validate if the value field matches.
  
  

Further documentation

For information on how to configure individual providers see relevant articles here. If you need any further help please get in touch with us.

here