IdP Example: Okta

This tutorial describes the process for configuring Okta and Skuid NLX for single sign-on using the SAML 2.0 protocol. It requires a working knowledge of SSO in Skuid and Okta.

We’ll need to navigate back and forth between Skuid and Okta for this process:

  • First, create an IdP connection in Skuid to generate an ACS URL and service provider entity ID
  • Next, create a SAML application in Okta using those values and configure the SAML attributes it sends
  • Finally, return to Skuid to create an identity mapping so users can be matched via information in the SAML assertion

Creating an IdP connection in Skuid

In your Skuid NLX site:

  1. Navigate to Settings > Single Sign-on.
  2. Click Create identity provider or, if some IdP connections already exist, click Create in the Identity Providers section.
  3. Give the IdP connection a name, like Okta.
  4. Confirm the name by clicking Create.
  5. Copy the ACS URL and service provider entity ID values for Okta.

Creating an Okta application and configuring SAML attributes

Creating a service provider entry to retrieve IdP metadata

In your Okta Admin dashboard:

  1. Navigate to Applications > Applications.
  2. Click Create App Integration.
  3. Select SAML 2.0 as your sign on method.
  4. Click Next.

Now, begin configuring the SAML integration app settings:

  1. Fill out the App name, App logo, and App visibility. Make sure to name the app something recognizable, like “Skuid NLX - Company Wide.”
  2. Click Next.
  3. Update your SAML settings to point to the appropriate Skuid values:
    • Single Sign-On URL: Insert the Assertion Consumer Service (ACS) URL from Skuid NLX.
      • Check Use this for Recipient URL and Destination URL
    • Audience URI (SP Entity ID): Insert the Audience URI / Service Provider Entity ID / Metadata URL from Skuid NLX.
  4. Click Next and then Finish to save these changes.
  5. Fill out the Feedback tab as appropriate and click Finish.

Configuring user attributes

To facilitate user provisioning and ensure all relevant user attributes are passed from Okta to Skuid during a SAML assertion, we recommend configuring SAML attributes within your Okta application.

Configure these as needed for your organization following Okta’s documentation, or consider using the suggested attributes below:

  1. Navigate back to your application’s details within Applications > Applications.

  2. Click the General tab.

  3. Click Edit within the SAML Settings pane.

  4. Click Next to open the Configure SAML settings.

  5. Set the Application username to send the user data you’d expect within the subject name identifier field of the SAML assertion.

    For most Skuid implementations, using email or a custom federation ID is recommended. For custom federation ID formats, you can use an Okta expression when this field is set to Custom.

  6. Update your Attribute Statements setting to contain the following:

    Note

    You may leave the Name format as Unspecified for all of the below.

    Name Value
    User.FirstName user.firstName
    User.LastName user.lastName
    User.Email user.email
    User.Username

    Use an Okta expression that matches your standardized username format. One common formula concatenates first and last names with a dot between the two:

    ${user.firstName}.${user.lastName}
    User.FederationId

    Use an Okta expression that matches your standardized federation ID format. One common formula concatenates first and last names with a dot between the two:

    ${user.firstName}.${user.lastName}

  7. Click Next and then click Finish to save your settings.

Okta is now configured to send the proper attributes for Skuid.

Retrieving the metadata file for Skuid

With the configuration complete on the Okta side, a metadata file becomes available. This file provides the rest of the information Skuid needs for the IdP connection.

  1. Navigate back to your application’s details within Applications > Applications.

  2. Click the Sign On tab, and find the SAML Signing Certificates section.

  3. In the SHA-2 row, click Actions > View IdP metadata.

  4. Copy the URL that points to this metadata XML. It should look similar to https://<Okta Domain>/app/<App integration Id>/sso/saml/metadata

    Note

    It’s also possible to save this XML file and upload to Skuid, however the instructions below use the URL.

Complete IdP setup and identity mapping

Updating the IdP connection with metadata

In your Skuid NLX site:

  1. Navigate back to your IdP connection’s details within Settings > Single sign-on.
  2. In the Identity provider details section, click Add details.
  3. Select Import metadata file from specified URL.
  4. Paste the IdP metadata URL copied earlier into the field.
  5. Click Import.

Add identity mapping

Once SAML metadata is loaded, you must create an identity mapping so Skuid can identify users based on the information sent by Okta.

This information should map to the user attributes you configured earlier within the settings in the General section in SAML settings pane

Using a subject name identifier

If you set the Application username in Okta to a format available to match within Skuid (like email or federation ID), you can use the subject name identifier.

Note

This mapping example assumes you’ve set the Okta application username to equal a user’s email. If this isn’t the case, replace email with the attribute you chose in Okta.

  1. In the Identity mapping section, click Add mapping.

  2. Configure the mapping:

    [ Subject name identifier ] with a format of [ Unspecified ] matches Skuid user [ Email ]

  3. Indicate whether or not the match is Case-sensitive.

  4. Click Save.

Using a SAML attribute

You can also match users based on a particular SAML attribute.

Note

This mapping example assumes you’re using the user email attribute configured in the the SAML attributes instructions above.

  1. In the Identity mapping section, click Add mapping.

  2. Configure the mapping:

    [ SAML attribute ] [ User.Email ] matches Skuid user [ Email ]

  3. Indicate whether or not the match is Case-sensitive.

  4. Click Save.

Make the IdP available as a login option

With all setup options complete, enable the Available as login option toggle and then click Save to display the newly created IdP connection as a login option to your users.

Troubleshooting

SAML Login error: User not found

This error indicates that the attributes sent by Okta did not match an existing Skuid user and user provisioning is not enabled.

First ensure your identity location and attribute settings are correct:

If this error occurred and you intended for a new user to be provisioned, go the IdP connection details, click the Provisioning tab, and enable Just-in-time user provisioning.