Skip to content
Last updated

Configure SSO with Okta and SAML2

In this video, we integrate Okta with Redocly to set up Single Sign-On (SSO) using SAML2.

This step-by-step tutorial shows you how to create an identity provider in Redocly, configure an Okta application, assign user groups, and test the connection.

It also covers using group attributes for customized access controls, giving you complete flexibility in managing team permissions. Follow along and simplify your Redocly access with Okta!

Preserve the Owner organization role

Critical step: Complete this step before clicking Save in Reunite to prevent getting locked out of your organization.

To prevent Okta from changing users' roles to the default organization role specified in the SSO settings:

  1. In Okta, navigate to Directory > Groups.
  2. Create a group named redocly.owners.
  3. Navigate to Directory > People and assign users with an Owner role in your organization to the redocly.owners group.
  4. Return to Reunite and click Save to complete the identity provider setup.

Configure SSO in Redocly Reunite

  1. Log into your Redocly Reunite account.
  2. Navigate to Organization settings > SSO.
  3. Click Create identity provider.
  4. Select SAML 2.0 as the SSO method.
  5. Choose Corporate SSO account to enable SSO for both Reunite and internal projects.
  6. Keep this page open - you'll need to copy values from here to Okta and then return to complete the setup.

Create SAML application in Okta

  1. In your Okta dashboard, navigate to Applications.
  2. Click Create App Integration.
  3. Select SAML 2.0 as the sign-in method.
  4. Click Next.
  5. Fill out the general settings:
    • App name: Enter a descriptive name like "Redocly Reunite"
    • App logo: Upload your company logo (optional)
  6. Copy the Single sign-on URL and Audience URI from your Reunite SSO page and paste them into the corresponding fields in Okta.

Configure group attribute statements

Group attributes enable role-based access control (RBAC) by passing Okta group memberships to Redocly.

  1. In the Attribute Statements section of your Okta SAML app:
    • Name: Enter redocly.com/sso/teams
    • Name format: Select URI Reference
    • Value: Enter getFilteredGroups(group.name, "redocly.", 40)
  2. This filter passes all groups that start with "redocly." to Redocly.
  3. Click Next.
  4. Select This is an internal app that we have created.
  5. Click Finish.

Get SAML setup information

  1. In your newly created Okta app, click View SAML setup instructions.
  2. Copy the following information - you'll need it to complete the Reunite setup:
    • Identity Provider Single Sign-On URL
    • Identity Provider Issuer
    • X.509 Certificate

Complete SSO setup in Reunite

  1. Return to your Reunite SSO configuration page.
  2. Fill out the remaining fields with information from Okta:
    • Single sign-on URL: Paste the URL from Okta
    • Issuer ID: Paste the issuer URL from Okta
    • X.509 Certificate: Paste the certificate from Okta
  3. Set the Default organization role to Owner initially to ensure you don't lose administrative access.
  4. Click Save to create the identity provider.

Create and assign Okta groups

  1. In Okta, navigate to Directory > Groups.
  2. Create groups using the naming pattern that starts with "redocly.":
    • redocly.owners (for organization owners)
    • redocly.members (for organization members)
    • Add any project-specific groups as needed
  3. Navigate to Directory > People.
  4. Assign users to the appropriate groups.
  5. Return to your SAML application in Okta.
  6. Go to the Assignments tab.
  7. Click Assign > Assign to Groups.
  8. Assign your newly created groups to the application.

Test SSO login

  1. Log out of Reunite.
  2. Navigate to your organization's SSO login URL: https://app.redocly.com/org/YOUR_ORG_SLUG
  3. Click Login with SSO.
  4. Complete the Okta authentication flow.
  5. If you're using the same email address as your existing Redocly account, you'll be prompted to link accounts.
  6. Verify you can access all expected features and that your organization role is preserved.

Update default organization role

After confirming SSO works correctly, you can adjust the default role for new users:

  1. In Reunite, navigate to Organization settings > SSO.
  2. Edit your identity provider.
  3. Change the Default organization role to Member or Viewer based on your security requirements.
  4. Save the changes.
  5. Test by logging out and back in to ensure you retain access.

Test project SSO and RBAC

To test project-level access control using Okta groups:

  1. In your project's redocly.yaml file, configure SSO and RBAC:

    sso:
  type: corporate
rbac:
  content:
    "**": read
  tutorials:
    redocly.developers: read

    This example allows everyone to read all content, but restricts tutorials to the redocly.developers group.

  2. Create the redocly.developers group in Okta.

  3. Assign users to the group.

  4. Assign the group to your SAML application in Okta.

  5. Test access by logging into your project - users should only see content they have permissions for.

Resources

Your SSO integration with Okta is now complete. Users can access Redocly using their corporate credentials, and you can manage permissions through Okta groups.

 
Next page