Single Sign-On (SSO) Management

Overview

For applications that work with sensitive information, keeping that information secure is key. Having end-users use single sign-on (SSO) to access your application is a great solution. When setting up SSO, you can select the authentication provider for your Unqork application. Instead of Unqork needing to store the end-users' credentials, the SSO provider takes care of it. Using SSO also gives your end-user fewer sets of credentials to remember. Your end-user gets a seamless login experience, and you can trust your SSO provider to ensure the right people have access to your app.

The Single Sign-On (SSO) Management page makes it easy to add SSO configurations. From Single Sign-On (SSO) Management, you can easily add, preview, and manage SSO configurations in your environment, using the SSO dashboard.

You can set up SSO configurations for:

  • Express View access: For authentication into the front-end of an application in your environment.

  • Designer access: For authentication in your Unqork environment, known as Designer.

When adding your SSO configuration, you choose one of two protocols supported by Unqork: SAML (Security Assertion Markup Language) or OIDC (OpenID Connect).

TIP  SSO Management also supports hard-coding Application Roles. To specify Application Roles, use this format: <applicationId>:<roleName>. To specify multiple Application Roles, use a comma-separated list.

NOTE  In this article, you'll learn the basics of using the Single Sign-On (SSO) Management page. In the Related Resources section, you can find links to related articles, including provider-specific how-to guides and detailed articles about SAML and OIDC in Unqork.

What You'll Learn

In this article, you'll learn how to:

The SSO Dashboard

The SSO dashboard is where you add, review, and manage SSO configurations in your environment. You can have SSO configurations from different Identity Providers (IDPs) or OpenID Providers (OPs) configured in your environment. Each SSO configuration has a unique callback URL (SAML) or redirect URI (OIDC) that contains the SSO configuration's unique name.

Here’s an example of the dashboard with several SSO configurations:

The SSO dashboard has two tabs:

  • Express: From the Express tab, you can add and review your SSO configurations for Express View.

  • Designer: From the Designer tab, you can add and review your SSO configurations for Designer access.

Each tab has a similar dashboard, where you can gather some useful information at a glance, including:

Column Column Description

Name

The SSO configuration's name.

TIP  SSO configuration names are customizable labels you set when adding the SSO configuration.

Protocol

Which protocol the SSO configuration uses: SAML or OIDC.

Default Role

The default role for users who authenticate using the SSO configuration.

For Express SSO configurations, the default role is an Express role, defined in Express Role Administration. For Designer SSO configurations, the default role is a Creator (User) role, defined in Creator (User) Administration.

Actions

From the Manage drop-down, you can view, edit, preview, or delete an SSO configuration.

Adding an SSO Configuration for Express View

These instructions outline the basic steps to add an SSO configuration to the SSO dashboard. The individual steps and field values vary based on your SSO provider as well as whether you add a SAML or OIDC-based configuration. See the Related Resources section for further information.

1. At the top right of the Unqork Designer Platform, click the Settings drop-down.
2. Click Administration.
3. Under Environment, select Single Sign-On (SSO).
4. Click + New SSO.
5. Select Express. The New Express SSO configuration modal opens.
6. In the SSO Name field, enter a name for your SSO configuration.

NOTE  SSO configuration names must be unique.

7. Select a Default Role. The drop-down contains a list of all Express Roles defined in Express Role Administration.

NOTE  Leaving this empty defaults to a role with the lowest-level permissions.

8. Select a Default Group. The drop-down contains a list of all Express Groups defined in Express Group Administration.

NOTE  It's best practice to select a default group with the lowest-level permissions. Leaving this empty defaults the end-user to no group.

9. Click Next to move to the Configure Protocol tab.
10. Select a protocol: SAML or OIDC.
11. Complete the IdP Details, Configuration Details, and Advanced Settings as required.

NOTE  It is possible to have multiple IDP configurations for a single application.

TIP  See the Related Resources section for detailed articles covering what to enter in each field, including provider-specific how-to guides.

12. Click Next to move to the Attribute Mapping tab.
13. Complete the Attribute Mapping and User Management settings as required.

TIP  See the Unqork as a SAML Service Provider or OpenID Connect (OIDC) articles for detailed information about adding attribute mappings to a SAML or OIDC-based SSO configuration.

14. Click Create SSO.

Adding an SSO Configuration for Designer

These instructions outline the basic steps to add an SSO configuration to the SSO dashboard. The individual steps and field values vary based on your SSO provider as well as whether you add a SAML- or OIDC-based configuration. See theRelated Resources section for further information.

1. Click the Settings drop-down at the top right of the Unqork Designer Platform.
2. Click Administration.
3. Under Environment, select Single Sign-On (SSO).
4. Click + New SSO.
5. Select Designer. The New Designer SSO configuration modal opens.
6. Enter a name for your SSO configuration in the SSO Name field.

NOTE  SSO configuration names must be unique.

7. Select a Default Role. The drop-down contains a list of all Creator (User) Roles defined in Creator (User) Role Administration.

NOTE  Leaving this empty defaults to a role with the lowest-level permissions.

8. Click Next to move to the Configure Protocol tab.
9. Select a protocol: SAML or OIDC.
10. Complete the IdP Details, Configuration Details, and Advanced Settings as required.

TIP  See the Related Resources section for detailed articles covering what to enter in each field, including provider-specific how-to guides.

11. Click Next to move to the Attribute Mapping tab.
12. Complete the Attribute Mapping and User Management settings as required.

TIP  See the Unqork as a SAML Service Provider or OpenID Connect (OIDC) articles for detailed information about adding attribute mappings to a SAML or OIDC-based SSO configuration.

13. Click Create SSO.

Previewing an SSO Configuration

After adding an SSO configuration, you need to preview it to test that it works. From the SSO dashboard, you can preview the Unqork entrypoint and use a set of test credentials from your SSO provider to test the configuration.

NOTE  For SAML-based configurations, previewing your configuration only tests an SP-initiated flow. Remember to also test an IdP-initiated flow. Our provider-specific how-to guides have more information.

To preview an SSO configuration:

1. At the top right of the Unqork Designer Platform, click the Settings drop-down.
2. Click Administration.
3. Under Environment, select Single Sign-On (SSO).
4. Select the Express or Designer tab.
5. In the SSO dashboard, find the SSO configuration to preview.
6. Under the Actions column, click Manage.
7. From the Manage drop-down, select Preview. The Unqork entrypoint link opens in a new tab.

NOTE  You might need to preview your configuration in an Incognito window to properly test the configuration. In that case, right-click Preview and select Copy Link Address. Then, paste the link address in a new Incognito window.

8. Log in using your test credentials.

Viewing an SSO Configuration

After adding an SSO configuration, it's useful to review the configuration's details. For example, reviewing the attribute mappings.

To view an SSO configuration:

1. At the top right of the Unqork Designer Platform, click the Settings drop-down.
2. Click Administration.
3. Under Environment, select Single Sign-On (SSO).
4. Select the Express or Designer tab.
5. In the SSO dashboard, find the SSO configuration to view.
6. Under the Actions column, click Manage.
7. From the Manage drop-down, select Edit. The SSO configuration modal opens.
8. Review the settings in the Basic Information, Configure Protocol, and Attribute Mapping tabs as needed.
9. Click Done.

Editing an SSO Configuration

At some point you might need to edit the SSO configuration's details. For example, revising attribute mappings or default groups. You view and edit SSO configurations from the same SSO configuration modal. However, to edit your SSO configuration you need to intentionally enable editing.

To edit an SSO configuration:

1. At the top right of the Unqork Designer Platform, click the Settings drop-down.
2. Click Administration.
3. Under Environment, select Single Sign-On (SSO).
4. Select the Express or Designer tab.
5. In the SSO dashboard, find the SSO configuration to edit.
6. Under the Actions column, click Manage.
7. From the Manage drop-down, select Edit. The SSO configuration modal opens.
8. Set the Edit toggle to ON.

9. Make changes to the settings in the Basic Information, Configure Protocol, and Attribute Mapping tabs as needed.
10. Click Save.

Deleting an SSO Configuration

Whether an SSO configuration is no longer needed or you changed SSO providers, you'll need to delete SSO configurations from your SSO dashboard at some point.

WARNING  Deleting an SSO configuration is permanent and irreversible.

To delete an SSO configuration:

1. At the top right of the Unqork Designer Platform, click the Settings drop-down.
2. Click Administration.
3. Under Environment, select Single Sign-On (SSO).
4. Select the Express or Designer tab.
5. In the SSO dashboard, find the SSO configuration to delete.
6. Under the Actions column, click Manage.
7. From the Manage drop-down, select Delete.
8. At the confirmation message, click Yes, Delete.

Related Resources

The following articles provide additional information related to SSO configuration:

General Information

Provider-Specific How-to Guides: Express View (OIDC)

Provider-Specific How-to Guides: Express View (SAML)

Provider-Specific How-to Guides: Designer (SAML)