Configuring and Using Single Sign-On

Configuring the Identity Provider (IDP) will be completed using OpenID Connect (OIDC). OIDC is an open authentication protocol that permits individuals to use single sign-on (SSO) to access relying party sites using OpenID Providers (OPs) like email providers for companies or institutions.

Table of contents

Configuring SSO in Data Refinery Workbench

Use the following steps to create a SSO configuration in Data Refinery Workbench and integrate with identity providers.

Creating a New Configuration in Data Refinery Workbench

There are four parameters that need to be stored as variables for OIDC; these are ProviderName, ProviderEndpoint, ClientID, and ClientSecret. ProviderName and ProviderEndpoint can be retrieved from the API after creation in the system.

To call the API to add a configuration to Data Refinery Workbench, use the following POST request.

curl -X 'POST' \
  'https://example.workbench.kingland-data-refinery.com/api/sso/oidc' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_token_here' \
  -d '{
  "clientID": "",
  "clientSecret": "",
  "providerEndpoint": "kingland.com",
  "providerName": "test",
}'

The ClientID and ClientSecret will be left blank during the initial POST call. They will be populated in Setting Up an Application in an Identity Provider.

Moreover, this POST request will return a response that looks like the following:

{
  "ID": 1,
  "createdAt": "2023-10-02T17:57:54.045520221Z",
  "updatedAt": "2023-10-02T17:57:54.045520221Z",
  "deletedAt": null,
  "providerName": "test",
  "providerEndpoint": "kingland.com",
  "redirectURL": "kingland.com"
}

Setting Up an Application in an Identity Provider

The following procedure will explain basic steps on how to set up an application in an IDP and provide useful tips.

  1. In the selected IDP, locate the New Application Registration Form.

    Note. Depending on the IDP, proper names of the following may slightly differ. Refer to the IDP’s manual on how to set up a new web application for more precise instructions.

  2. Reference the following configuration table to fill out the new application form, if needed.

    Configuration Option Value Notes
    Client Authentication Type Client Secret This uses Client ID + secret key instead of public & private key pair
    Application Type Web  
    Grant Type Authorization Code  
    Sign-in redirect URIs https://{full URL}/sso/oidc/{ID}/callback The value is the Data Refinery Workbench endpoint used to handle SSO call back. Replace {ID} with the configuration ID assigned by Data Refinery Workbench.
    Login initiated by “Either Okta or App” This allows the user to click on a button from Okta and get logged in (like MS myApps)
    Sign-in Initialization URIs https://{full URL}/sso/oidc/{ID}/init The value is the Data Refinery Workbench endpoint used to initialize SSO process. Replace {ID} with the configuration ID assigned by Data Refinery Workbench.
    Login flow OIDC Compliant  
  3. Submit the form once the fields are completed.
  4. When the application is set up with an IDP, the ClientID and ClientSecret should be given. Save that information to update the configuration in Data Refinery Workbench.

Updating the Configuration in Data Refinery Workbench

Once the ClientID and ClientSecret are generated, update the configuration to include these items.

To update, use the following PUT command:

curl -X 'PUT' \
  'https://example.workbench.kingland-data-refinery.com/api/sso/oidc' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_token_here' \
  -d '{
  "ID": 1,
  "clientID": "abcd",
  "clientSecret": "1234",
  "providerEndpoint": "kingland.com",
  "providerName": "test",
  
}'

This will return a response that looks like the following:

{
  "ID": 1,
  "createdAt": "2023-10-02T17:57:54.045520221Z",
  "updatedAt": "2023-10-02T17:57:54.045520221Z",
  "deletedAt": null,
  "providerName": "test",
  "providerEndpoint": "kingland.com",
  "redirectURL": "kingland.com"
  
}

The ClientID and ClientSecret are considered sensitive data. This means the data is stored but not returned in the response to protect the information.

To change, delete, or view existing configurations, refer to the DR Workbench API Reference.

Automatic User Creation and Synchronization

A new Data Refinery Workbench User is created when a user logs in for the first time via SSO, or when their information has changed in the identity provider. This section covers these creation and synchronization processes.

User Attributes

When a user logs in for the first time via SSO, a new Data Refinery Workbench user is created with information provided by the identity provider, including username and email.

When a user logs in after their information has changed in the identity provider, Data Refinery Workbench will attempt to synchronize the changes as well. Currently, the only mutable field is the user’s email.

Caution. SSO users are identified by their usernames. Changing a user’s username in the identity provider will lead to unpredictable behaviors.

Passwords

An SSO user, by default, cannot log in via username and password.

Incompatible Fields

When signing in through SSO, Data Refinery Workbench aims to provide a seamless user experience. As part of this process, information provided by the SSO might undergo some adjustments to ensure it adheres to the system’s standards.

  • Usernames: usernames are normalized following the rules listed below.
  • Emails: email addresses must be in valid email address format. Invalid email addresses are ignored by Data Refinery Workbench when creating or updating SSO users.

Username Normalization From SSO

This section outlines the normalization process for usernames. See examples of normalization below.

Note. Username normalization may lead to username clashes. Administrators should ensure usernames stored in the identity providers adhere to Data Refinery Workbench’s username constraints when possible.

Normalization Rules

  1. Lowercase Conversion: All characters in the username will be converted to lowercase.
  2. First Character Validation: The username must start with a letter (a-z) or an underscore (_). If the first character is invalid, it will be replaced by an underscore (_).
  3. Subsequent Characters Validation: After the first character, usernames can consist of:
    • Letters (a-z)
    • Digits (0-9)
    • Underscores (_)
    • Dollar signs ($)

    Any other characters will be removed from the username.

  4. Length Limit: The username cannot exceed 127 characters. If it does, it will be truncated to fit within this limit.
  5. Reserved Keywords: If the entire username matches any reserved keyword, the username will be transformed into a hash for uniqueness and security. The complete list of reserved keywords can be found here.

What to Expect

  • If your SSO username is ADMIN, it will be normalized to admin.
  • If your SSO username is Admin1$ter, it will be normalized to admin1$ter.
  • If your SSO username is 1User@Name, it will be normalized to _username.
  • If your SSO username matches a reserved keyword, e.g., “system”, it will be transformed into a unique hash.

Troubleshooting

Below are common error messages users may encounter when logging in using SSO.

Error 400 - “Username from IDP is un-normalizable”

This may happen when the username returned from the IDP is blank, or only contains invalid characters. See Normalization Rules for more information.

To resolve this issue: verify the IDP is correctly configured to return username claims, and verify usernames are compatible with the normalization rules.

Error 500 - “SSO user Sync failed”

This could indicate a transitory issue in the application server. Please try again after a short delay.

If this error persists, the SSO user could have a duplicate email with an existing user. Verify the SSO user’s email isn’t shared by another user with a different username. Changing the existing user’s email to a unique value and retrying SSO should resolve the issue.

Error 500 - Other messages

This could indicate a transitory issue in the application server. Please try again after a short delay. If the issue persists, please reach out to Kingland Support.

Copyright © 2025 Kingland Systems LLC