Single Sign-On (SSO)
SSO enablement introduces a new category of user, i.e., those who are able to log in only via SSO. Users added after SSO is enabled fall into this new category. The credentials of users enrolled prior to SSO enablement will still be available after SSO is enabled, which means they will still be able to log in with username and password. Org Admins and Auditors who log in this way will be directed to authenticate via the SSO link in order to perform Console operations. Org owners must log in with credentials to configure SSO.
API tokens will not be affected by SSO enablement or disablement. They will keep working as usual.
Users can only use SSO to log into a single org at a time. If a user is a member of multiple orgs, that person cannot use SSO-logged-in sessions and switch between orgs. Org selection is only available if the user logs in with credentials immediately after login as well as at any other time from the Profile page. If a user needs to switch from one SSO-enabled org to another SSO-enabled org, they must log out of the first one and use the login link supplied by the Service Provider (SP) for the other org.
See also Managing Passwords, etc. with SSO: Single Sign-On.
Permissions after SSO Enablement
Logging in With Credentials
Org Owners, Admins, and Auditors who log in with credentials can update those credentials: change password, edit, delete, and add new YubiKeys.
Org Owners who log in with credentials can also configure SSO.
All other Console operations require logging in via SSO.
This permissions setup prevents Org Owners who have forgotten their passwords logging in via SSO, then disabling or misconfiguring SSO and inadvertently locking themselves out.
Logging in Via SSO
Users who are invited to join YubiEnterprise Services after SSO enablement will not be asked to enroll credentials; instead, they will immediately be accorded Active status. In contrast, users invited to join before SSO enablement go into the Pending state until they enroll their credentials.
All users will be able to log in via SSO immediately by using the SP’s SSO login link.
Users who log in using credentials will be redirected to log in via SSO.
Only when logging in via SSO (using the SP link) can users perform the usual operations permitted by their roles (e.g., shipment request creation, listing POs, inviting users, etc.).
Updating credentials after logging in via SSO is not possible for any role; the credential management page is not accessible.
Although Org Owners can configure SSO, the SSO configuration page is read-only if they log in using SSO.
If a user who is a member of multiple organizations logs into one of them via SSO, that user cannot switch between those organizations without first logging out of the original organization. Only then can that person use the SP’s SSO link to log in to the desired organization.
Requirements for SSO Enablement
To enable an SSO integration you need to:
- Be using SAML 2.0 with Azure AD or Okta or Google Workspace as your Identity Provider (IDP). Other IDPs are likely to be compatible, but they are not supported. (For this latter case, see SSO Configuration Tab.)
- Have owner / admin /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 YubiEnterprise Services users in your org out-of-band after SSO is enabled: this is not something that the system does automatically
- Be an Org Owner in YubiEnterprise Services
- Be able to log in to YubiEnterprise Services with username and password and have a YubiKey enrolled (i.e., via credentials as opposed to via SSO).
Known Limitations
- Currently only SP-initiated authentication is supported; more specifically, only Azure AD, Okta, and Google Workspace are supported as IDPs (although other IDPs might work too).
- Since users invited to join YubiEnterprise Services after SSO enablement are not required to have username/password, they will not be able to log in if SSO access is disabled. Workaround for enabling access via credentials: Users invited to join YubiEnterprise Services after SSO enablement must be reset in order to enable them to enroll credentials. Resetting a user triggers the system to send the user an email directing them to reset their username/password and enroll a YubiKey.
Enabling SSO with Azure AD
These instructions assume that your company’s SAML application has already been created in Azure AD.
Copy Entity ID from Console to Azure AD
| Step 1: | As Org Owner, use credentials (i.e., password and MFA) to log in to the YubiEnterprise Console, then go to Settings > SSO. The Configure SAML Single Sign-On page appears. Click the copy icon at the end of the EntityID/Identifier field under “Step 1”. 
|
|---|---|
| Step 2: | Log into 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 the Default checkbox, you will be marking this as primary. This will be the 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: | As Org Owner, use credentials (i.e., not SSO) to log in to the YubiEnterprise Console, then 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 under “Step 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 the Default checkbox, you will be marking this as 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: | As Org Owner, use credentials (i.e., not SSO) to log in to the Console, then 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 the Step 2 box in the Console. 
|
| 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 the Step 2 section, paste the content from the Azure AD Identifier field in Azure into the Console’s 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 on the Download button. 
|
| Step 3: | Open the file in a text editor like Notepad (not something like Microsoft Word, which deposits all kinds of undesirable artifacts into a simple text file), and copy it. It is not necessary to remove the header and footer lines: 
|
| Step 4: | In the Console, in Settings > SSO, on the Configure SAML Single Sign-On page in the Step 2 section, 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
| Step 1: | In the Console, look at Settings > SSO Configure SAML Single Sign-On to make sure that the content you pasted in is correct. |
|---|---|
| Step 2: | In the last section, Step 3, copy the SP Initiated Login URL by clicking the copy icon at the end of it. Save the URL so that you can send it to YubiEnterprise Services users. 
|
| Step 3: | Before enabling SSO, make sure to send all users who will be enabled for it this SP Initiated Login URL. The same link will also be shown on the login screen after you have enabled SSO. |
Add Users and Enable User Login via SSO
Add users first to Azure, then to YubiEnterprise Services. 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 necessary, make sure that you have the permissions in Azure to have groups available for assignment.
| Step 1: | On your company’s Overview page in Azure, from the menu on the left under Manage, select Users. 
On the Users page, the entire list of your company’s users appears. |
|---|---|
| Step 2: | To add entirely new users to Azure as opposed to adding them to the SAML organization, click New user at the top of the page and follow the directions provided in the subsequent pages. Otherwise select the users for whom you are enabling SSO by clicking on the checkbox next to the respective Display name. |
| Step 3: | From [your company’s] SAML Overview page, click Assign users and groups. 
The Users and groups window appears. |
| Step 4: | Click Add user/group at the top of the window. The Add Assignment screen appears. 
Underneath Users, click None Selected, and a list of your total users in Azure appears. |
| Step 5: | Select the checkboxes for the requisite users, then click the Select button. |
| Step 6: | As Org Owner or Admin, log in to the Console, go to Settings > Users, and add any necessary users to YubiEnterprise Services from Azure. |
Enabling SSO with Okta
These instructions assume that your company’s SAML application has already been created in Okta.
| Step 1: | Log in to the YubiEnterprise Console with username and password and navigate to Settings > SSO. 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
| Step 1: | In Okta, still in the General section on the A SAML Settings tab, from the Name ID format dropdown, select EmailAddress. |
|---|---|
| Step 2: | From the Application username dropdown, select Email. 
|
| Step 3: | Scroll down to the Attribute Statements (optional) section, and
|
| Step 4: | Scroll down to the bottom of the tab and click Next. The Feedback tab appears. |
| Step 5: | On the Feedback tab under Create SAML Integration, select either:
provide feedback as desired (or not) and click Finish. The Sign On tab for your application appears. 
|
Copy IDP SSO URL + X509 Certificate from Okta to Console
| Step 1: | On the bottom right of Okta’s Sign On tab, click the View SAML setup instructions tab. 
The How to Configure SAML 2.0 for [name of your] Application window appears. 
|
|---|---|
| Step 2: | Still in Okta, copy the content of the Identity Provider Single Sign-On URL: to the IDP login URL field in the Console. 
|
| Step 3: | From the Okta The following is needed to configure [application name] window, copy the Identity Provider Issuer to the Console’s EntityID/Issuer. |
| Step 4: | In Okta, click Download certificate under X.509 Certificate, then paste the content to the Console’s X.509 cert (Base64) field. |
| Step 5: | In the Console, click Save settings. |
| Step 6: | From the Console, copy the SP Initiated Login URL and send it to your users. |
Add YubiEnterprise Services Users to Okta’s SAML App Integration
To Okta, add the YubiEnterprise Services users for whom you intend to enable SSO. (Detailed instructions for this can be found in Okta’s documentation.) In order to be available for adding to an application integration, the users need to be in Okta itself first. In Okta, navigate to Applications > Applications and click Assign Users to App. The [name of app] page for your app appears.
Assign YubiEnterprise organization members as a group or as individuals.
In the Console, enable SSO.
Enabling SSO with Google Workspace
Prerequisites
- Ensure that you are an Org Owner in YubiEnterprise 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 in Google
| Step 1: | Log into the Google Admin Workspace by going to admin.google.com/ and selecting the appropriate account as shown here: 
|
|---|---|
| Step 2: | Enter username and password for the selected account. (Your company may have set up Google Groups to require a YubiKey, in which case, you will be prompted to plug one in and touch it.) After login, the Admin page appears: 
|
| Step 3: | Navigate from Apps to Web and mobile apps by selecting the latter, so that you arrive at the Apps > Web and mobile apps page: 
|
| Step 4: | Create a new SAML app by clicking on the Add app dropdown and selecting Add custom SAML app. (If you do not see this option, it is because your role is not Super Admin.) 
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
Prepare to copy and paste information from the Google Add custom SAML app screen to the YubiEnterprise Console Configure SAML Single Sign-On page - and vice versa. Using two browser windows side-by-side, bring up YubiEnterprise Console next to the Google Workspace. Leave the browser window with Google open, but reduce the size if necessary to half your screen, and open an additional browser window in the other half of your screen for YubiEnterprise Delivery.
| Step 1: | Log in to the Console as Org Owner with username, password, and YubiKey. 
|
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Step 2: | On the Console, navigate to the SSO configuration page: Settings > SSO. 
|
||||||||||||
| Step 3: | Enter the following values from Google’s 2 Google Identity Provider detail page into the Console’s SSO configuration form, transferring them from the fields listed in the table:
On the Console’s Configure SAML Single Sign-On page, click Save settings. |
||||||||||||
| Step 4: | In Google, in the Add custom SAML app screen, click CONTINUE. The 3 Service provider details window appears. 
|
||||||||||||
| Step 5: | In Google, in the 3 Service provider details window, enter the following values from YubiEnterprise Console into Google’s form, transferring them from the fields listed in the table:
|
||||||||||||
| Step 6: | In Google, in the 3 Service provider details screen, click CONTINUE. The 4 Attribute Mapping page appears (with Attributes and Group membership (optional). Skip these steps by clicking FINISH. The page for your new SAML app appears: 
|
||||||||||||
| Step 7: | In Google, ensure that User Access is ON for everyone by clicking on the tiny caret in the upper right corner of the User access section, circled in magenta in the screenshot below: 
The Service Status window opens, as shown below: 
Toggle the service status radio control to ON for everyone and click SAVE. |
||||||||||||
| Step 8: | In the YubiEnterprise Console, click Save settings. Then click Enable SSO. (Unless you had already enabled it and were doing nothing more than updating your SSO configuration, in which case it was already enabled.) |
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.
|
||
|---|---|---|---|
| Issue: | Sometimes the Google site displays the 500 error after SSO configuration.
|
||
| Issue: | Sometimes Google presents the message “Service is not configured for this user”.
|
SSO Configuration Tab
To try out SSO for unsupported IDPs, go to Settings > SSO Configure SAML Single Sign-On, and fill in the fields on the Configure SAML Single Sign-On tab shown below:
Note
Be aware that the field labels vary depending on the IDP. For examples of these variances, look at the instructions above for the supported IDPs, Microsoft Azure, Okta, and Google Workspace.
Disabling SSO
To disable SSO, in the Console, go to Settings > SSO Configure SAML Single Sign-On and click the Disable SSO button.
Note
Because none of the users added after SSO was enabled will be able to login once SSO is disabled, it becomes necessary to determine which users need to be enabled to log in with credentials. To do this, the Org Owner must log in with credentials, then go to Settings > Users. The MFA column in the table indicates which users have credentials. To enable users added after SSO enablement to enroll credentials and log in again, reset them (see Account Recovery and Password Reset).