SAML Single Sign-On
Connect your organization's identity provider — Okta, Microsoft Entra ID, Google Workspace, OneLogin, ADFS, Keycloak — over SAML 2.0, add an SSO button to the widget, and optionally require it for your verified domains.
Single sign-on lets your users sign in with your organization's identity provider over SAML 2.0. It is included in the Enterprise plan, and each app has one connection, set up on the app's Single Sign-On page in the dashboard by an owner or admin.
Before you start
Single sign-on only signs in email addresses at your app's verified domains, so verify your organization's domain first. Without this rule an identity provider could vouch for any address, including a user's at another company.
Setting up the identity provider
Create a SAML application in your identity provider with the values from the top of the Single Sign-On page:
| Identity provider field | Value |
|---|---|
| Entity ID / Audience | https://embedauth.com/api/embed/auth/sso/<clientId>/metadata |
| ACS URL / Reply URL / Single sign-on URL | https://embedauth.com/api/embed/auth/sso/<clientId>/acs |
| Metadata URL (if it can import one) | the Entity ID above |
Then make sure it:
- sends the user's email address as the NameID (email format), or as an attribute named
email(Microsoft'semailaddressclaim andmailwork too); - signs the assertion, the response, or both, with SHA-256 (SHA-1 is refused);
- does not encrypt the assertion.
A display name, if sent as displayName, name, or firstName and lastName, becomes the new user's name.
Connecting it
Paste the identity provider's metadata XML into the page and press Read metadata to fill in its entity ID, sign-in URL and signing certificate — or enter the three yourself. Choose the button's label, switch single sign-on on and save. The widget then shows the button above its other sign-in options.
How a sign-in works
The button opens a popup at your identity provider. When the user signs in there, the identity provider posts a signed response back to EmbedAuth, which checks it and hands the session to the widget — or to your success redirect — like a Google sign-in.
A user is matched by their identity provider ID first, then by email address; an existing account with that address is linked rather than duplicated. A new user's account is created on their first sign-in, unless your app has sign-ups turned off. Two-factor sign-in is not asked for on top: your identity provider owns the second factor.
Requiring single sign-on
Tick Require single sign-on for verified domains to make it the only way in for users at your verified domains. Their password, magic-link, email-code, Google and Discord sign-ins — and sign-ups — are then refused with a message pointing them to the SSO button. Everyone else is unaffected.
What is checked
Every response must be signed by the certificate saved on the page — the one inside the response is ignored — with an enveloped XML signature using exclusive canonicalization and RSA with SHA-256 or SHA-512. It must hold exactly one assertion, issued by your identity provider's entity ID, for this app's entity ID and ACS URL, in answer to the request the sign-in started with, and within its validity period (three minutes of clock difference are tolerated). Each response signs in once. Sign-ins started from the identity provider's own portal (IdP-initiated) are not accepted.
Changes to the connection are recorded in your audit log.