SAML SSO with Okta

Set up SSO for your Ninox server (Private Cloud or On-Premises) using SAML and a third-party app like Okta

 SSO is an Enterprise feature available on request that requires a valid license purchased from Ninox or a certified partner.

 We do not require you use Okta to set up a single sign-on with SAML.

However, we chose Okta to demonstrate a potential SAML setup with Ninox. Your setup may vary based on which third-party app you use.

What's new?

Merge SSO roles in Okta and Ninox

As of Ninox 3.6.9, you can assign roles to people or groups in your SAML integration and then merge existing roles in your Ninox server with the ones set up in a third-party app, like Okta.

Create a new SAML integration

Step 1: Log in and create app integration

1. Log in to Okta.

2. Click Applications in the left sidebar and select Applications (1) from the dropdown menu.

3. Click the Create App Integration (2) button.

Step 2: Set up sign-up method

In the Create a new app integration pop-up window, select SAML 2.0 (1) as Sign-in method. Click the Next (2) button to proceed.

Step 3: Create SAML integration

1. On the Create SAML Integration page, in the General Settings tab, enter a name in the App name field. In this example it's Ninox SAML (1).

2. Click the Next (2) button to proceed.

Step 4: Configure SAML integration

In the Configure SAML tab, fill in the fields listed below.

1. Single sign on URL: The URL is a combination of of the protocol https://, your Ninox server domain name (in this example, it's anastasiya.ninoxdb.de), and the path /ums/saml/consume, resulting in something like https://anastasiya.ninoxdb.de/ums/saml/consume (1). The domain name needs to be replaced with the domain name of your Ninox server.

2. Audience URI (SP Entity ID): ninox-saml (2)

3. Default RelayState: WEB (3)

4. Name ID format: EmailAddress (4)

5. Application username: Email (5)

6. Update application username on: Create and update (6) (default setting)

7. Group Attribute Statements (optional): Enter a name, e.g., roles and set the Name format to Basic (7). Set the filter to Matches regex and enter .* (8).

2. For a preview of the SAML configuration, click the Preview the SAML assertion (1) button.

3. A new browser tab opens and shows a preview similar to the one below.

Tip: Remember the audience and attribute name

 Remember the audience ninox-saml (1) and the attribute name roles (2)—we'll need these again in your Ninox server setup.

4. Click the Next (1) button to proceed.

Step 5: Finish setup in Okta

1. In the Feedback tab, respond to Are you a customer or partner? by selecting I’m an Okta customer adding an internal app (1).

2. Tick the box This is an internal app that we have created (2).

3. Click the Finish (3) button to confirm.

Assign users to SAML integration

 Make sure people have access to Ninox, either as members (paid by the owner) or as contributors (paid by themselves). If users cannot log in to Ninox, they won't be able to log in to your Ninox server using SSO.

Follow the steps below to either assign individual users or whole groups to your SAML integration.

Assign to people

1. On the new application page, click the Assignments (1) tab.

2. Click the Assign dropdown button, then select Assign to People (2).

3. A pop-up window opens. Select a user from the list to individually assign them to your app, then click Assign (1).

4. In a new new pop-up window, click the Save and Go Back (1) button to return to the previous view.

5. In the previous pop-up window, the label Assigned (1) appears next to the selected user. Click the Done (2) button to close the pop-up.

External resources

  Assign applications to users | Okta

Assign to groups

1. Back on the application page, click the Assign dropdown button, then select Assign to Groups (1).

2. A pop-up window opens. Select a group from the list to individually assign it to your app, then click Assign (1).

3. The label Assigned (1) appears next to the selected group. Click the Done (2) button to return to the previous view.

External resources

  Manually assign people to a group | Okta

Retrieve SAML credentials from Okta

Step 1: View SAML setup instructions

1. On the new application page, in the Sign On tab, click the View SAML setup instructions (1) button.

2. A new browser tab opens to show SAML setup instructions.

Step 2: Copy SAML setup instructions

1. Copy the Identity Provider Single Sign-On URL (1). This value corresponds to the following field in your Ninox server setup: Single Sign on URL (SSO URL). Refer to https://docs.ninox.com/en/private-cloud-on-premises/single-sign-on-sso/saml-single-sign-on-with-okta#step-2-transfer-saml-credentials

2. Copy the Identity Provider Issuer (2). This value corresponds to the following field in your Ninox server setup: Issuer. Refer to https://docs.ninox.com/en/private-cloud-on-premises/single-sign-on-sso/saml-single-sign-on-with-okta#step-2-transfer-saml-credentials

3. Click the Download certificate (1) button. A file named okta.cert is saved to your computer. This file corresponds to the following button in your Ninox server setup: IDP Certificate.

Finish SAML setup in your Ninox server setup (Private Cloud or On-Premises)

Step 1: Access Ninox server configuration

1. Log in to your Ninox Private Cloud or Ninox On-Premises as root user. In the example below we use a Private Cloud (1).

2. Click the gear icon (2) in the top-right corner to access the global settings.

3. From the dropdown menu, select Server Administration (3).

4. A new page opens. Click the Configuration (1) tab.

Tip: Copy the team ID to auto-assign users to that workspace

 To automatically add users to a specific workspace (team), copy its team ID (1). In this example we use the same Private Cloud as mentioned in the steps above.

Step 2: Transfer SAML credentials

1. On the Server Configuration page, scroll down to Authentication Strategy, then select the SAML V2 (1) tab. Fill in the fields listed below and upload the certificate file from Okta.

   1. Single Sign on URL (SSO URL): copy-paste the Identity Provider Single Sign-on URL, in this example https://dev-78357175.okta.com/app/dev-78357175_ninoxsaml_1/exk5s7f2zbbh9HGTh5d7/sso/saml (2)

   2. Issuer: copy-paste the Identity Provider Issuer, in this example http://www.okta.com/exk5s7f2zbbh9HGTh5d7(3)

   3. IDP Certificate: upload the .cert file (4)

   4. Audience (5): ninox-saml (5)

   5. Session Duration (in days): 2 (6)

   6. Auto Assign To Team: copy-paste the team ID, in this example p75h1me5ngr0grptq (7)

   7. Property name of group attributes in SAML assertion: copy-paste the attribute name, in this exampleroles(8)

   8. Roles To Be Excluded For Mapping: optional, in this example Everyone (9)

   9. Role mapping strategy: select Merge SAML and Ninox roles (10)

   10. Click the Setup SAML and Restart button (11) to confirm.

Check SSO login

If the configuration was successful, the login with SSO will look similar to the one shown in the GIF below. In this example we use the same Private Cloud as above.