Single Sign-On (SSO)
Note
This feature capability is only available upon request. You will be able to see the Configure SSO tab once Yubico has enabled the SSO feature for you.
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 using 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.
API tokens will not be affected by SSO enablement or disablement. They will keep working as usual.
User can only use SSO to log into a single org. If a user is a member of multiple orgs, they cannot use SSO logged in sessions and switch between orgs via the org selector in Profile page. Org selection is only available if user logs in with credentials instead, immediately after login as well as on the Profile page. If user needs to switch from a SSO enabled org to another SSO enabled org, they will need to log out from Org 1 SSO logged in session and use the SP login link for Org 2.
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 guards against Org Owners who have forgotten their passwords logging in via SSO, then disabling or misconfiguring SSO and thereby 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 and will immediately acquire the Active status, in contrast to users invited to join before SSO enablement, who go into the Pending state until they enroll their credentials.
All users will be able to log in via SSO immediately by using the service-provider’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 service-provider’s link) can users perform the usual operations permitted by their roles (e.g., shipment listing and 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 will it be possible to use the service-provider’s SSO login link for 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 as your Identity Provider (IDP)
- Have owner / 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., with credentials as opposed to via SSO)
- Request Yubico to enable the SSO feature
Known Limitations
- Currently only Service Provider initiated authentication is supported; more specifically, only Azure AD and Okta are supported as Identity Providers.
- 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 the Okta test tenant https://developer.okta.com/login/ as Admin, and navigate to Applications > Applications. 
|
| Step 3: | Click Create App Integration. The Create a new app integration window appears. 
Select SAML 2.0 and click Next. The Create SAML Integration window appears. 
|
| Step 4: | 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.
Disabling SSO
To disable SSO, in the Console, go to Settings > SSO Configure SAML Single Sign-On and click the Disable SSO button.
Note
None of the users added after SSO was enabled will be able to login once SSO is disabled. To determine which users were added after SSO enablement, log in with credentials, then go to Settings > Users. The MFA column in the table tells you whether they have credentials or not. To enable those users to enroll credentials and log in again, reset them (see Account Recovery and Password Reset).