Single sign-on with Okta

This guide connects BROKA to Okta over OpenID Connect: an app integration in Okta, a provider in BROKA, and the groups that put people in BROKA's teams. What each BROKA setting does is described on Single sign-on.

In BROKA, first

In Settings ▸ Security ▸ Single sign-on, choose New provider, then OpenID Connect and Okta, and give it the name people will see on the sign-in page and a Slug, part of the address Okta sends people back to. The sheet's Give your identity provider these section then shows the Redirect URI Okta needs; switch on Also sign out of at the foot of the sheet if BROKA should also sign people out of Okta, and the section shows the Sign-out redirect URI as well. Keep the sheet open.

In Okta

1. In the Admin Console, open Applications ▸ Applications ▸ Create App Integration, and choose OIDC - OpenID Connect and Web Application.
2. Under Sign-in redirect URIs, replace the example address Okta fills in with BROKA's Redirect URI. If BROKA should also sign people out of Okta, replace the example under Sign-out redirect URIs with BROKA's Sign-out redirect URI; otherwise remove that example.
3. Keep the Authorization Code grant type. BROKA always uses PKCE, so Okta's option to require it can be on.
4. Under Assignments, assign the people or groups who may sign in to BROKA — yourself included, so that you can run the test.
5. Save. The app's General tab shows its Client ID and its Client secret; leave client authentication on the client secret.

Groups

A sign-in carries the person's groups in a groups claim. Where you add it depends on the authorization server whose issuer BROKA will use.

A custom authorization server, such as default under Security ▸ API ▸ Authorization Servers, whose issuer is https://example.okta.com/oauth2/default:

1. On its Claims tab, choose Add Claim. Name it groups, include it in the ID Token, Always, set the Value type to Groups and a filter for the groups BROKA should see — Starts with broka-, for example, or Matches regex .* for every group — and include it in Any scope.
2. On its Access Policies tab, the server needs a policy that admits the app. If there is none, choose Add Policy, assign it to the app, and add a rule that allows the Authorization Code grant.

Okta's organisation authorization server, whose issuer is your Okta domain: open the app's Sign On tab and edit OpenID Connect ID Token: set the Groups claim type to Filter, the claim's name to groups, and a filter as above. This server sends the groups only when BROKA asks for the groups scope, which the next section adds. Not every Okta organisation shows that section on the Sign On tab; if yours does not, use a custom authorization server.

A narrow filter keeps the token small and the mapping list short. A filter matches only groups made in Okta. For groups imported from Active Directory or another directory, use an expression instead — the Expression value type on a custom server's claim, or the Expression groups claim type on the Sign On tab — such as Groups.startsWith("active_directory", "broka-", 100).

Okta sends group names. Map them as they arrive. A name is a safe thing to map only while nobody outside your administrators can create a group with it, which is how Okta's groups are usually managed — created by its administrators or imported from your directory.

Okta sends no groups at all for someone in none of the groups the claim selects, and a sign-in without groups changes no membership in BROKA. So removing someone from their last mapped group in Okta leaves their BROKA teams as they are: remove the mapping, or disable the account in BROKA.

Back in BROKA

• Issuer URL: the custom authorization server's issuer, such as https://example.okta.com/oauth2/default, or your Okta domain, such as https://example.okta.com, for the organisation authorization server.
• Client ID and Client secret from the app's General tab.
• Scopes: openid profile email groups with the organisation authorization server. With a custom authorization server, the default, openid profile email, is enough.
• Under Claim names, set Groups are sent as to Names. The claim names themselves fit Okta as they are.

Save, then Test sign-in and sign in as an assigned person. The result shows what Okta sent — the e-mail address and whether Okta says it is verified, and the groups. When it has passed, map the groups to teams under Group mappings, and Enable the provider.

Accounts

Okta says whether an address is verified in email_verified, which BROKA reads as Okta sends it. With Link existing accounts by e-mail on, an existing BROKA account with the same verified address in an allowed domain is linked at the person's first sign-in; with Create an account at first sign-in on, someone with no account gets one when a mapped group is in their sign-in. Both need the allowed domains set to your organisation's own.

Okta says an address is verified only once the person has confirmed it. Someone an administrator created in Okta with a password, who never confirmed their address, signs in without email_verified, and BROKA neither links nor creates an account for them: the sign-in appears under Recent refused sign-ins, where you can link it to an account, or the person confirms their address in Okta and signs in again.

Signing out

With Also sign out of Okta switched on, signing out of BROKA ends the Okta session in that browser, and Okta sends the person back to BROKA's sign-in page — the sign-out address registered in step 2.