# Set up SSO using SAML All Cerby users are able to configure a default Identity Provider (IdP) such as Okta to leverage the Single Sign-On (SSO) authentication feature to securely authenticate to Cerby using a single set of credentials. This article describes how to configure Okta as the primary IdP to enable SSO with the Cerby application using a Security Assertion Markup Language (SAML) integration. *** ## Supported features The following are the supported features of configuring SSO between Cerby and Okta with SAML: * **Service provider-initiated authentication flow.** This authentication flow occurs when users attempt to log in to the application from Cerby. * **Automatic user account creation in Cerby.** This provisioning flow in Cerby occurs automatically on the initial SSO. *** ## Requirements The following are the requirements to configure SSO between Cerby and Okta: * An Okta tenant * A user account in Okta with privileges to manage an app integration in your Okta tenant * A user account in Cerby with the **Workspace Owner** role * An invitation sent from Cerby Support via email to create a workspace {% hint style="warning" %} **IMPORTANT:** If you have not received an invitation, send an email to with your request. {% endhint %} * Users and groups created beforehand in your Okta directory. Follow the corresponding instructions in the Okta Help Center to manage users and groups: * [Manage users](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-people.htm) * [Manage groups](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-groups-main.htm) *** ## Configuring SSO between Cerby and Okta with SAML To configure SSO between Cerby and Okta with a SAML integration, you must complete four main steps: 1. [Set up a workspace in Cerby](#id-1.-set-up-a-workspace-in-cerby) 2. [Add the SAML-based app to Okta](#id-2.-add-the-saml-based-app-to-okta) 3. [Assign users and groups to the Cerby app](#id-3.-assign-users-and-groups-to-the-cerby-app) 4. [Retrieve the metadata information from Okta](#id-4.-retrieve-the-metadata-information-from-okta) {% hint style="info" %} **NOTE:** Depending on the use case, you may be redirected to Okta for authentication if a session has not been established. {% endhint %} The following sections describe each step. ### 1. Set up a workspace in Cerby To set up a workspace in Cerby, complete the following steps: 1. Click the **Create your Workspace** button from the invitation email you received from Cerby. The **Welcome to Cerby** page is displayed. 2. Click the **Set up Okta** button, as shown in **Figure 1.** The **Let's create your workspace** page is displayed.

Figure 1. Welcome to Cerby Page

3. Enter the name of your workspace in the **Workspace name** field, as shown in **Figure 2**.

Figure 2. Let's Create Your Workspace Page

**NOTE:** Remember the workspace name that you have entered. You need it later. 4. Click the **Create Workspace** button. The **Configure SSO through Okta SAML App** page is displayed with instructions to configure the Cerby app in your Okta tenant. {% hint style="warning" %} **IMPORTANT:** Keep the **Configure SSO through Okta SAML App** page open because it contains the required values that you must provide to Okta and Cerby to complete the configuration. {% endhint %} The next step is [2. Add the SAML-based app to Okta](#id-2.-add-the-saml-based-app-to-okta). *** ### 2. Add the SAML-based app to Okta To add the SAML-based app to Okta, complete the following steps: 1. Log in to the [Okta Admin Console](https://developer.okta.com/login/) of your organization. 2. Select the **Applications** option from the **Applications** drop-down list located in the left navigation drawer. The **Applications** page is displayed, as shown in **Figure 3**.

Figure 3. Applications Page in the Okta Admin Console

3. Search for the Cerby app by performing the following actions: 1. Click the **Browse App Catalog** button. The **Browse App Integration Catalog** page is displayed. 2. Enter **Cerby** in the search bar above the **All Integrations** section. A list of apps is displayed below the search bar. 3. Select the **Cerby** option from the list, as shown in **Figure 4**. The **Cerby Overview** page is displayed.

Figure 4. Apps List in the Browse App Integration Catalog Page

4. Click the **Add Integration** button. The **Add Cerby** page is displayed with the **General Settings** tab activated. 4. Enter the name of the app in the **Application label** field of the **General Settings** tab, as shown in **Figure 5**. For example, you can enter **Cerby**.

Figure 5. General Settings Tab in the Add Cerby Page

5. Click the **Next** button. The **Sign-On Options** tab is activated. 6. Select the **SAML 2.0** option located in the **Sign on methods** section. 7. Enter the corresponding values in the **SubDomain** and **Pool ID** fields of the **Advanced Sign-on Settings** section, as shown in **Figure 6**. These values are located in the **Configure SSO through Okta SAML App** page that you left open in Cerby. **TIP:** You can use the **Copy** button in the **Configure SSO through Okta SAML App** page in Cerby to copy the values to the clipboard.

Figure 6. Advanced Sign-On Settings Section in the Sign-On Options Tab

8. Click the **Done** button located at the bottom of the **Add Cerby** page. The **Cerby** app page is displayed. The next step is [3. Assign users and groups to the Cerby app](#id-3.-assign-users-and-groups-to-the-cerby-app). *** ### 3. Assign users and groups to the Cerby app To assign the users and groups you already created to the Cerby app integration, complete the following steps: {% hint style="warning" %} **IMPORTANT:** Users must have a profile created in Okta and groups must be configured before adding them to the Cerby app. {% endhint %} 1. Activate the **Assignments** tab of the **Cerby** app page, as shown in **Figure 7**. The users of your Okta directory are displayed in a table.

Figure 7. Assignments Tab

2. Assign individually the users from your directory to the Cerby app by performing the following steps: 1. Select the **Assign to People** option from the **Assign** drop-down list. The **Assign Cerby to People** dialog box is displayed. 2. Click the **Assign** button of the user you want to add to the Cerby app, as shown in **Figure 8**. A dialog box is displayed to assign a user name to the user.

Figure 8. Assign Cerby to People Dialog Box

3. Enter the user name in the **User Name** field. **IMPORTANT:** Make sure that the user name is a valid email address. 4. Click the **Save and Go Back** button. The dialog box closes. 5. Click the **Done** button. The **Assign Cerby to People** dialog box closes. 3. Assign the groups you have already created to the Cerby app by performing the following steps: 1. Select the **Assign to Groups** option from the **Assign** drop-down list. The **Assign Cerby to Groups** dialog box is displayed with a list of groups, as shown in **Figure 9**.

Figure 9. Assign Cerby to Groups Dialog Box

2. Click the **Assign** button for each group you want to assign the Cerby app integration to. The **Assign** button changes to an **Assigned** status. 3. Click the **Done** button when you complete assigning groups. The dialog box closes. {% hint style="info" %} **TIP:** To verify the groups are successfully assigned to the Cerby app integration, click the **Groups** button from the **Filters** column of the table. The groups you assigned are displayed in the table. {% endhint %} The next step is [4. Retrieve the metadata information from Okta](#id-4.-retrieve-the-metadata-information-from-okta). *** ### 4. Retrieve the metadata information from Okta To retrieve the metadata information from Okta, complete the following steps: 1. Activate the **Sign On** tab on the **Cerby** app integration page in Okta. 2. Click the **Actions** drop-down list in the **SAML Signing Certificates** section. A drop-down list is displayed with the **View IdP metadata** and **Download certificate** options. 3. Right-click the **View IdP metadata** option. A context menu is displayed, as shown in **Figure 10**.

Figure 10. Context Menu for the View IdP metadata option

4. Select the **Copy Link Address** option from the context menu. 5. Paste the link address in the **Okta Identity Provider metadata** field of the **Configure SSO through Okta SAML App** page that you left open in Cerby, as shown in **Figure 11**. The link address must look like the following example: `https://**< OKTA_TENANT>**.okta.com/app/**< okta-generated-id>**/sso/saml/metadata`

Figure 11. Configure SSO Through Okta SAML App Page in Cerby

6. Select the **I have already assigned users or groups to the application** option. 7. Click the **Finish Configuration** button. A page is displayed with a message telling you that your workspace has been successfully created. 8. Click the **Login** button. Your new Cerby workspace is displayed. Now you are done. {% hint style="danger" %} **IMPORTANT:** Currently, after creating a workspace, you cannot change its name or update the IdP settings. {% endhint %} *** {% hint style="info" %} **NOTE 1:** Assigned users via group or individually can now log in to Cerby via SSO through the Cerby app integration displayed on their Okta dashboard. In Cerby, accounts are automatically created after the initial SSO login. {% endhint %} {% hint style="info" %} **NOTE 2:** The SAML-based integration leverages Okta only for authentication. To assign permissions for Cerby, users must do so directly in Cerby. {% endhint %} {% hint style="info" %} **NOTE 3:** This integration does not currently support IdP-initiated login from Okta. To log in to Cerby from an Okta dashboard, a bookmark app must be created. The bookmark app must point to your workspace, which would be **``**`.cerby.com`. For example, if your workspace name is **`cerby`**, the bookmark app should point to **`cerby.cerby.com`**. For more information on creating a bookmark in Okta, see the [How to Create a Bookmark App](https://support.okta.com/help/s/article/How-do-you-create-a-bookmark-app?language=en_US) article. {% endhint %} --- # 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://help.cerby.com/setup-and-admin/workspace-identity-federation/okta/configure-sso-between-cerby-and-okta-with-saml.md?ask= ``` 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.