🌐 Web | 👤 Organization admin
To set up Yokoy to use Okta with SAML 2.0, you need to configure both Yokoy and Okta. Depending on the step, you may need to perform actions in Yokoy or in Okta.
For more details and information, see Create SAML app integrations - Okta documentation.
To set up SSO to allow users to sign into Yokoy with Okta:
Disable password authentication (optional)
Configure the domain(s) and select an authentication protocol
First you need to set up the SAML 2.0 protocol used by Okta 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 by clicking +Add domain. The domain is specified as part of your company’s email address. Make sure to insert only your specific company domain in a yourcompany.com format. Press Save to save the domain.
You can add multiple domains for an organization. For example, if you have different domains for various countries, make sure to add them all here (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 protocol SAML protocol.
Copy SP Entity ID and ACS URL
In this case, select SAML. When you select SAML, you can view:
SP entity ID (metadata endpoint)
ACS URL (ACS endpoint)
You need to copy these URLs by clicking the copy icon beside the field as you’ll need to configure Okta to communicate with Yokoy.
Add Yokoy as a new SAML application
Go to OKTA admin and add a new app. Select a SAML 2.0.
✏️ Note
If you also plan to enable user provisioning in Yokoy, you must use SAML 2.0 authentication. Okta only supports OpenID Connect authentication for single sign-on.
Add the SP entity ID and ACS URL in the SAML configuration
Enter Yokoy as the name of the app, and include a logo for the app (optional).
Enter the SP entity ID in the Audience URI (SP Entity ID) field and the ACS URL in the Single sign-on URL field.
Enter the sign-on URL depending on the environment:
Environment | URL |
Production | |
Sandbox |
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.
Within the metadata file (which may be a very long XML document), search for the tag IDPSSODescriptor to find the relevant information.
You need to locate:
○X509 Certificate: string found within the
<ds:X509Certificate>tag○POST binding SSO URL: URL found directly after
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="
💡 Tip
If you get the OPOST binding SSO URL (= well-known url for SSO), try to open it in the browser first. These URLS don't require any authentication and you can immediately see whether it’s valid. This can help to eliminate some issues resulting from incorrect configuration.
Example of the metadata XML
Add ○X509 Certificate and ○POST binding SSO URL
You can now configure the setup on Yokoy’s side.
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.
Paste the X509 Certificate in Certificate field, and the POST binding SSO URL in the IdP login URL field.
Add a button label for the SSO log-in button
Finally, you can add text that is used in the button displayed to the end user. Bear in mind that this text is compiled with the button label Sign in with. For example, if you enter Okta in this field, the button label is displayed as Sign in with Okta.
Save the configuration and proceed with testing
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.
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 an Okta 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.
