SSO with Okta

This guide connects UTMStack v12 to Okta so your users sign in with their Okta account. It covers OpenID Connect (OIDC) and SAML 2.0, and explains how to send Okta groups so UTMStack can give roles from them.

Read Single Sign-On first for how sign-in, accounts and roles work in UTMStack. Single sign-on needs an Enterprise licence.

Which protocol to use with Okta

The reason: UTMStack asks Okta for the openid, profile and email scopes. Okta's org authorization server adds groups to the ID token only when the groups scope is requested, while a custom authorization server can be told to always include them.

What you need

• In Okta: an administrator who can create app integrations and assign them (for example Super Administrator or Application Administrator).

• In UTMStack: the Administrator role.

• The address users open UTMStack with. This guide uses https://siem.example.com, the Okta domain example.okta.com and the provider name okta. On a multi-tenant server, use the tenant's own address.

• Okta groups for UTMStack access, for example UTMStack-Admins, UTMStack-Analysts and UTMStack-Viewers.

Setup A: OpenID Connect, sign-in only

In Okta

1. 1

   Create the app integration

   In the Okta Admin Console, go to Applications > Applications and click Create App Integration. Choose OIDC - OpenID Connect and Web Application, then click Next.

2. 2

   Fill in the settings

   Okta field	Value
   App integration name	UTMStack
   Grant type	Authorization Code (selected by default)
   Sign-in redirect URIs	https://siem.example.com/api/v1/sso/okta/callback
   Sign-out redirect URIs	Remove the default entry
   Assignments	Limit access to selected groups, and choose the UTMStack groups

   Click Save.

3. 3

   Copy the client credentials

   On the General tab, copy the Client ID and the Client secret.

In UTMStack

Add a provider named okta of type OpenID Connect:

Keep Active (show on the login page) on (the default), save, and test with https://siem.example.com/api/v1/sso/okta/login in a private browser window. UTMStack refuses sign-ins through an inactive provider, even at its /login address.

Setup B: OpenID Connect with groups

This needs a custom authorization server in Okta, such as the one named default, available with Okta API Access Management.

1. Create the app integration as in Setup A.

2. Go to Security > API > Authorization Servers and open the server you will use (for example default). Copy its Issuer URI, for example https://example.okta.com/oauth2/default.

3. On the Claims tab, click Add Claim:

   Okta field	Value
   Name	groups
   Include in token type	ID Token, Always
   Value type	Groups
   Filter	Starts with UTMStack- (or Matches regex .* for all groups)
   Include in	Any scope

4. On the Access Policies tab, make sure a policy and rule allow the UTMStack app integration to use this server.

In UTMStack, set Issuer URL to the authorization server's issuer, https://example.okta.com/oauth2/default, and under Accounts and roles:

Okta sends group names, so map the names exactly as they appear in Okta (upper and lower case do not matter).

Setup C: SAML 2.0 with groups

The provider name in this example is okta-saml.

In Okta

1. 1

   Create the app integration

   Go to Applications > Applications > Create App Integration, choose SAML 2.0 and click Next. Name it UTMStack and click Next.

2. 2

   Configure SAML

   Okta field	Value
   Single sign-on URL	https://siem.example.com/api/v1/sso/okta-saml/acs, with Use this for Recipient URL and Destination URL ticked
   Audience URI (SP Entity ID)	https://siem.example.com/api/v1/sso/okta-saml
   Name ID format	EmailAddress
   Application username	Email

3. 3

   Add attribute statements

   Name	Value
   email	user.email
   displayName	user.displayName (or user.firstName + " " + user.lastName)

   Under Group Attribute Statements, add the name groups with the filter Starts with UTMStack- (or Matches regex .*).

   Click Next, choose that this is an internal app, and click Finish.

4. 4

   Copy the metadata URL

   On the Sign On tab, copy the Metadata URL (it ends in /sso/saml/metadata).

5. 5

   Assign and hide the tile

   On the Assignments tab, assign the UTMStack groups. On the General tab, under App Settings, tick Do not display application icon to users: UTMStack refuses sign-ins started from the Okta dashboard, so the tile would only lead to an error. Users start from the UTMStack sign-in page.

In UTMStack

Create the SP certificate and key as shown in Single Sign-On, then add a provider named okta-saml of type SAML 2.0:

Test with https://siem.example.com/api/v1/sso/okta-saml/login.

Troubleshooting

If Okta accepts the sign-in but UTMStack refuses it with "this identity maps to no role, and the provider has no default", the token or assertion carries no groups: check Setup B or C, or set a Default role. For other messages, see Troubleshooting in Single Sign-On.