# Setting Up Okta SSO

This document outlines the steps required to set up Okta SSO with StepSecurity.

**You can follow this interactive demo to get started with setting up Okta SSO:**

{% embed url="<https://app.storylane.io/share/zk8kh3vae0go>" %}

### Setup Instructions

#### Step 1: Configure SAML Settings

* On the StepSecurity App navigate to Admin Console → Security & Auth → Configure SSO → Okta

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FTQYo1CxOfzPHUC8vlEVJ%2FScreenshot%202025-11-12%20at%2014.25.50.png?alt=media&#x26;token=bfe03995-dc4c-4202-bd8d-03011a804ba8" alt=""><figcaption></figcaption></figure>

* Copy the values displayed here

#### Step 2: Log in to Okta

* Log in to the Okta Admin Console
* Navigate to Applications > Applications from the left sidebar.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FqwCL3RRJlTg3FU9mfq5x%2FScreenshot%202025-03-26%20at%208.33.09%E2%80%AFPM.png?alt=media&#x26;token=559dd8d8-be14-44f6-8956-2a7cf5b7c7f9" alt="" width="324"><figcaption></figcaption></figure>

#### Step 3: Create App Integration

* Click on Create App Integration on the Applications page.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FFa33HneC5e3LOQa7o77y%2FScreenshot%202025-03-26%20at%208.36.37%E2%80%AFPM.png?alt=media&#x26;token=a010a4bc-ff7c-4d46-9144-b456a6939ee1" alt=""><figcaption></figcaption></figure>

#### Step 4: Choose SAML 2.0

* Select SAML 2.0 as the Sign-in method, then click Next.<br>

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FeYGJVG8RxmsaBLt2vZaK%2FScreenshot%202025-03-26%20at%208.39.12%E2%80%AFPM.png?alt=media&#x26;token=b7ced993-f89e-4295-94af-e551f318d7ff" alt=""><figcaption></figcaption></figure>

#### Step 5: Configure General Settings

* On the General Settings page:
  * Enter the App name as StepSecurity.
  * Optionally, add the StepSecurity logo:

    [StepSecurity Logo Link](https://stepsecurity-public-media.s3.us-west-2.amazonaws.com/media/step-security-logo.png)
* Click Next to continue.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FhhVJziWou90mOrhHRTbI%2FScreenshot%202025-03-26%20at%208.42.45%E2%80%AFPM.png?alt=media&#x26;token=bf22f9f8-b57b-4098-bf9a-4ad33ad646e1" alt=""><figcaption></figcaption></figure>

#### Step 6: Configure SAML Settings

* Paste the values you obtained from the StepSecurity App into the corresponding fields in Okta

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FUk7WuxwpBD30oLb3AQeA%2FScreenshot%202025-03-26%20at%208.52.57%E2%80%AFPM.png?alt=media&#x26;token=d9ea37d5-15f9-4164-aa57-77a94b453e58" alt=""><figcaption></figcaption></figure>

#### Step 6: Add Attribute Statement

* Under Attribute Statements, add the following field:
  * email → user.email

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FnLafEaNPynQD1QZP5uCB%2FScreenshot%202025-03-26%20at%209.06.02%E2%80%AFPM.png?alt=media&#x26;token=22af76a4-bf2f-4ad3-9e6f-f2d6b6fc9ee3" alt=""><figcaption></figcaption></figure>

#### Step 7: Add Group Attribute Statements

* Scroll down to ‘Group Attribute Statements’ and add following field.
  * Set Name as ‘Groups’&#x20;
* We recommend creating dedicated Okta groups for StepSecurity, such as `StepSecurity-Administrators` and `StepSecurity-Auditors`. Follow the instructions below to set them up:

<details>

<summary><strong>How to Setup StepSecurity Okta Groups</strong></summary>

1. Navigate to the Admin Console in your Okta dashboard and select Groups

![](https://colony-recorder.s3.amazonaws.com/files/2026-01-06/6bbe7362-3052-45b1-838d-0031b36209a4/ascreenshot_f14a324afdf449d7848b6dea7dc8d83f_text_export.jpeg)

2\. Click "Add group"

![](https://colony-recorder.s3.amazonaws.com/files/2026-01-06/26f134b6-2763-4282-8734-8cf28604af70/ascreenshot_9fef4a89c64b4368aede2ffa58693a6e_text_export.jpeg)

3. Enter `StepSecurity-Auditors` as the group name. (Usually there are two groups that should be created `StepSecurity-Administrators` is the second one

![](https://colony-recorder.s3.amazonaws.com/files/2026-01-06/c2457df7-b0f2-44dd-b33b-ee1e8a195346/ascreenshot_7c6851f1e6694652975698d7cd41b5c7_text_export.jpeg)

4\. Click "Submit"

![](https://colony-recorder.s3.amazonaws.com/files/2026-01-06/c587c465-86ba-45c5-99b0-298bcd8b3d3e/ascreenshot_e4d77be07b4344d4915190fcd5d70623_text_export.jpeg)

5. Repeat the same steps to create StepSecurity-Administrators

![](https://colony-recorder.s3.amazonaws.com/files/2026-01-06/8dc72129-3616-4000-b5c4-14647ddd5f09/ascreenshot_a42b65db568c4df099c138ab273d04ca_text_export.jpeg)

6\. To add users to a group, select the group and click Assign people&#x20;

![](https://colony-recorder.s3.amazonaws.com/files/2026-01-06/370de5bb-9b3d-41b0-95d8-a952a1c708cd/ascreenshot_8b105429ba544e9aaa49a8b5f2414198_text_export.jpeg)

</details>

* Choose Matches regex and enter this regex  `.*StepSecurity`*`.*`*

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FmbXNgCjbGbuloNch2Wds%2FScreenshot%202026-01-06%20at%2016.39.36.png?alt=media&#x26;token=21220ae4-ba3f-409e-be16-c98342658ef0" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
**You should only pass specific groups to the StepSecurity platform. If the app passes all group memberships, it may exceed the maximum request body size**
{% endhint %}

* This enables StepSecurity’s SCIM-like functionality — for example, you can use Okta groups and map them to roles in the StepSecurity dashboard.

#### Step 8: For Idp Initiated login(Optional)

* In the Okta Admin Console, navigate to StepSecurity app → Sign On → Settings → Edit, then paste the Default Relay State value (copied from the StepSecurity App) into the SAML 2.0 section **(For IDP initiated login)**

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2Fr6Rwbx5rv79mvSvmdlI8%2FScreenshot%202025-07-03%20at%202.19.08%E2%80%AFPM.png?alt=media&#x26;token=1f0ab530-9055-4c8e-9f0f-02ceb0bda654" alt=""><figcaption></figcaption></figure>

#### Step 9: Assign User to Application

* Ensure you are added to the Okta application as a user so you can access it.
* To do this, go to the Applications section, click "Assign Users to App", select both the application and the user you want to assign, then confirm the assignment.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FDr8o3cDZ1jfWsqp9LR4d%2FScreenshot%202025-11-30%20at%2005.45.06.png?alt=media&#x26;token=8e7f7a82-a9aa-40e0-821a-0a027c7ae8ac" alt=""><figcaption></figcaption></figure>

#### Step 10: Save Settings

* Scroll down keeping the default values, then click Next.

#### Step 11: Share Metadata URL

* After finishing, you will see a screen displaying the Metadata URL. Copy this URL.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2F7CBHRuxFckskoY4934yG%2FScreenshot%202025-03-26%20at%209.57.27%E2%80%AFPM.png?alt=media&#x26;token=6103f6bb-aa61-4aee-ae69-15610b57f9f9" alt=""><figcaption></figcaption></figure>

* On the StepSecurity App share the Email Domains and Metadata URL gotten from the Okta App and submit the configuration. Ping the StepSecurity team on Slack or email, then wait for the StepSecurity Operations Team to update your tenant

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FkSoM58tjSPUVhsxVrrUn%2FScreenshot%202025-11-12%20at%2014.34.18.png?alt=media&#x26;token=dae6f0df-381c-4b1c-8e30-c9e464721cea" alt=""><figcaption></figcaption></figure>

#### Step 12: Confirm SSO Setup

* On the StepSecurity → Security & Auth page, you can test your SSO integration.
* To verify that the SSO flow is working, follow these steps:
  * Authorize your email address for SSO access: Navigate to the Admin Console -> Members and click "Add Members".
  * Select SSO as the Authentication Type and add your email as an authorized member.
  * Log out of your current StepSecurity session.
  * Go to `https://app.stepsecurity.io/login` and log in using SSO.
  * Confirm that you can successfully access the dashboard.
* For additional confirmation, go to Admin Console → Security & Auth, then in Step 3 of the Okta SSO configuration, click "Run SSO Test". Verify that all checks on the test page pass successfully

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FLeLebA3ZsNtka9o6rEMS%2FScreenshot%202025-12-02%20at%2000.34.08.png?alt=media&#x26;token=b16acb09-afa9-44cc-8d6c-868473324eab" alt=""><figcaption></figcaption></figure>

#### Step 13: Add Members

{% hint style="info" %}
**Important**: If any changes are made to SSO group membership in Okta (for example, adding or removing a user from a group), the affected user must log out and log back into StepSecurity for the updated group access and role mappings to take effect immediately otherwise it will be reflected once the sso session is renewed.
{% endhint %}

Every SSO identity must be explicitly authorized in the StepSecurity dashboard. You can do this in two different ways:

* Authorize Individual users
* Authorize Okta groups

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2F0Gtk8FNBuunega7gTv9V%2FScreenshot%202025-11-21%20at%2014.12.55.png?alt=media&#x26;token=28ee9f18-a405-474d-a15a-d36bf96a0360" alt=""><figcaption></figcaption></figure>

**To authorize individual users:**

* The user must also be explicitly authorized to access the Okta application, either by assigning the user directly to the app or by assigning a group the user belongs to.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FOrjL0slMVu5qWI5Wdlbz%2FScreenshot%202025-11-30%20at%2006.21.26.png?alt=media&#x26;token=c16ec2f6-3241-406c-9894-aedc9ac2cf72" alt=""><figcaption></figcaption></figure>

* Once the user is authorized in Okta in your StepSecurity dashboard navigate to Admin Console -> Members

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FGGXqrFtZvhBWQ00FXDMo%2FScreenshot%202025-12-01%20at%2013.11.34.png?alt=media&#x26;token=9b74a1ea-6549-4244-be12-aa5e30834315" alt=""><figcaption></figcaption></figure>

* Click "Add Members" and select the SSO option
* Add the user's email address

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FkTW91j3VEFQ5s9Sdo1ZC%2FScreenshot%202025-12-01%20at%2013.12.46.png?alt=media&#x26;token=a9584436-5d3f-4585-91d6-0faa051d2a74" alt=""><figcaption></figcaption></figure>

**To authorize Okta groups:**

* Ensure that the Okta group is authorized to use the Okta application

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FjgA5mUoY00umo4G8DnzM%2FScreenshot%202025-11-30%20at%2006.20.11.png?alt=media&#x26;token=be730de0-be5c-4f2b-a0d6-00e997a272a5" alt=""><figcaption></figcaption></figure>

* Once the group is authorized in Okta in your StepSecurity dashboard navigate to Admin Console -> Members
* Click "Add Members" and select the SSO Group option
* Add the SSO group

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FyBO8u3iq3aARh2g3ChuA%2FScreenshot%202025-12-01%20at%2013.23.53.png?alt=media&#x26;token=7e57375f-24ef-476f-9569-1bdbcb936f20" alt=""><figcaption></figcaption></figure>

For more details on adding members to your StepSecurity dashboard, visit this [documentation](https://docs.stepsecurity.io/admin-console/members).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stepsecurity.io/admin-console/security-and-auth/setting-up-okta-sso.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.