Federated Login#

Skalio ID supports authentication through registered external identity providers, based on OpenID Connect.

The following flows are supported:

In all cases, the authenticity and the identity of the person is established by the external identity provider. An external ID token is issued. Skalio ID validates the external ID token, locates the matching person and issues a Skalio ID token in return. The token includes a http://skalio.com/oidc_provider claim, identifying the external identity provider.

From this point on, authentication is completed successfully, and the person can use Skalio ID and its related services normally. Notice some restrictions apply for externally managed persons.

Implicit signup vs login#

Persons authenticating via a registered external identity provider for the first time are auto-provisioned to Skalio ID automatically. The accounts are marked as federated. Where possible, the name, locale and timezone of the person are imported during initial setup. After signup, the person must verify the email address.

On subsequent authentication attempts, the existing person is recognised. The personal information is not updated with details from the ID token; instead the person can manage their local profile.

If the external ID token holds a supported reference to an existing organization, the person is invited to join it. See federated organization management for details.

Email address verification#

The external identify provider provides the email address of the person in its ID token. To avoid conflicts with existing accounts, a person must demonstrate control over the email address once. This email verification process involves entering a short-lived random code that is sent to the requested email address. Email address verification is required whenever the address changes.

Note: Federated persons can have only a single email address. If the ID token provides a different email address during login, the existing address is removed, and verification is triggered for the new address.

Failure to verify an email address within ten days leads to removal of the account.

Request flows#

Authorization code flow#

The implementation follows the specification. In this flow, the client interacts with the external identity provider to authenticate himself and give consent to use Skalio ID. The identity provider returns a short-lived one-time key, the authorization code. The client forwards this authorization code to Skalio ID. From there, in a request towards the external identity provider, the authorization code is exchanged for an external ID token.

Skalio ID validates the external ID token and finds the matching person. If none is found, one is automatically auto-provisioned. The Skalio ID token is issued for the person and returned to the client.

Image

Implementation notes:

  • Use the code_verifier field where no clientSecret exists.

Implicit flow#

The implementation follows the specification. The client interacts with the external identity provider to authenticate himself and give consent to use Skalio ID. The identity provider returns the external ID token directly to the client. The client exchanges the external ID token at Skalio ID for a Skalio ID token.

Image

Formpost flow#

The implementation extends the specification with preflight- and pickup-requests:

  1. The client registers the intent to use the form-post flow with the Skalio ID backend. It sends the requested redirectUrl, where it expects notification of the completed authentication. The backend calculates a random state and returns it together with a short-lived pickup token, required at the end of the flow.
    • The registration of state as well as the associated pickup token expire after 5 minutes.
  2. The client interacts with the external identity provider, requesting response_mode=form_post. The request includes the previously registered state and a redirect_uri pointing to Skalio ID.
  3. The person interacts with the identity provider to authenticate himself and give consent to use Skalio ID.

  4. The identity provider posts the external ID token to the redirect_uri at Skalio ID. Skalio ID associates the person with the state and redirects to the client.

    • Form-post flow requests without previous registration of the state are rejected.
    • The redirection response contains the URL registered during the preflight request.

  5. The client fetches the Skalio ID token by providing the pickup-token.

Image

Service restrictions#

Persons managed by external identity providers are limited in some of the Skalio ID functionality:

  1. Password reset is disabled.
  2. Authenticators, such as password or 2FA, cannot be changed or added.
  3. The email address cannot be changed via the API.

Migration from local to federated account#

A common scenario is that a person signs up as a local user and later switches to Microsoft Entra ID. If the email address is the same in both cases, the local account can be migrated into a federated account. However, to reduce the chance for account theft, the email address must be verified again to complete the migration.

This table explains support for various scenarios:

Scenario Email address Flow After verification
OIDC signup Is not yet used Create person, add unverified email address, trigger verification notification. If organization exists, create invitation for email, using data from external ID token. Mark email as verified.
OIDC signup Exists, is verified, belongs to local account Create (temporary) person, add unverified email address, trigger verification notification. If organization exists, create invitation for email, using data from external ID token. Take over local account: Find local account, remove password, set extUid / extIdentityProvider, remove membership. Mark as primary, remove all other addresses. Silently remove temporary OIDC account.
OIDC signup Exists, is not verified, belongs to local account (possibly multiple accounts) Create person, add unverified email address, trigger verification notification. If organization exists, create invitation for email, using data from external ID token. Mark as verified. Remove unverified email from local account(s). May trigger removal of local account(s).
OIDC signup Exists, belongs to an OIDC account Reject request. Admin must remove OIDC account in skp-admin.
Add email to OIDC account Reject request. OIDC accounts cannot add email address manually.
OIDC login, roles have changed unchanged Update roles in membership. n/a
OIDC login, email has changed Is not yet used Remove existing address. Add unverified new email address, mark as primary. Trigger verification notification. Mark email as verified.
OIDC login, email has changed Exists, is not verified, belongs to local account (possibly multiple accounts) Remove existing address. Add unverified new email address, mark as primary. Trigger verification notification. Mark as verified. Remove unverified email from local account(s). May trigger removal of local account(s).
OIDC login, email has changed Exists, is verified, belongs to local or OIDC account Reject request. Local account must be deleted manually. (Reason: cannot merge two accounts with data)