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 Okta and Skuid for this process:

  • First, we’ll create an Okta app integration with placeholder data so its IdP metadata can be retrieved at a URL.
  • Next, we’ll create an identity provider connection in Skuid with that IdP metadata URL.
  • Finally, we’ll then return to Okta to update its app integration settings with Skuid’s ACS URL and audience URI.

Connecting Okta and Skuid NLX

In Okta

Creating a service provider entry to retrieve IdP metadata

First, configure settings in Okta to obtain its IdP metadata file:

  1. Within the Admin dashboard, 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. In the Configure SAML step you’ll need to enter temporary data to access Okta’s IdP metadata file that’ll be used to configure Skuid’s IdP connection. You’ll update these values later when Skuid generates the proper URLs, but for now use placeholder values:

    • Single Sign-On URL: https://placeholder.com
    • Audience URI (SP Entity ID): https://placeholder.com

  4. Click Next.

  5. Fill out the Feedback tab as appropriate and click Finish.

  6. On the newly created app integration’s configuration page, within the Sign On tab, find the SAML Signing Certificates section.

  7. In the SHA-2 column, click Actions > View IdP metadata.

  8. Copy the URL that points to the 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.

In Skuid

Creating an IdP connection to retrieve service provider metadata

With the IdP metadata now available at a URL, point Skuid to that URL to create the IdP connection:

  1. Navigate to Settings > Single Sign-on.
  2. Click Create or Create if an IdP connection already exists.
  3. Select Import identity provider metadata file - from specified URL.
  4. Paste the IdP metadata URL copied earlier into the field.
  5. Click Import.

A new IdP connection is created based on the metadata provided by Okta, its name similar to Okta_1231234123456. You can now retrieve the Skuid-generated audience URI and ACS URL to use in Okta:

  1. Click the identity provider connection (or click dots-vertical More Options > Configure) to navigate to the connection’s details.
  2. Copy the URLs in the following fields:
    • Assertion Consumer Service (ACS) URL
    • Audience URI / Service Provider Entity ID / Metadata URL

Both of these URLs are necessary for the Okta configuration in the next section.

Update the identity location

Using Okta’s metadata file sets Skuid’s IdP connection to look for a federation ID within the The name identifier element of the subject statement by default.

Okta sends a user’s username through this name identifier element. This is a hardcoded value in Okta, and it may represent an email, a first name/last name, or other format.

Because of this, it’s typically more useful to use an attribute element instead.

To update the IdP connection to look for an attribute element:

  1. Return to the Okta IdP connection detail screen.
  2. In the Identity location pane, set the following properties:
    • SAML Identity is in: An attribute element
    • Name Identifier Format: Unspecified
    • SAML Identity contains Skuid User’s: Select the Skuid user attribute to verify a user with. Federation ID is typically recommended.

Note

It’s also possible to leave the location as is and adjust the SAML Identity contains Skuid User’s property to the expected format, for example Email Address. The most important thing is that Skuid knows where to look for a user’s identity in the Okta assertion.

In Okta

Updating Okta’s settings to point to Skuid

Return to the Application settings for the app you configured in the first section.

  1. In the General tab within the SAML Settings pane, click Edit.
  2. Click Next to proceed to the Configure SAML step.
  3. Update your SAML settings:
    • 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.

User attributes and provisioning

Once the connection between Okta and Skuid is finished, you must configure Okta attribute statements in a way that Skuid can parse when users log in. This information is used to match an Okta user to the appropriate Skuid user record. If user provisioning is enabled, then this information determines which attributes are used to create a Skuid user.

In Okta

  1. Navigate to Applications > Applications.

  2. Click your Skuid NLX app.

  3. Click the General tab.

  4. Click Edit within the SAML Settings pane.

  5. Click Next to open the Configure SAML settings.

  6. (Optional) Set the Application username field to the appropriate value to determine the default username when adding users. You may use an Okta expression when this field is set to Custom.

  7. 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}

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

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

Adding users and assigning the Skuid app integration to users

Okta can function as the system of record for your users after these but some final steps must be completed in Okta:

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:

  • Ensure the identity location in Skuid’s IdP connection matches Okta’s settings. If necessary, update the identity location in the IdP connection details.

  • Ensure that Okta is passing the necessary attributes to Skuid.

    expects properly set Okta attribute statements. These are used by Skuid to map which user is which.

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