SSO (Single Sign-On)

Background

SSO (Single Sign-On) aims to replace the interactive entry of credentials (user name and password) when logging in to Lobster Data Platform with a reference to an existing login with an 'external identity provider'. If necessary, a corresponding login with this provider is initiated in a separate browser window.

To register for a session on a suitably configured Lobster Data Platform the user can click on a button displayed in the login dialog for the 'external identity provider' of their choice (in the image on the right, 'Microsoft' or a fictitious provider 'B²B') instead of entering any information.

If the identity 'offered' is linked to an active user account, this account will then be used for login.

What happens when you click on ( Microsoft )?

Check: Azure login exists in context?
1. If NO: Start Azure identification
  (See below: Authorization URL).
2. Returning the Azure user term
  (e.g. registered e-mail address).
Check: Does a user account exist for Lobster Data Platform, das sich that refers to the Azure user term determined above in the 'User term' (userterm) field for an 'External user login information' (ExternalUserLoginInfo) attribute with the matching entry for the 'Provider Alias' (providerAlias) — here: azure — refers to the Azure user term determined above?
1. If NO: Error message / Login canceled.
2. If YES: Log in with the user account (if active).

IMPORTANT If multiple user accounts exist for the Lobster Data Platform with the 'matching' providerAlias/userterm combination, a login will only be attempted with the first match, even if this account is not active.

NOTE Users, who are assigned different Companies/Clients and/or Roles can and must make a selection from the available alternatives during the login process.

If the 'Back' button is selected in this second step of the login process, the login dialog shown above reappears. For technical reasons,the 'User term' (userterm) used in the canceled SSO login appears as a default value in the 'username' field. This absolutely does not have to match the ‘Username’ (username) of the corresponding user account for the Lobster Data Platform. However, only then does it make sense to perform a conventional login after the termination based on the default setting with the password for this account, if known.

Example:

For a user (let call him Jack) identified via Microsoft Azure using their business e-mail address (jack.tonic@doma.in), a user account with the 'Username' jtonic is set up on Lobster Data Platform, for which a reference to the 'Azure user term' (jack.tonic@doma.in) is noted under 'External user login infos'. An SSO login with Jack’s azure-’User term’ (userterm) jack.tonic@doma.in therefore refers to the user account with ‘username’ (username) jtonic.
The list property 'Roles' (roles) in Jack’s Lobster Data Platform user account grants access to two different Roles to choose from. During each SSO login, Jack will be prompted to select the Role of session.
- However, he can also reject this selection by clicking the 'Back' button. In this case, the entire login process is considered canceled.
- The login dialog then appears with jack.tonic@doma.in pre-filled as the user name, even though the ‘Username’ (username) for the user account associated in the canceled login process would have been jtonic.
- Even if Jack knows the password for the user account assigned to him (jtonic), logging in as jack.tonic@doma.in with this password is pointless.

A successful SSO login requires the following:

In the execution context of the login, a registration with the desired external identity provider must be established or created.
A valid reference to the provider account must be stored in an active user account for Lobster Data Platform (see Users, 'External user credentials').
Appropriate 'SSO System Preferences' for communication with the 'SSO Provider' must be set up, activated, and, if necessary, supported for the specific login context (see Site configurations).

The following documentation relates exclusively to the last item on this list.

Access to 'SSO System Preferences'

The view Authentication (see Base settings) provides a separate tab with settings for SSO (Single Sign-On).

The SSO (Single Sign-On) tab contains an overview listing all 'SSO System Preferences' (SSOSystemPreferences) that can be read in the context of the current session.

If ownership restrictions must be taken into account for Role of session (see Roles), only 'SSO System Preferences' (SSOSystemPreferences) that are owned by Company of session or for which Company authorizations apply.

Additional permissions for listed 'SSO System Preferences' (SSOSystemPreferences) — e.g., 'Change', 'Create', 'Delete', etc. — must be granted to the Role of session and be applicable to the respective instance based on ownership and, if applicable, Company authorizations in order for the associated ribbon buttons to be visible or appear active depending on the selection in the list.

With sufficient permissions for a list entry identified by single selection or double-click, the associated configuration details can be accessed in a separate view. This is an input form (see Input forms), which is also referred to below as the detail view.

Configuration

The system-defined detail view for 'SSO System Preferences' is required, among other things, to create a new 'SSO System Preferences' instance using the New ribbon button (in the overview or detail view).

Initially, the type for the SSO Provider (ssoType) must be specified using a Combobox so that any other specific Form elements appear.

WARNING
If the selection for the SSO Provider is changed after you have already started entering details in the Form elements that appear, data already entered for the deselected provider will be lost even if the configuration for the selected provider supports the same properties.

Background to the data model
Technically, the selection for the SSO Provider assigns a data object with a specific class ({Google|Azure|Auth0|Facebook|Amazon|Frontegg|Custom}SSOConfiguration) to the preferencesfield of the 'SSO System Preferences' class (SSOSystemPreferences). The parent class 'SSO (Single Sign-On)' (BaseSSOConfiguration) provides the common properties. The specific classes may contain additional properties.

In fact, all SSO Providers offer largely the same features, as can be seen in the following table. The few specific features are shaded gray in the table.

Subject	Name	Data field	Data type	Description
General properties	Alias	`alias`	`String`	Unique system-wide identifier that is displayed directly to the user upon login, provided that no localization (see Localization) is defined.
	(Status) NOTE In the input form, the corresponding Check box displays its value ('active', 'not active') instead of a label.	`active`	`Boolean`	Flag that must be set (`true`) so that the relevant 'SSO System Preferences' instance can be offered during login. NOTE Whether active 'SSO System Preferences' appear in the login dialog may also depend on settings in the applicable Site configurations A whitelist (per Multiselect combobox 'External identity providers') can be defined there as a filter.
	Client ID	`clientId`	`String`	Public identifier for the application issued by the identity provider (e.g., Google, Amazon).
	Client Secret	`clientSecret`	`String`	Private key used to authenticate your application with the identity provider. IMPORTANT Keep this confidential!
	Authorization URL	`authorizationUrl`	`String`	URL where users are redirected to log in using the identity provider.
	Callback URL	`callbackUrl`	`String`	URL where the identity provider should redirect users after a successful login NOTE The text value is automatically assigned for the current system based on the Alias. The associated Text field is therefore read-only. The Button provided to the right of it transfers the calculated value to the client's clipboard so that it can be reused from there.
	Comment	`comment`	`String`	Free text for comments on the configuration.
└► only Azure SSO	Tenant	`tenant`	`String`	Specific tenant or organization ID within the identity provider (used in multi-tenant setups like Azure AD).
└► only Auth0 SSO and Frontegg SSO	Domain	`domain`	`String`	Expected domain of the user's email or organization (used to route or restrict login access).
Advanced settings	Token URL	`tokenUrl`	`String`	Endpoint used to exchange the authorization code for an access token.
	User Info URL	`userInfoUrl`	`String`	Endpoint to retrieve user profile information (such as e-mail and name) after login.
	Scope	`scope`	`String`	Keywords for the permissions the application is requesting (e.g. `openid` `email` `profile`).
	State Field	`stateField`	`String`	Parameter used to maintain state between the request and callback; helps prevent CSRF attacks.
	Field Mappings	`fieldMappings`	`String`	Mappings for identity provider fields (like e-mail or name) to the application's user attributes.
	Additional Authorization Parameters	`additionalParameters`	`String`	Optional query parameters to include in the authorization request (e.g. `prompt=consent`).
	Icon	`iconUri`	`String`	Reference for the icon to be displayed together with the Alias (or the assigned localization) in the login dialog (see also Working with image resources (Icons)) NOTE If no Icon is explicitly assigned, a 'key' appears by default:
Localization (Alias)	One Text field for each supported Locale	n/a	`String`	Localization value for the Alias (see above) in the respective Locale. (Bundle `ExternalIdentityProvider` Resource `{alias}.login`) NOTE Localizations appear in place of the Alias in the login dialog and, if applicable, in the Multiselect combobox element for 'External identity providers' for Site configurations. NOTE For historical reasons, the `ExternalIdentityProvider` Bundle may contain Resource entries with the schema `{alias}.icon`. Current versions of Lobster Data Platform refer exclusively to the Icon property (`iconUri`), to assign an Icon to an 'SSO System Preferences' instance.

IMPORTANT Placeholder texts describe default values
For many of the shared properties, the empty Text field displays a placeholder that can be specific to each SSO Provider (ssoType). (ssoType).
Example: For the SSO Provider (ssoType) 'Azure SSO', the placeholder for the Authorization URL property (authorizationUrl) is:
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
The placeholder describes the default value that applies to the property at runtime as long as no input is available for the property.
The text values predefined by the system as default values are only visible in the user interface in empty text fields once a selection has been made for the SSO Provider (ssoType).
The system provides typical default values for all specific SSO Providers. For the 'Custom SSO' option, default values are of course only applicable to a limited extent.
The text displayed as a placeholder can (as in the example above) contain a reference to a data field of a specific property ({tenant}, {domain}) In this case, the text assigned to the relevant property (tenant, domain) is used instead at runtime. However, this only applies to default values. It is not intended to use such references in user-defined text values for properties of an SSO configuration.
The hard-coded default values are explicitly not persisted in the database when saving an 'SSO System Preferences' instance. Instead, the relevant fields remain empty.
The associated data object also does not return the effective default value when reading an undefined property.

Specific menu functions

Once the 'SSO (Single Sign-On)' tab is selected in the 'Authentication' view, the contextually applicable ribbon buttons appear.

In addition to the generic functions, which appear and are activated as usual depending on permissions for the relevant 'SSO System Preferences' instance, two specific ribbon buttons are also available:

Ribbon button	Context	Functional description
Test SSO `testSSO`	Overview and data input form	Runs a test for the selected/displayed 'SSO System Preferences' instance and displays a success or error notification depending on the outcome. For the test, a separate browser window is temporarily opened, in which an error message with details may appear. The selection for the 'Status' property (`active`) is ignored for the test. Inactive configurations can also be tested. In the context of an input form, the test takes into account any volatile processing status for the displayed 'SSO System Preferences' instance. The form is validated before the actual test is performed. Validation errors (e.g., empty required fields) are indicated by an error message. No test is performed with invalid data.
De/Activate `deActivate`	Overview	Inverts the Boolean value for the 'Status' (`active`) property for selected 'SSO System Preferences' instances: Active 'SSO System Preferences' instances are deactivated. Inactive 'SSO System Preferences' instances are activated. A change in status implies saving the selected instances, so that the 'Change' event (see Common action event) is triggered for them. IMPORTANT A status change can only be performed if the 'Change' permission for the selected 'SSO System Preferences' instance is available. Otherwise, an error message will appear when the ribbon button is clicked. NOTE The 'Activate/Deactivate' ribbon button is not available in the context of an input form. There, the 'Status' (active) can be adjusted directly via the corresponding Check box element. However, a change in status does not imply that the instance is saved.

Ribbon button

Context

Functional description

Test SSO

testSSO

Overview

and

data input form

Runs a test for the selected/displayed 'SSO System Preferences' instance and displays a success or error notification depending on the outcome. For the test, a separate browser window is temporarily opened, in which an error message with details may appear.

The selection for the 'Status' property (active) is ignored for the test. Inactive configurations can also be tested.
In the context of an input form, the test takes into account any volatile processing status for the displayed 'SSO System Preferences' instance. The form is validated before the actual test is performed. Validation errors (e.g., empty required fields) are indicated by an error message. No test is performed with invalid data.

De/Activate

deActivate

Overview

Inverts the Boolean value for the 'Status' (active) property for selected 'SSO System Preferences' instances:

Active 'SSO System Preferences' instances are deactivated.
Inactive 'SSO System Preferences' instances are activated.

A change in status implies saving the selected instances, so that the 'Change' event (see Common action event) is triggered for them.

IMPORTANT A status change can only be performed if the 'Change' permission for the selected 'SSO System Preferences' instance is available. Otherwise, an error message will appear when the ribbon button is clicked.

NOTE The 'Activate/Deactivate' ribbon button is not available in the context of an input form. There, the 'Status' (active) can be adjusted directly via the corresponding Check box element. However, a change in status does not imply that the instance is saved.