> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta SSO setup

Superblocks single sign-on (SSO) with Okta lets your team seamlessly authenticate and access Superblocks using their Okta credentials. Optionally, you can also let users sign in from the Superblocks tile on their Okta dashboard (IdP-initiated login). This guide walks you through how to configure single sign-on for Superblocks.

## Prerequisites

To setup SSO for your organization, you'll need:

* An Okta account
* A user account with **[App Admin](https://help.okta.com/en-us/content/topics/security/administrators-admin-comparison.htm)** access
* A Superblocks organization on the **[Enterprise](https://www.superblocks.com/pricing)** plan
* Your instance's `{tenant}` value. See [Instance URLs](https://docs.superblocks.com/enterprise/instance-urls.md)

## Set up Okta

Set up single sign-on for Okta by creating either a custom **SAML** or **OIDC** application. For full details, see Okta's guides for how to:

* [Create SAML app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm)
* [Create OIDC app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)

For the fastest setup,&#x20;
[create an OIDC integration](#create-an-oidc-integration).

If you plan on using SCIM for user provisioning and group management, we recommend&#x20;
[creating a SAML integration](#create-a-saml-integration). Learn more
about [
Managing users and groups with SCIM
](https://docs.superblocks.com/admin/org-administration/auth/scim.md).

### Create an OIDC integration

1. Log in to Okta and go to the **Admin Console**

2. Navigate to **Applications** → **Applications**

3. Click **Create App Integration**

4. Select **OIDC - OpenID Connect** as the **Sign-on method**

5. Select **Web Application** as the **Application type** and click **Next**

6. Configure the following settings for your application

   <table>
     <tr>
       <th>Name</th>

       <td>
         **Superblocks**, or a custom name you want users to see on
         their application dashboard.
       </td>
     </tr>

     <tr>
       <th>Grant type</th>

       <td>
         **Authorization Code** (selected by default),&#x20;
         **Refresh Token**, and **Implicit (hybrid)**
       </td>
     </tr>

     <tr>
       <th>Sign-in redirect URIs</th>

       <td>
         `https://login.superblocks.com/login/callback`
       </td>
     </tr>

     <tr>
       <th>Sign-out redirect URIs</th>

       <td>
         `https://{tenant}.superblocks.com/logout`
       </td>
     </tr>

     <tr>
       <th>Assignments</th>
       <td>Your desired settings for who can access Superblocks.</td>
     </tr>
   </table>

7. Click **Save**. You'll be brought to the **General** tab of your new application.

8. [Allow the `offline_access` scope](#allow-the-offline_access-scope)

9. **(Optional)** To enable IdP-initiated login, so users can open Superblocks from the tile on their Okta dashboard, go to the **General Settings** section, click **Edit**, and configure the following **Login** settings. Skip this step if users will only sign in from Superblocks.

   <table>
     <tr>
       <th>Login initiated by</th>
       <td>Either Okta or App</td>
     </tr>

     <tr>
       <th>Application visibility</th>
       <td>Display application icon to users</td>
     </tr>

     <tr>
       <th>Login flow</th>
       <td>Redirect to app to initiate login (OIDC Compliant)</td>
     </tr>

     <tr>
       <th>Initiate login URI</th>

       <td>
         `https://{tenant}.superblocks.com?connection=<CompanyName>-OpenID`
       </td>
     </tr>
   </table>

   Replace `<CompanyName>` with your company's name. Remove all spaces and
   special characters from the name. If your company name is multiple words,
   capitalize the first letter of each word. For example, the company River
   Bank Technologies would become `RiverBankTechnologies`

10. If you changed the **Login** settings, click **Save**. Then continue to find out [what info to send to Superblocks](#oidc-application).

#### Allow the `offline_access` scope

Superblocks requests the `offline_access` scope so that Okta issues a refresh token at login. Superblocks uses it to get a new Okta token when the one from login expires, so users don't have to log out and back in.

The **Refresh Token** grant type and the `offline_access` scope are required if you use the [On-Behalf-Of Token Exchange](https://docs.superblocks.com/integrations/auth/oauth-20.md#on-behalf-of-token-exchange) or **IdP Token Passthrough** auth methods in any integration.

How you allow `offline_access` depends on which Okta authorization server issues tokens for Superblocks.

* **Org authorization server** (the default for this setup, with endpoints under `https://{yourOktaDomain}/oauth2/v1/`): `offline_access` is allowed once the **Refresh Token** grant type is enabled. No other changes are needed.
* **Custom authorization server** (for example, `https://{yourOktaDomain}/oauth2/default`):
  1. Go to **Security** → **API** → **Authorization Servers** and open the authorization server
  2. On the **Scopes** tab, confirm the `offline_access` scope exists. It's a reserved scope that Okta creates by default, so restore it if it has been deleted.
  3. On the **Access Policies** tab, open the policy assigned to your Superblocks application and edit its rule
  4. Under **Scopes requested**, select **Any scopes**, or select **The following scopes** and include `offline_access` along with `openid`, `profile`, and `email`
  5. Click **Update rule**

### Create a SAML integration

1. Log in to Okta and go to the **Admin Console**

2. Navigate to **Applications** → **Applications**

3. Click **Create App Integration**

4. Select **SAML 2.0** as the **Sign-on method**

5. Provide the general information for the integration. **(Optional)** To enable IdP-initiated login, so users can open Superblocks from the tile on their Okta dashboard, leave **Do not display application icon to users** unchecked. Click **Next**

6. Enter the following information into **SAML Settings** → **General**

   <table>
     <tr>
       <th>Single sign-on URL</th>

       <td>
         [https://login.superblocks.com/login/callback?connection=](https://login.superblocks.com/login/callback?connection=)`<CompanyName>-SAML`
       </td>
     </tr>

     <tr>
       <th>Audience URI</th>

       <td>
         `urn:auth0:superblocks-prod:<CompanyName>-SAML`
       </td>
     </tr>

     <tr>
       <th>Name ID format</th>
       <td>EmailAddress</td>
     </tr>

     <tr>
       <th>Application username</th>
       <td>Email</td>
     </tr>
   </table>

   Replace `<CompanyName>` with your company's name. Remove
   all spaces and special characters from the name. If your company name is
   multiple words, capitalize the first letter of each word.

   For example, the company River Bank Technologies would become `RiverBankTechnologies`

7. Configure the follow attributes in **SAML Settings** → **Attribute Statements**

   | Name | Name format | Value |
   | - | - | - |
   | email | Unspecified | user.email |
   | givenname | Unspecified | user.firstName |
   | surname | Unspecified | user.lastName |

8. Click **Next** and fill out the Okta feedback form, then click **Finish**.

9. You'll be brought to the **Sign on** tab of your new application. Click **View Setup Instructions** and continue to the next section to learn [what info to send to Superblocks](#saml-application).

## Send IDP info to Superblocks

### OIDC application

Send the following information to [support@superblocks.com](mailto:support@superblocks.com). On Cloud-Prem, send it to your Superblocks deployment team instead.

<table>
  <tr>
    <th>Client ID</th>

    <td>
      The public identifier for your client located on the&#x20;
      **General** tab of your application.
    </td>
  </tr>

  <tr>
    <th>Client Secret</th>

    <td>
      The **secret** value shows in the&#x20;
      **CLIENT SECRETS** section.\
      \


      Note: we recommend using a secure transfer mechanism such as [https://onetimesecret.com](https://onetimesecret.com) or similar to send the secret.
    </td>
  </tr>

  <tr>
    <th>Okta domain</th>

    <td>
      Your company's Okta domain. You can find this by clicking your username in
      the upper-right corner of the Admin Console. Learn more about how to&#x20;
      [Find your Okta domain](https://developer.okta.com/docs/guides/find-your-domain/main/).
    </td>
  </tr>

  <tr>
    <th>Domains</th>

    <td>
      A list of domain and domain aliases your employees should be able to use
      when logging into Superblocks.
    </td>
  </tr>
</table>

### SAML application

Send the following information to [support@superblocks.com](mailto:support@superblocks.com). On Cloud-Prem, send it to your Superblocks deployment team instead.

<table>
  <tr>
    <th>Sign In URL</th>

    <td>
      The **Identity Provider Single Sign-On URL** in the Okta
      setup instructions.
    </td>
  </tr>

  <tr>
    <th>X509 Signing Certificate</th>
    <td>The certificate downloaded from the setup instructions.</td>
  </tr>

  <tr>
    <th>IdP-initiated login (optional)</th>

    <td>
      Only if you want users to open Superblocks from the tile on their Okta
      dashboard: let us know, and Superblocks enables IdP-initiated login for
      your connection so the tile signs users in to your Superblocks instance.
    </td>
  </tr>

  <tr>
    <th>Metadata URL (optional)</th>

    <td>
      Optionally, send us the **Metadata URL** shown on the&#x20;
      **Sign on** tab of your application.
    </td>
  </tr>

  <tr>
    <th>Domains</th>

    <td>
      A list of domain and domain aliases your employees should be able to use
      when logging into Superblocks.
    </td>
  </tr>
</table>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.