🌐 Web | 👤 Organization admin
To set up Yokoy with Microsoft Entra ID (formerly Azure Active Directory) using SAML 2.0, you'll need to configure both Yokoy and the Microsoft Entra ID app.
Some steps may require actions in either system. Yokoy is a certified Entra ID app, making the configuration process easier. For more details and information, see Microsoft Entra SSO integration with Yokoy - Microsoft Entra ID.
To set up SSO to allow users to sign into Yokoy with their Entra ID:
Disable password authentication (optional)
Set up the domain(s) and authentication protocol
You need to set up the SAML 2.0 protocol used by Microsoft Entra ID in Yokoy.
Go to Admin > Organization, and select the Authentication tab.
🚧 Caution
Make sure the Authentication feature has been enabled for your organization. Otherwise, you won’t be able to see this tab.
Add a specific domain related to your company. To add a specific domain for your organization, use the format yourcompany.com. Press Save to save the domain. You can add multiple domains per organization. For example, if your organization has different domains for various countries, include all of them (i.e. company-a.it, company-a.ch, company-a.de).
Once you have added all domains, you can determine the desired authentication method. Click Add provider and select the SAML protocol.
Copy SP entity ID and ACS URL
When you select SAML, you can view:
SP entity ID
ACS URL
You need to copy these URLs (by clicking the copy icon beside the field) to configure MS Entra ID to communicate with Yokoy if you do not have access to Microsoft Entra ID.
✏️ Note
If you want to set up an identity provider initiated flow, you need to contact Yokoy to set this up.
Add Yokoy as a new SAML application
In Microsoft Entra, go to Enterprise applications and click + New application. Search for Yokoy in the search bar, and select Yokoy.
Click Create to add the app to your Microsoft Entra Gallery.
Set up SAML SSO
In the application overview, in Single sign-on, select Set up single sign on and choose SAML as the single sign-on method.
Add SP entity ID and ACS URL
Enter the SP entity ID provided by Yokoy in the Identifier (Entity ID) field and the ACS URL in the Reply URL (Assertion Consumer Service URL) field.
For the sign-on URL, enter the URL for the corresponding environment:
Environment | URL |
Production | |
Sandbox |
Click Save to keep the configuration.
The default values in the User Attributes Claims can be left. However, they can be changed if required.
Download the IdP metadata
Download the SAML signing certificate as metadata XML (Federation Metadata XML). You need this to locate the OX509 certificate and the OPOST binding SSO URL.
You can find these details within the metadata XML. Look for the <IDPSSODescriptor> tag to locate the necessary details.
💡 Tip
You can use any browser to open the XML metadata file and select the specific parts of the XML file you need.
🚧 Caution
When implementing Microsoft Entra ID with SAML, it is important to check:
○X509 Certificate: Certificates generated for Test and Prod should be different.
○POST binding SSO URL: This should end with
saml2and notwsfed.
If it ends withwsfed, you haven't set up SAML correctly.
Add ○X.509 certificate and ○POST binding SSO URL
Paste the X509 certificate in the Certificate field and the POST binding SSO URL in IdP login URL.
When pasting the certificate, make sure:
Only include text starting from the actual string.
DO NOT include XML brackets (e.g. </ds:X509 Certificate>)
There are no line breaks.
✏️ Note
The SSO URL doesn’t require any authentication and you can immediately see whether it’s valid by opening it in a browser. This can help to eliminate some issues resulting from incorrect configuration.
Add a button label for the SSO log-in button
You can add text that is used in the button displayed to the end user. This text is compiled with the button label Sign in with. For example, if you enter Microsoft Entra in this field, the button label is displayed as Sign in with Microsoft Entra.
Test the SSO configuration
Once you have finished the configuration, proceed with testing. Enter a test email address in the main Yokoy login page and click Continue. Once Yokoy has detected an email with the company’s domain, you see the SSO option. For example, you see an additional button above the password option: Sign in with Microsoft Entra (SAML).
You should set up a test user that you can use to test the full flow to ensure SSO is correctly configured. The test can include clicking on the SSO button. This can show if the application is configured correctly. For example, it may show a Microsoft Entra ID error if configured incorrectly.
💡 Tip
If the button does not show, check:
environment: check that you have configured the correct environment (sandbox/production).
domain: Make sure the email domain is spelled correctly and matches the one configured.
Disable password authentication
Once you have verified that SSO has been set up correctly and users can log in via SSO, then password authentication can be disabled for the organization to prevent login issues. Although this step is recommended, you can choose to allow both authentication methods.
To do this, go to Admin > Organization, Authentication tab and turn off the Enable password toggle.
