Skip to content

Okta SAML Setup Guide»

Info

SSO Integration with SAML 2.0 is an Enterprise plan feature. Check out our pricing page for more information.

This guide walks you through setting up SAML 2.0 Single Sign-On between Okta and Spacelift, including how to pass group membership so you can use it for permissions in Spacelift.

Warning

Before setting up SSO, it's recommended to create backup credentials for your Spacelift account for use in case of SSO misconfiguration, or for other break-glass procedures. You can find more about this in the Backup Credentials section.

Pre-requisites»

  • Spacelift account, with access to admin permissions
  • Okta account, with permission to create Okta App Integrations

Info

You need to be an admin on the Spacelift account to access the Organization settings to configure Single Sign-On.

Open Spacelift SSO Settings»

Open Organization settings for your Spacelift account by clicking the arrow next to your name at the bottom left.

Select Single Sign-On under Authorization. Click Set up next to the SAML section.

A drawer opens containing the Single Sign-On URL and Entity ID (audience) values. Keep this drawer open - you'll need both values in the next step.

These URLs will be different for your account

Create the Okta App Integration»

In a new browser tab, open your Okta account. Select Applications from the navigation, then click the Create App Integration button.

For the sign-in method, select SAML 2.0 and click Next.

Give your app integration a name (e.g., "Spacelift") and click Next.

In the Configure SAML step, fill in the following fields using the values from the Spacelift drawer:

  • Single Sign-On URL: Paste the Single Sign-On URL from Spacelift (e.g., https://<account>.app.spacelift.io/saml/acs). Make sure the Use this for Recipient URL and Destination URL checkbox is ticked.
  • Audience URI (SP Entity ID): Paste the Entity ID (audience) from Spacelift (e.g., https://<account>.app.spacelift.io/saml/metadata).
  • Name ID format: EmailAddress is a good default. Transient and Persistent are also supported.

Okta SAML configuration

Finish the remaining steps of the wizard.

Configure Spacelift with Okta Metadata»

After completing the Okta wizard, you'll be presented with the app's Metadata URL. It looks something like https://<org>.okta.com/app/<app-id>/sso/saml/metadata.

Back in the Spacelift SAML setup drawer:

  1. Tick Dynamic configuration.
  2. Paste the Metadata URL into the IdP metadata URL field.
  3. Click Save.

Provide it in Spacelift in the IdP metadata URL field and save.

Configure Group Attribute Statements»

This step is critical for passing Okta group membership to Spacelift. Without it, Spacelift won't know which groups your users belong to, and any group-based permissions won't work.

  1. Open the Okta application you just created.
  2. Go to the Sign On tab.
  3. Scroll down to the Attribute statements section and find Group attribute statements (it may be under "Show legacy configuration").
  4. Add a group attribute statement with the following values:
    • Name: Teams (case-sensitive)
    • Name format: Unspecified
    • Filter: Matches regex .*
  5. Click Next, then Finish to save.

The attribute name must be exactly Teams

Spacelift reads the Teams SAML attribute (case-sensitive) to populate group membership in user sessions. If this attribute is missing or named differently, input.session.teams in login policies will be empty and IdP group mappings won't match any groups.

If your Okta configuration uses a different attribute name (e.g., Groups), you can use the Custom Attribute Mapping feature to map it to Teams on the Spacelift side.

Tip

The .* regex filter sends all group memberships. You can use a more specific filter to limit which groups are sent to Spacelift, for example ^Spacelift-.* to only send groups whose names start with "Spacelift-".

Using Group Permissions in Spacelift»

Once the Teams attribute is configured, the Okta groups each user belongs to will be available in Spacelift. How you use them depends on your management strategy:

  • User Management strategy: Map Okta groups to roles in specific spaces through IdP group mappings. Anyone assigned to those groups in Okta will automatically get the corresponding permissions in Spacelift.
  • Login Policies strategy: Reference groups via input.session.teams in your Rego-based login policies to control access and assign roles programmatically.

Info

Users must log out and log back in for group membership changes to take effect in their Spacelift session.

Okta SAML Setup Completed»

That's it! Your SAML 2.0 integration with Okta should now be fully configured, with group membership flowing through to Spacelift for use in permissions and policies.