🌐 Web | 👤 Organization admin
In Yokoy, you can set up one or more authentication methods for user login.
Yokoy currently offers two authentication methods:
Password login: Users can log into Yokoy using a username (email address) and password.
Single Sign On (SSO): Users can log into Yokoy using their identity provider login (IdP), such as Microsoft Entra ID, Okta, or Google Workspace.
You can determine which authentication methods are used for your organization, i.e. user-password authentication and/or SSO authentication. By default, all organizations are provisioned initially with user-password authentication. However, this can be disabled if you set up SSO. You can set up multiple SSO authentication options.
The authentication methods set up apply to all domains configured for the organization and are not restricted to a specific company. Currently, you cannot assign a specific authentication method to a specific domain (i.e. you can’t force users from the company-a.de domain to SSO, while users from the company-a.es must use user-password authentication).
Authentication using email address and password
By default, password authentication is set for the organization. It allows users to log into Yokoy with their email address and password.
Yokoy uses Google Identity Platform as its identity server. When a new user is created, a token is sent to the user’s email address that allows them to set the initial password.
✏️ Note
If your company plans to use email and password to log into Yokoy, bear in mind that two-factor authentication (2FA) is not supported. If you want to enforce two-factor authentication when users log in, then it is recommended you use SSO authentication via an external identity provider. In this case, the external identity provider is responsible for sending an SMS or push notification or requesting an OTP in an 2FA app that must be entered.
To determine whether password authentication is used for your organization, go to Admin > Organization > User authentication. If Enable password is on, then users can log into Yokoy using password.
💡 Tip
If you can’t see the Authentication tab in Admin > Organization, then reach out to Yokoy to get this feature enabled for your organization.
Users are requested to create a password by sending an invitation when creating their user.
🚧 Caution
User-password authentication cannot be deactivated if it is the only authentication method set up. If you haven’t configured another authentication method, an error message is displayed, stating that the action cannot be completed.
Authentication using single-sign on (SSO)
Yokoy also offers businesses the option to use their own IAM system (e.g. Microsoft Entra, Okta, Google Workspace). Depending on the IAM used, you can use either OpenID Connect (an OAuth 2.0 based standard) or SAML 2.0 authentication protocols to secure the connection. You can use either protocol for logging into both the web and mobile apps.
When identity is federated, credentials are stored by the customer’s identity provider, not in Yokoy. The mobile app uses a temporary access token that is exchanged after successful authentication.
✏️ Note
As an organization admin, you can set up service-provider initiated SSO authentication flows in Yokoy. If your organization requires an identity provider-initiated authentication flow, then you must contact Yokoy to set this up.
Domains for SSO
You determine the domains for which SSO authentication apply. You can add multiple domains for your organization and set up multiple SSO authentication methods. All configured authentication options apply to all domains set up in the organization. You cannot determine a specific authentication option for a specific domain.
Yokoy displays all available methods as separate buttons on the login page once the user has entered the initial identity provider claim, i.e. their email address to determine the domain.
✏️ Note
By default, Yokoy uses the email address as the identity provider claim. However, other attributes can be used (but this needs to be set up by Yokoy).
Users must know which authentication option they must select where there are several set up for your organization. For example, you set up the account with multiple domains, i.e. company-a.de and company-a.es. Users in the Spanish entity use Okta for SSO, while the German entity use Microsoft Entra; therefore, the login page displays two buttons for the different SSO authentication providers.
SSO using OpenID Connect protocol
Yokoy implements the OpenID protocol with PKCE (RFC 7636), an extension to the Authorization Code flow to prevent several attacks and to be able to securely perform the OAuth exchange from public clients. Implicit code flow is not supported.
💡 Tip
If your identity provider is Microsoft Entra ID (formerly Azure Active Directory), see Set up SSO with Microsoft Entra ID (OpenID Connect).
If you don’t see a specific guide for your system, you can still configure Yokoy as an SSO OpenID provider. Make sure to follow the general steps provided below.
Yokoy is responsible for triggering the authentication flow as the service provider. First, you need to set up Yokoy application as web application in your identity provider with authorization code flow (client secret required). You need to specify the callback URL (and sign-in URL, if required).
| Callback URL | Sign-in URL |
Production | https://app.yokoy.ai | |
Sandbox |
Once done, enter the following information in Admin > Organization, Authentication tab.
Field | Description |
Issuer | URL pointing to well-known OpenID discovery document. |
Client ID | Unique ID that identifies the IdP. |
Client secret | Key used for authentication. This is required as Yokoy uses authorization code flow |
Authentication app name | Name of the IdP. This label is used on the sign-in button. For example, if you enter GSuite, the button label is Sign in with GSuite. |
SSO using SAML 2.0 protocol
Yokoy supports both identity provider and service provider initiated authentication flows. You can configure service provider-initiated flows in Yokoy as organization admin.
✏️ Note
Identity provider-initiated flows need to be set up by Yokoy.
The primary email address is used as claim. Other attributes can be used as the IdP claim on request. However, this set up must be done by Yokoy. If you require an attribute that is not an email address, then contact Yokoy.
💡 Tip
If you want specific instructions for your identity provider, check out these guides:
If you don’t see a specific guide for your system, you can still configure Yokoy. Make sure to follow the general steps provided in one of the guides.
For service provider-initiated flows, Yokoy is responsible for initiating the authentication process. Yokoy provides the SP entity ID and ACS URLs that you need to configure your identity provider setup.
Field | Description |
SP entity ID | Yokoy automatically generates this value when adding a new SAML authentication provider. Usually, it takes the format of https://auth.yokoy.ai/ |
Assertion Consumer Service (ACS) URL | Yokoy automatically generates this value when adding a new SAML authentication provider. Usually, it takes the format of https://auth.yokoy.ai/ |
✏️ Note
[tenantId] is created for each organization individually.
Once you have these values, you can start to configure your identity provider. You set up a Yokoy application as SAML web application with the ACS URL & SP entity ID. You need to create a new certificate (X509) and then download the metadata.xml file (contains all the required information). Alternatively, you can use X509 public key (certificate) and login URL.
Once you have this information, you can finish the configuration in Yokoy, Admin > Organization, Authentication tab.
Field | Description |
Certificate | ○X509 certificate. Make sure that there are no line breaks or any XML brackets. |
IdP login URL | Well-known URL for SSO (also known as OPost binding SSO URL). |
Button text | Enter a text that is used for the button displayed on the Yokoy sign in page. This text is prefixed with Sign in with. |
