External IDP

You may be running Stroom in an environment with an existing Identity Provider (IDP) Identity Provider (IDP) An Identity Provider is a system or service that can authenticate a user and assert their identity. Identity providers can support single sign on (SSO), which allows the user to sign in once to the Identity Provider so they are then authenticated to all systems using that IDP.Click to see more details... (KeyCloak, Cognito, Google, Active Directory, etc.) and want to use that for authenticating users. Stroom supports 3rd party IDPs that conform to the Open ID Connect specification.

This page describes what Stroom needs from any such provider. It applies whichever provider you use, so read it before following one of the provider specific pages.

• Stroom Configuration - every Stroom setting involved, and what it does.
• KeyCloak
• Amazon Cognito
• Google
• Microsoft Entra ID (Azure AD)

What Stroom Needs from the Provider

Stroom is a confidential OAuth 2.0 client using the authorization code flow. To register it with a provider you need the following.

STROOM_FQDN is the public facing address of Stroom, which is what you have configured as appConfig.publicUri and is the address users type into their browser. If Stroom is behind a load balancer or Nginx, it is that address and not the address of an individual node.

The Redirect URI

The redirect URI, sometimes called the callback or reply URL, is where the provider sends the user’s browser once they have authenticated.

Stroom uses a single fixed redirect URI:

https://STROOM_FQDN/api/auth/flow/v1/signin-oidc

Register that exact value. It does not vary with the page the user was trying to reach, so there is no need to register a wildcard, and you should not do so. The page the user came from is remembered separately by Stroom and does not travel through the provider.

If Stroom is served under a path prefix, i.e. appConfig.publicUri.pathPrefix is set, that prefix comes before /api.

The Post Logout Redirect URI

When a user signs out, Stroom sends them to the provider’s logout endpoint and asks to be returned to Stroom’s public root:

https://STROOM_FQDN/

Stroom appends a state query parameter to that URI. Providers that match post logout redirect URIs exactly may need to be told to permit it, so if sign out leaves the user on an error page at the provider, that is the usual cause.

The name of the parameter Stroom uses to pass this URI is controlled by logoutRedirectParamName, which may be post_logout_redirect_uri, the default and current specification, or redirect_uri for older providers.

PKCE

Stroom always sends a PKCE code_challenge using the S256 method, and the matching code_verifier when it exchanges the authorization code for tokens.

There is nothing to configure in Stroom for this. Providers that require PKCE, and anything following OAuth 2.1, will be satisfied, and providers that do not support it ignore the extra parameters. Where the provider lets you insist on PKCE, as KeyCloak does, you can safely turn that on.

Claims

Stroom reads three things about a user from the token.

Not every provider issues preferred_username, so check the provider page before assuming the defaults will do.

Token Validation

Stroom validates every token it is given, whether that is the id_token from an interactive sign in or a bearer access token presented to the API.

The signature must verify against a key from the provider’s JWKS, and the algorithm must be one of the RSA, RSA-PSS or ECDSA families. Unsigned tokens and tokens signed with an HMAC algorithm are refused.

The issuer must match what the provider advertised, and the audience must match what Stroom expects. Audience validation is the part most likely to need attention, because providers differ in what they put in the aud claim of an access token. See Audience validation.

Users and Permissions

Authentication is handled by the provider. Authorisation, i.e. what a user may do once they are in, is always handled by Stroom.

Whenever a user successfully signs in via the provider, Stroom automatically creates an entry for them in its own user table. That user starts with no permissions and no group memberships, so an administrator must grant those. This does mean a new user has to sign in once before an administrator can do anything with them.

The very first administrator is a chicken and egg problem, since there is nobody able to grant permissions yet. That is solved with the manage_users command, described on each provider page.