Single Sign-On (SSO)
Single-Sign-On (SSO) lets users log in once with a single ID to multiple related software systems. The Security Assertion Markup Language (SAML) open standard is designed to deliver a seamless user experience through SSO flows.
A service provider (SP) provides services to end users and rely on an identity provider (IDP or IdP) to verify a user’s identity. SSO through SAML can be initiated by an IDP (IDP-initiated SSO) or an SP (SP-initiated SSO).
Supported SSO Initiation Forms
With the release of YubiEnterprise Services 2.4.0, both IDP- and SP-initiated SSO are supported. Console Owners can enable IDP-initiated SSO from the YubiEnterprise Console. For more information, see SSO Enablement.
IDP-initiated SSO
The IDP authenticates users when they present their credentials so that those users can then access other websites and applications (relying applications). The SAML flow for an IDP-initiated SSO is as follows:
- When the IDP and SP established SSO trust, they shared a private key.
- The user’s identity is sent by the IDP to the SP in the form of a SAML assertion signed with the private key.
- To retrieve the SAML Assertion securely, the IDP uses the user’s browser or a reference that the SP can use.
SP-initiated SSO
Service providers rely on an IDP to store the user’s information (including attributes for the particular service requested), and make authentication decisions based on that information.
SP-initiated SSO comes into play when a user tries to access an application at the SP end without having first authenticated with an IDP. In this case, the SAML flow is as follows:
- In the absence of an active browser session, the SP redirects the user to the IDP to request authentication.
- The user’s identity is sent by the IDP to the SP in the form of a SAML assertion signed with the private key.
- If the SP supports SSO from multiple IDPs, it can determine which IDP to use by:
- Requesting the user to enter additional information.
- Showing the user the list of supported IdPs so the user can select the right one.
- Using a resource URL specific to a specific IDP.
- Restoring an IDP cookie in the user’s browser session from initial IDP login.
- Upon receipt of the SAML assertion, the SP validates the signature using the public key and presents the user with its landing page as if the user had logged in with the usual credentials instead of SSO.
Logging in Using SSO Only
SSO enablement introduces a new category of user: those who are able to log in only via SSO. Users added after SSO is enabled fall into this new category, while users enrolled prior to SSO enablement will still be able to log in with username and password.
Important
Users that were enrolled before enabling SSO can still log in with their credentials but only to perform SSO management actions. For other Console actions they need to authenticate via SSO. This permission setup prevents users from locking themselves out for example if they have forgotten their password, then log in with SSO and accidentally misconfigure or disable SSO, in which case they would be locked out.
If SSO is disabled, none of the users added after SSO is enabled will be able to log in. For more information, see Disabling SSO. API tokens are not affected by SSO enablement or disablement.
Note
Only a single organization at a time can be logged into with SSO. A user who is a member of multiple organizations cannot use SSO-logged-in sessions to switch between organizations. If a user needs to switch from one SSO-enabled organization to another, they must log out of the first organization and use the login link supplied by the SP for the second organization.
See also Managing Passwords with SSO.
Permissions and SSO
Capability
|
Logging in with SSO
|
Logging in with credentials
|
---|---|---|
Status | Users invited to join the Console
go into the
Active state andcan log in immediately via the
SP’s SSO login link.
|
Users invited to join the
Console without SSO
go into the
Pending stateuntil they enroll their credentials.
|
Login Redirect | None: not applicable | If SSO has been enabled, users
who log in using credentials will
be redirected to log in via SSO.
|
Console Operations | All are permitted (for example shipment
request creation, listing POs, inviting
users etc.) except configuring SSO and
updating credentials.
|
No operations other than
configuring SSO
(by Console Owner) and
updating credentials are
permitted.
|
Credential Update | Not permitted; credential
management page is inaccessible.
|
All roles can update their
credentials: change password,
edit, delete, and add new
YubiKeys.
|
SSO Configuration | Not permitted for any role. | Console Owners may
configure SSO.
|
SSO Enablement
The sections below describe how to configure and enable SSO for different identity providers. Console Owners can enable IDP-initiated SSO by logging in to the Console with credentials, going to Settings > SSO, and selecting Allow IDP initiated single sign-on.
Requirements
To enable SSO integration you need to:
- Use SAML 2.0 with Azure AD or Okta or Google Workspace as your IDP. Other IDPs are likely to be compatible, but are not supported. For more information, see Enabling SSO for Other IDPs.
- Have owner, admin, or super-admin access to the SSO app in your IDP account for permissions to manage the SAML configuration and users.
- Know how to enable, edit and disable your IDP’s SSO offering.
- Be able to share the SSO link with the Console users in your organization out-of-band after SSO is enabled, this is not something that the system does automatically.
- Be a Console Owner in the Console.
- Be able to log in to the Console with username/password and a registered YubiKey (via credentials, not SSO).
Known Limitations
- Since Console users invited after SSO enablement are not required to have username and password, they will not be able to log in if SSO access is disabled. These users must be reset to be able to log in using credentials. Resetting a user triggers the system to send the user an email directing them to reset their username/password and register a YubiKey. See Disabling SSO.
Google Workspace cannot support both the SP-initiated and the IDP-initiated ACS URL at the same time. It is also not possible to set up two different SAML Apps in the same Google Workspace, because Google Workspace enforces SP EntityID uniqueness across all SAML Apps in the workspace.
When IDP-initiated SSO is enabled with the Google Workspace SAML application, the IDP-initiated SSO ACS URL (
/realms/y4o-azad/broker/sso/endpoint/clients/idp-initiated
) must be configured as the ACS URL in order for the Google Dashboard link to work. When the Google Workspace SAML application is configured with this URL, the IDP will not work with the SP-Initiated flow since the Reply URL (ACS) endpoint does not match what is configured above.
Enabling SSO with Azure AD
This section describes how to enable SSO between Azure AD and the YubiEnterprise Console. These instructions assume that your company’s SAML application has already been created in Azure AD.
Note
The Azure AD SAML Enterprise Application can be made to work with both the SP-initiated and IDP-initiated flows. Configure both the IDP-initiated ACS URL and the SP-initiated ACS URL as valid reply URLs. Make sure to mark the IDP-initiated URL as default.
Copy Entity ID from Console to Azure AD
Step 1: | Log in to the Console as Console Owner using credentials (password and MFA), and go to Settings > SSO. The Configure SAML Single Sign-On page appears. Click the copy icon at the end of the EntityID/Identifier field in section 1. |
---|---|
Step 2: | Log in to your Azure tenant https://portal.azure.com/signin/index/. |
Step 3: | Set up the new application in Azure AD (note that this does not mean “create the new application”) by going to Manage Azure Active Directory and clicking View. Your company’s Overview page for Azure AD appears. |
Step 4: | From the menu on the left-hand side, select Enterprise Applications. Your company’s Overview page for all applications appears. |
Step 5: | From the list in the center pane, select the appropriate SAML application. The Overview page for that application appears. |
Step 6: | Click Get started in the second box Set up single sign on. The [Name of your organization’s enterprise application] SAML | SAML-based Sign-on page appears. |
Step 7: | Click the Edit icon for 1 Basic SAML Configuration. The Basic SAML Configuration window appears. |
Step 8: | Under Identifier (Entity ID), click Add identifier. A new field appears. |
Step 9: | Paste what you copied from the Console (in step 1) into the Identifier (Entity ID) field in Azure. If you select Default, this will be the primary identifier sent for IDP-initiated SAML responses. |
Step 10: | Save your settings by clicking Save in the top left corner of the Basic SAML Configuration Edit window. |
Copy Reply URL from Console to Azure AD
Step 1: | Log in to the Console as Console Owner using credentials (password and MFA), and go to Settings > SSO. The Configure SAML Single Sign-On page appears. Click the copy icon at the end of the Reply URL (ACS) field in section 1. |
---|---|
Step 2: | Unless you are already logged into Azure and on the Basic SAML Configuration Edit window, log into your Azure tenant https://portal.azure.com/signin/index/ and perform steps 2-7 in Copy Entity ID from Console to Azure AD above. |
Step 3: | Under Reply URL (Assertion Consumer Service URL), click Add reply URL. A new field appears. |
Step 4: | Paste what you copied from the Console’s Reply URL (ACS) field (in “Step 1”) into the Reply URL (Assertion Consumer Service URL) field in Azure. If you select Default, this will be primary and IDP-initiated SAML responses will be sent to this reply URL. |
Step 5: | In Azure, save your settings by clicking Save in the top left corner of the Basic SAML Configuration Edit window. |
Copy Login URL & Azure AD Identifier from Azure to Console
Step 1: | Unless you are already logged into Azure and on the Basic SAML Configuration Edit window, log into your Azure tenant https://portal.azure.com/signin/index/ and perform steps 2-7 in Copy Entity ID from Console to Azure AD above. |
---|---|
Step 2: | In Azure, in section 4 Set up [your company’s] SAML, click the copy icon at the end of the Login URL field. |
Step 3: | Log in to the Console as Console Owner using credentials (password and MFA), and go to Settings > SSO. The Configure SAML Single Sign-On page appears. Paste the content from the Login URL field in Azure into the IDP login URL field in section 2. |
Step 4: | Go back to Azure, and in section 4 Set up [your company’s] SAML, click the copy icon at the end of the Azure AD Identifier field. |
Step 5: | In the Console, in Settings > SSO, on the Configure SAML Single Sign-On page in section 2, paste the content from the Azure AD Identifier field in Azure into the EntityID/Issuer field. |
Copy X509 Certificate from Azure AD to Console
Step 1: | Unless you are already logged into Azure and on the Basic SAML Configuration Edit window, log into your Azure tenant https://portal.azure.com/signin/index/ and perform steps 2-7 in Copy Entity ID from Console to Azure AD above. |
---|---|
Step 2: | In section 3, SAML Certificates, download the Certificate (Base64) by clicking Download. |
Step 3: | Open the file in a text editor and copy it. You do not need to to remove the header and footer lines: |
Step 4: | In the Console, in Settings > SSO, on the Configure SAML Single Sign-On page in section 2, paste the certificate content into the X.509 cert (Base64) field. (The header and footer in the file will be automatically stripped out when you save.) |
Step 5: | Click the Save settings button at the bottom of the Console page. |
Set Attributes & Claims in Azure AD
There is always a required claim. Ensure that the name identifier format is Email address.
Step 1: | Unless you are already logged into Azure and on the Basic SAML Configuration Edit window, log into your Azure tenant https://portal.azure.com/signin/index/ and perform steps 2-7 in Copy Entity ID from Console to Azure AD above. |
---|---|
Step 2: | In section 2, Attributes & Claims, click the Edit icon. |
Step 3: | In the Attributes & Claims window that appears, click the Unique User Identifier (Name ID) in the Required claim section. |
Step 4: | In the Manage claim window that opens, if the Name identifier format is not Email address, select it from the dropdown list. |
Step 5: | Save your settings in Azure by clicking Save in the top left corner of the Manage claim window. The Attributes & Claims window reappears. |
Step 6: | In the Attributes & Claims window, directly underneath the title, click + Add new claim. The Manage claim window appears. |
Step 7: | In the Manage claim window, in the Name field, enter |
Verify and Save SSO Settings in Console
Add Users and Enable User Login via SSO
Add users first to Azure, then to the Console. Before you can add them to your company’s SAML application in Azure, the users must be added to your company’s Azure AD instance at the top level. If needed, ensure you have the permissions in Azure to have groups available for assignment.
Enabling SSO with Okta
This section describes how to enable SSO between Okta and the YubiEnterprise Console. These instructions assume that your company’s SAML application has already been created in Okta.
Create App Integration
Step 1: | Log in to the Console as Console Owner with user name and password, and go to Settings > SSO. The Configure SAML Single Sign-On page appears. This is the location from which you will be copying information. |
---|---|
Step 2: | Log in to your company’s Okta tenant https://developer.okta.com/login/ as Admin, and navigate to Applications > Applications. The Applications page appears on the right. |
Step 3: | Click Create App Integration. The Create a new app integration window appears. |
Step 4: | Select SAML 2.0 and click Next. The Create SAML Integration window appears. |
Step 5: | On the 1. General Settings tab, enter the appropriate name in the App name field, make any other necessary settings and click Next. The Configure SAML tab of the Create SAML Integration window appears. |
Copy Entity ID from Console to Okta
In the Console Settings > SSO page from Step 1 in Enabling SSO with Okta, click the copy icon to copy the EntityID/Identifier from the Console.
Paste it into the Audience URI (SP Entity ID) field in Okta’s Configure SAML tab.
Copy Reply URL from Console to Okta
In the Console Settings > SSO page from Step 1 in Enabling SSO with Okta, click the copy icon to copy the Reply URL (ACS) from the Console.
Paste it into the Single sign-on URL field in Okta’s Create SAML Integration window on the Configure SAML tab. Enable the checkbox for Use this for Recipient URL and Destination URL.
Set Name ID Format, Application Username, and Attribute Statement
Copy IDP SSO URL & X509 Certificate from Okta to Console
Add Console Users to Okta’s SAML App Integration
Users for whom you intend to enable SSO must first be in Okta to be available for adding to the application integration. For information on how to add users, see the Okta documentation.
Enable IDP- and SP-initiated SAML Flows
This configuration enables both the IDP- and SP- initiated SAML flows for Okta. This subsection assumes that you are familiar with the instructions for IDP-initiated SAML flow with Okta.
Enabling SSO with Google Workspace
This section describes how to enable SSO between Google Workspace and the YubiEnterprise Console.
Prerequisites
- Ensure that you are a Console Owner in the Console.
- System role: Your Google Workspace Administrator Seed Role must be Super Admin.
- Ensure you have access to the email account associated with that Google account.
Procedure
Add a Custom SAML App
Step 1: | Log into the Google Admin Workspace by going to admin.google.com/ and selecting the appropriate account. |
---|---|
Step 2: | Enter username and password for the selected account. If your company has set up Google Groups to require a YubiKey, you will be prompted to plug one in and touch it. After login, the Admin page appears. |
Step 3: | Go to Apps > Web and mobile apps. |
Step 4: | Create a new SAML app by clicking on the Add app dropdown and selecting Add custom SAML app (you need be Super Admin to see this option.) Under the Add custom SAML app banner, the 1 App details tab is displayed: |
Step 5: | In the 1 App details tab:
|
Configure the Custom SAML App
Copy and paste information between the Google Add custom SAML app and the Console Configure SAML Single Sign-On pages, have them open side-by-side in two browser windows.
Troubleshooting
Issue: Changing the ACS URL in an existing Google IDP configuration does not appear to be successful even after waiting a significant amount of time.
- Workaround: Start over. Delete your Web and mobile app and start again.
Issue: Sometimes the Google site displays the 500 error after SSO configuration.
- Workaround: Update the Entity ID with a trailing forward slash “/”. If you already have such a slash, remove it.
Issue: Sometimes Google presents the message “Service is not configured for this user”.
- Workaround: Update the Entity ID with a trailing forward slash “/”. If you already have such a slash, remove it.
Enabling SSO with Duo
This section describes how to enable SSO between Duo and the YubiEnterprise Console. Note that unlike the other SAML integrations described above, Duo is not the IDP for the users. The following instructions assume that Duo is configured with Azure as the IDP, so those steps are not included.
Prerequisites
- Ensure that Duo’s IDP is configured (Azure for this environment).
- Ensure that you are a Console Owner in the Console.
- As Console Owner, add the SSO users to your organization in the Console, see Adding or Deleting Users. Each user’s email address must match the email address used for that user in Duo and in Azure.
Procedure
To copy and paste information between the Duo and the Console configuration pages, have them open side-by-side in two browser windows.
Step 1: | As administrator, log in to the Duo Tenant Admin portal: https://admin.duosecurity.com. |
---|---|
Step 2: | Add the Console (YubiEnterprise Delivery) application in Duo. Go to Applications > Protect an Application > YubiEnterprise Delivery > Protect. |
Step 3: | Log in to the Console with the Console Owner role. |
Step 4: | Configure Console SSO to IDP (Duo). In the Console, go to Settings > SSO to open the SAML Single Sign-On page. Copy the EntityID/Identifier field from section 1 in the Console to the EntityID/Identifier field in the Duo Service Provider section. Console configuration section Duo configuration section |
Step 5: | Configure IDP (Duo) to SP (Console).
Duo configuration section Console configuration section |
Step 6: | Save settings and enable SSO in the Console. Ensure to click Save settings and Enable SSO before closing your browser. |
Step 7: | Configure Duo application attribute mapping. To configure a Duo attribute other than Email Address as the email address attribute sent to the Console in the SAML response, return to the Duo application configuration screen Service Provider section, check the box for Custom attributes, and then select the attribute to send as the email address attribute. |
Step 8: | Configure Duo application policy. Duo policies control how users authenticate to specific applications. Steps 8 and 9 ensure that MFA is enforced, and YubiKeys are enabled as Webauthn authentication method. These policies can be configured globally, or per application. If other applications are already being protected with Duo, ensure that the following settings can apply to all applications, or consider creating a unique Application policy for the Console. See the Duo documentation.
|
Step 9: | Ensure hardware tokens are selected. In Duo, scroll down to the Authentication methods section, and ensure the Hardware tokens option is selected. |
Step 10: | Save the global policy. In Duo, click Save Policy at the bottom of the Global Policy configuration page. |
Step 11: | Save the application configuration. In Duo, click Save at the bottom of the application configuration page. |
Enabling SSO for Other IDPs
To try out SSO for identity providers that Yubico does not explicitly claim to support, go to Settings > SSO > Configure SAML Single Sign-On, and fill in the configuration fields.
Note
Be aware that the field labels vary depending on the IDP. For examples of these variances, look at the instructions for supported IDPs Microsoft Azure, Okta, and Google Workspace.
Disabling SSO
To disable SSO, in the Console, go to Settings > SSO. In the Configure SAML Single Sign-On page click the Disable SSO button.
Users added after SSO was enabled will not be able to login once SSO is disabled. Therefore you need to determine which users need to be enabled to log in with credentials again. To see which users have credentials, log in to the Console as Console Owner with credentials and go to Settings > Users. The MFA column on the page indicates which users have credentials.
To enable users added after SSO enablement to enroll credentials and log in again, reset them as described in Account Recovery and Password Reset.
To file a support ticket for YubiEnterprise Delivery, click Support.