Single sign-on with Okta

Verified end to end against an Okta organization with ShakerScan Enterprise 0.2.0-beta.3 and later; the same steps apply to any Okta tenant. Every step below was needed; the two mistakes that are easy to make are in the troubleshooting section so you do not repeat them. Time: about fifteen minutes in Okta, two on the ShakerScan host.

Terms used here: the host is your Linux server running ShakerScan Enterprise, reachable at its public address, https://scanner.example.com in the examples. Replace it with yours.

What you get

• People sign in to ShakerScan with their Okta account (Authorization Code flow with PKCE, a confidential client; no passwords ever reach the host).
• Their ShakerScan role (viewer, operator or administrator) comes from an Okta group on their first sign-in. After that the role is managed in the ShakerScan console, not in Okta.
• Okta's own MFA and sign-on policies apply, because the sign-in happens at Okta.

What you do not get in this beta: automatic deprovisioning (SCIM), Okta-initiated sign-out, or continuous group synchronization. Removing a person means disabling their identity in the ShakerScan console (which revokes their sessions) and unassigning the app in Okta.

Before you start

• The host is installed and its public address works over HTTPS (the sign-in page at https://scanner.example.com/_enterprise/login opens).
• You are an Okta administrator (Super Administrator or Application Administrator plus the ability to edit the authorization server).
• Decide the group names. This guide uses shakerscan-admins, shakerscan-operators and shakerscan-viewers. Any names work as long as the ShakerScan configuration in step 5 matches.

Step 1: create the application in Okta

1. In the Okta Admin Console open Applications → Applications and click Create App Integration. Do not use the "Create app and add integrations" wizard on the dashboard; that one publishes to Okta's catalog and asks for a review.
2. Sign-in method: OIDC - OpenID Connect. Application type: Web Application. Next.
3. General settings:
   • App integration name: ShakerScan Enterprise (any name).
   • Grant type: leave Authorization Code ticked. Do not enable Implicit.
   • Sign-in redirect URIs: exactly https://scanner.example.com/_enterprise/oidc/callback (your public address, then /_enterprise/oidc/callback; no trailing slash).
   • Sign-out redirect URIs: leave empty.
   • Trusted Origins: leave empty.
   • Assignments: for a pilot, Allow everyone in your organization to access; for production, Limit access to selected groups and pick the ShakerScan groups from step 3.
4. Save. On the app's General tab note the Client ID (it starts with 0oa) and reveal the Client secret. Copy the secret to a password manager; you will put it on the host in step 5 and never anywhere else.

Step 2: allow the application on the authorization server

ShakerScan uses Okta's default custom authorization server (issuer https://<your-org>.okta.com/oauth2/default). A custom authorization server only issues tokens to applications its access policies allow. A fresh organization may have no policy, in which case every sign-in fails with "Policy evaluation failed" before the person even sees ShakerScan.

1. Open Security → API → Authorization Servers and click default.
2. Open the Access Policies tab.
   • If a policy is listed, open it and check it is active and its rule allows the Authorization Code grant for the people you assign.
   • If none is listed, click Add New Access Policy: name ShakerScan, assign to All clients (or select the ShakerScan application), Create Policy. Then Add rule: name Allow sign-in, grant type tick Authorization Code only, user is Any user assigned the app, scopes Any scopes, Create Rule.
3. Stay on the same authorization server for step 4.

Step 3: create the groups and add people

1. Open Directory → Groups and click Add group for each role you need: shakerscan-admins, shakerscan-operators, shakerscan-viewers.
2. Open each group, People tab, Assign people, and add the members. Put at least one person (yourself) in shakerscan-admins before the first sign-in.
3. You do not need to assign the application to the groups on the group's Applications tab. The role comes from the group membership carried in the ID token (step 4); access to the application comes from step 1's assignment.

Step 4: put the groups into the ID token

1. Back in Security → API → Authorization Servers → default, open the Claims tab and click Add Claim.
2. Fill in: Name groups; Include in token type ID Token, Always; Value type Groups; Filter Starts with shakerscan-; Include in Any scope. Create.
3. Optional check: on the Token Preview tab pick the ShakerScan application, grant type Authorization Code, your user, scopes openid profile email, and preview the ID token. The groups claim must list your ShakerScan groups. If it is missing, the filter or your membership is wrong.

Step 5: configure ShakerScan Enterprise on the host

In the console (0.2.0-beta.22 and later): as an administrator, open Settings → Single sign-on, enter the issuer, client ID, client secret and the group-to-role table from the steps above, and choose Test sign-in. The test goes to Okta, reports what it sent and what came back, and signs no one in. Save when it passes; the setting applies without a restart and is audited. The host-file steps below do the same and remain available, for example for automation.

All commands run on the host as the user who installed ShakerScan; /srv/shakerscan-enterprise is the deployment directory created by prepare.

1. Put the client secret in the deployment's secrets directory, readable only by the gateway (it runs as user and group 10001):

   umask 077
   printf '%s' '<client secret from step 1>' | sudo tee /srv/shakerscan-enterprise/secrets/oidc-client-secret >/dev/null
   sudo chown 10001:10001 /srv/shakerscan-enterprise/secrets/oidc-client-secret
   sudo chmod 0440 /srv/shakerscan-enterprise/secrets/oidc-client-secret
   

   Type the secret into that command rather than pasting it into a file you keep; the directory is mounted read-only into the gateway at /run/enterprise-secrets/.

2. Append the identity-provider settings to /srv/shakerscan-enterprise/enterprise.env (replace the organization, the client id and the group names):

   SHAKERSCAN_ENTERPRISE_OIDC_ISSUER=https://<your-org>.okta.com/oauth2/default
   SHAKERSCAN_ENTERPRISE_OIDC_CLIENT_ID=0oa...
   SHAKERSCAN_ENTERPRISE_OIDC_CLIENT_SECRET_FILE=/run/enterprise-secrets/oidc-client-secret
   SHAKERSCAN_ENTERPRISE_OIDC_TOKEN_AUTH_METHOD=client_secret_basic
   SHAKERSCAN_ENTERPRISE_OIDC_SCOPES=openid profile email
   SHAKERSCAN_ENTERPRISE_OIDC_GROUPS_CLAIM=groups
   SHAKERSCAN_ENTERPRISE_OIDC_GROUP_ROLES={"shakerscan-admins":"admin","shakerscan-operators":"operator","shakerscan-viewers":"viewer"}
   

   The issuer is the exact Issuer URI shown in Okta's Authorization Servers list. Do not add a groups scope; the claim is delivered because it is marked Always.

3. Restart the gateway and confirm the sign-in page now offers single sign-on:

   cd /srv/shakerscan-enterprise
   docker compose -f compose.json up -d --wait enterprise
   curl -s https://scanner.example.com/_enterprise/login-options
   

   The answer contains "oidc":true. Local password sign-in stays available for break-glass administrators unless you disable it later.

Step 6: first sign-in and what to expect

1. Open https://scanner.example.com/_enterprise/login and click Sign in with your organization. Okta signs you in (with its MFA if your policy requires it) and returns you to ShakerScan.
2. You land in the scanner workspace, whatever your role. A small circle in the top-right corner opens the session panel: your name and role, the Enterprise administration page (for administrators) and Sign out.
3. In the console under Identities the new identity appears with kind oidc, its Okta subject (an id starting with 00u), your display name and the mapped role, and the audit history shows login.oidc with outcome created for the first sign-in and ok afterwards.
4. From now on the role is local. Changing a person's Okta groups does not change their ShakerScan role; change it in the console. Disabling the identity in the console revokes their sessions immediately.

Admitting a person without group mapping: an administrator can create an identity of kind OIDC in the console with the person's exact Okta subject (00u..., visible in Okta under Directory → People → the person, in the page address) and the role; their first sign-in then matches that record.

Troubleshooting

Nothing about a person's sign-in is sent anywhere but Okta and your host; the gateway audits the outcome, the subject and the group names, never the tokens.

What was verified

An Okta organization with an OIDC web application, the default authorization server with the access policy and the groups claim from steps 2 and 4, and a shakerscan-admins group with one member. The first sign-in from a normal browser created the OIDC identity with the administrator role; subsequent requests from the scanner workspace ran under that identity, and the audit history recorded the sign-in without tokens.