SAML single sign-on for Eklo: Okta, Entra ID, Google Workspace

Eklo, the workspace church staff use for requests, tasks and chat, supports SAML 2.0 single sign-on. Once it's set up, people at your church's email domain sign in through your identity provider (IdP) instead of with an emailed code. Step-by-step guides:

• Okta
• Microsoft Entra ID
• Google Workspace

Before you startCopy Anchor Link

• You need to be the workspace owner or an admin.
• Verify your email domain first. In Settings → Single sign-on → Email domain, enter your domain (for example firstbaptist.org) and click Claim domain. Publish the eklo-verify=… TXT record with your DNS provider, then click Check now. The domain shows Verified once Eklo finds the record. A SAML connection only signs in addresses at your verified domains. Until a domain is verified, nobody can use it.

Set up the connectionCopy Anchor Link

1. Open Settings → Single sign-on. Under SAML connection, Eklo shows two values for your IdP:
   • Entity ID (Audience URI), which identifies Eklo to your IdP.
   • ACS URL (Reply / Single sign-on URL), where your IdP sends people after they sign in.
2. Create a SAML app in your IdP with those values. The provider guides above go through each screen.
3. Back in Eklo, tell it about your IdP in one of three ways:
   • Metadata URL: Eklo fetches the IdP's metadata. The URL must be https and publicly reachable.
   • Metadata file: paste the XML or choose the file you downloaded.
   • Enter manually: the IdP's entity ID (issuer), its sign-in URL (HTTP-Redirect binding) and its signing certificate.
4. Set the attributes if your IdP doesn't use the defaults:
   • Email: Eklo reads the email attribute, then the NameID.
   • Name: Eklo reads givenName and surname, then displayName.
5. Click Save connection. Eklo's own SAML metadata is now available from Download Eklo's SAML metadata, if your IdP prefers to import it.
6. Test from a private browser window: go to the Eklo sign-in page, enter an address at your domain, and choose Continue with single sign-on.

How sign-in worksCopy Anchor Link

• Start at Eklo. People enter their email on the Eklo sign-in page, and Eklo sends them to your IdP. Sign-in that starts from an IdP dashboard tile isn't accepted, because Eklo only accepts a response to a sign-in request it made. Each guide says how to point the tile at Eklo or hide it.
• Codes still work until you require SSO. Until Require SSO is on, the sign-in page also offers Email me a sign-in code instead.
• New people are added automatically. The first time someone signs in through SSO, Eklo creates their account and adds them to your workspace as a Member. Change their role on the People page as usual.
• When someone leaves, remove them in Eklo. They stay out until you invite them back: signing in through your IdP, or with Google at your domain, doesn't add them again. The same goes for someone who leaves your workspace themselves. If they delete their Eklo account and sign up again, they count as a new person, so to keep someone out for good, also unassign them from Eklo in your IdP (on Google Workspace, suspend their Google account). Eklo doesn't remove people automatically when your IdP does.
• Existing accounts are linked. If someone already used an emailed code with the same address, SSO signs them into that same account.
• Only your domains. Your connection signs in addresses at your verified domains, nothing else. Another workspace's IdP can't sign anyone into yours.
• Eklo checks each response's signature, audience, recipient and validity window (allowing two minutes of clock difference), and accepts each sign-in request once.

Require SSOCopy Anchor Link

Turn on Require SSO for a verified domain to make SSO the only way in for addresses at that domain:

• Emailed codes and sign-in links are refused, with a message that points people to single sign-on. Passkeys are refused too.
• When you turn it on, everyone at the domain who is signed in another way is signed out immediately, except the workspace owner.
• Without a SAML connection, Require SSO means signing in with Google for that domain.
• You can't remove the SAML connection while any domain requires SSO. Turn Require SSO off first.

Owner emergency accessCopy Anchor Link

If your IdP is down or misconfigured while Require SSO is on, the workspace owner can still get in. On the sign-in page, after entering their email, the owner chooses Email me an emergency code (under "Workspace owner and can't reach your identity provider?"). Only the owner receives a code; anyone else who tries gets the same "sent" screen and no email.

Eklo records every emergency sign-in in its own internal log, with the owner, the workspace, the time and the IP address. That log is Eklo's record; churches can't view it. Treat it as a break-glass path: fix the IdP, then sign in through SSO again.

CertificatesCopy Anchor Link

The connection shows the IdP's signing certificate fingerprint and expiry date, highlighted when it's within 30 days. When your IdP rotates its certificate, click Update connection and save it again (re-fetch the metadata URL, upload the new file, or paste the new certificate). With metadata, Eklo trusts every signing certificate the metadata lists, so you can add the new certificate in your IdP before you switch to it.

TroubleshootingCopy Anchor Link

When SSO fails, the sign-in page shows "Single sign-on didn't work:" followed by one of these: