Single sign-on (OpenID Connect)

If the people using your app already sign in to work through an identity provider — Okta, Auth0, Keycloak, OneLogin, Ping, JumpCloud, or a customer’s own — your app can use it too. They get one more button on your sign-in screen, and nobody needs another password.

It works with any provider that speaks OpenID Connect, the standard behind most modern single sign-on. Your app can have one such provider, alongside the Google, Apple and Microsoft buttons.

Turn it on

Open Explorer → Authentication, choose the Single sign-on tab and tick Single sign-on (OpenID Connect). The setup steps appear underneath, with the sign-in redirect URI to give your provider at the top.

If it is not shown yet, your project does not have a web address so far — publish to a server first, then come back.

Set it up in your identity provider

Every provider names things a little differently, but the steps are the same. Whoever runs your identity provider can do this part.

1. Create a new OpenID Connect application of the web application kind — the kind that has a client secret. (In Okta: Applications → Create App Integration → OIDC → Web Application. In Auth0: Applications → Create Application → Regular Web Application. In Keycloak: a client with Client authentication on.)
2. Paste the redirect URI Sapilon showed you as its sign-in redirect URI — some providers call it the callback URL or valid redirect URI. If Sapilon showed you more than one — your own sign-in address, or a Rehearsal Server’s — add them all.
3. Allow the authorization code grant, and the openid, email and profile scopes. Your app needs each person’s email address and name.
4. Assign the people (or groups) who should be able to sign in.
5. Copy the client ID, the client secret and the issuer URL.

The issuer URL is the provider’s own address for this sign-in — for Okta something like https://acme.okta.com, for Auth0 https://acme.eu.auth0.com/, for Keycloak https://keycloak.acme.com/realms/acme. You can check you have the right one: adding /.well-known/openid-configuration to the end of it opens a page of settings whose issuer line is the same address.

Paste them back into Sapilon

Back on the Authentication page, fill in:

• Button name — what the button on your sign-in screen says, for example Acme SSO or Sign in with Okta. Up to 32 letters, digits and spaces; it cannot be the name of one of the built-in providers.
• Issuer URL, Client ID and Client secret from your provider.

When you click Save, Sapilon reads the issuer’s settings page to make sure it is reachable and really is the issuer. If something is off — a typo, an address that is not public, an issuer that calls itself by another address — it tells you then, instead of your publish failing later.

The client secret is stored encrypted and is never shown again. Replace lets you change any of the four values (you will need to paste the secret again); Remove deletes them all.

Publish

Nothing changes on your live app until you publish. The button is added to your sign-in screen as part of publishing. If single sign-on is on but its details are missing, publishing stops and tells you so.

Pressing Apply on the Authentication page only saves the setting. The Publish page then lists it under What’s new for each server that doesn’t have it yet, and lets you publish even if nothing else in your app changed. Publish to Rehearsal and Live separately.

Questions people ask

Sign-in fails with a message about a missing attribute. Your app needs an email address and a name for everyone. Check that your provider shares the email and profile scopes, and that the person has both filled in.

Can I use SAML instead? Not yet — only OpenID Connect. Most providers that offer SAML offer OpenID Connect too.

Can I connect more than one identity provider? One for now, beside Google, Apple and Microsoft.

Does the secret expire? That depends on your provider. If it does, create a new one there, use Replace on the Authentication page, and publish.

Someone signed in through single sign-on — which group are they in? The default group you picked under Groups on the same page, exactly as if they had signed up with an email address.