Google

This page covers using Google Identity as Stroom’s 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..., whether for consumer Google accounts or for a Google Workspace domain.

Creating the OAuth Client

In the Google Cloud Console :

1. Select or create a project.
2. Configure the OAuth consent screen. For a Workspace domain choose the Internal user type, which restricts sign in to your own domain. For consumer accounts the only option is External.
3. Go to APIs & Services => Credentials => Create Credentials => OAuth client ID.
4. Choose an application type of Web application.
5. Under Authorised redirect URIs, add https://STROOM_FQDN/api/auth/flow/v1/signin-oidc.
6. Create the client and note the Client ID and Client secret.

Where STROOM_FQDN is the public address of Stroom, i.e. what you have set as appConfig.publicUri.

Google supports PKCE, and Stroom always sends an S256 challenge, so there is nothing to configure for it.

There is no sign out URL to register, because Google has no OIDC sign out endpoint to register one with.

Configuring Stroom

  security:
    authentication:
      authenticationRequired: true
      openId:
        identityProviderType: EXTERNAL_IDP
        openIdConfigurationEndpoint: "https://accounts.google.com/.well-known/openid-configuration"
        clientId: "123456789012-abcdefghijklmnop.apps.googleusercontent.com"
        clientSecret: "THE_CLIENT_SECRET"
        # Google issues no 'preferred_username' claim
        userDisplayNameClaim: "email"
        # 'profile' is needed for the 'name' claim used by fullNameClaimTemplate
        requestScopes:
          - "openid"
          - "email"
          - "profile"

The discovery document supplies the issuer, https://accounts.google.com, along with the authorization, token and JWKS endpoints, so none of those need setting by hand.

Note that logoutEndpoint is deliberately absent; see Signing out below.

Audience Validation

Nothing to do. Google’s id_token carries aud set to your client id, so it validates against clientId with the default settings.

Claims

Google issues sub, email, email_verified, name, given_name, family_name and picture, and hd for a Workspace account. It does not issue preferred_username, which is Stroom’s default for userDisplayNameClaim, so that has to be changed. email is the natural choice.

name, given_name and family_name require the profile scope, which is why it is added to requestScopes above. Without it the default fullNameClaimTemplate of ${name} will not resolve.

Leave uniqueIdentityClaim as sub. Google’s sub is stable for a given account, unlike the email address.

Signing Out

Google offers no OIDC sign out endpoint, so leave logoutEndpoint unset.

Logging out of Stroom then ends the Stroom session but leaves the user signed in to Google. Their next visit to Stroom will sign them straight back in without being asked for credentials, which is worth being aware of on a shared machine.

Do not point logoutEndpoint at a general Google sign out URL, as that would sign the user out of every Google service on that browser, which is unlikely to be what they expect from a Stroom logout.

Access Token Type

Leave requiredAccessTokenType unset. It applies to JWT bearer tokens on the API, and Google’s access tokens are not JWTs.

Restricting Who Can Sign In

Authentication and authorisation are separate. Anyone Google will authenticate can complete a sign in and have a Stroom user created for them, but that user starts with no permissions and no group memberships, so they can see nothing.

Even so, you should restrict who can reach the sign in at all:

• For a Workspace domain, set the OAuth consent screen to Internal, so only accounts in your domain can authenticate.
• For consumer accounts there is no equivalent, so any Google account can reach the consent screen. Consider whether Google is the right provider in that case.

Stroom has no configuration to restrict sign in by hd or email domain, so this has to be done at Google.

Setting up the Admin User in Stroom

Find the sub of the account that is to be the administrator. Unlike KeyCloak and Cognito, Google does not show this in an admin console; the reliable way to obtain it is to decode an id_token issued for that account, or read it from Stroom’s logs after the person has signed in once.

The simplest route is therefore:

1. Configure Stroom as above and start it.
2. Have the intended administrator sign in once. They will land in Stroom with no permissions.
3. Read their sub from the Stroom logs, or from the
   Tools

   Users
   screen if another administrator is available.
4. Run the manage_users command with that value, then restart Stroom so the permission caches are rebuilt.

subject_id="XXX"; \
java -jar /absolute/path/to/stroom-app-all.jar \
  manage_users \
  --createUser "${subject_id}" \
  --createGroup Administrators \
  --addToGroup "${subject_id}" Administrators \
  --grantPermission Administrators "Administrator" \
  ../local.yml

The command is repeatable and will skip anything that already exists, so running it against a user that signed in earlier is fine.

Data Receipt and the API

Because Google’s access tokens are opaque rather than JWTs, Stroom cannot validate them, so this will not work:

  receive:
    authenticationRequired: true
    tokenAuthenticationEnabled: true

Use Stroom API Keys API Key API Keys are a form of authentication token that are created within Stroom for use by Stroom-Proxy instances or other clients that want to use Stroom’s API. It is an encrypted string that contains details of the user and the expiration date of the token. Possession of a valid API Key for a user account means that you can do anything that the user can do in the user interface via the API.Click to see more details... for API clients and for feed status checks, or client certificates for data receipt.

Stroom-Proxy with Google

Google has no OIDC client credentials grant, so a Stroom-Proxy cannot obtain a service user token from it, and addOpenIdAccessToken on a forward destination has nothing to add.

Configure the proxy with identityProviderType: NO_IDP and give it an API key created in Stroom:

  feedStatus:
    apiKey: "AN_API_KEY_CREATED_IN_STROOM"
  security:
    authentication:
      openId:
        identityProviderType: NO_IDP