Skip to main content
owlie
Sign Up Free

Configure SAML SSO

Who this is for​

Tenant administrators connecting an external SAML 2.0 identity provider to Owlie sign-in.

Goal​

Register the tenant-specific Owlie service provider (SP), import the IdP trust configuration, and complete an SP-initiated test login.

Prereqs​

  • Administrator access to Owlie and the identity provider
  • A verified email domain used by the people who will sign in
  • A tested emergency access method before removing local login

Success criteria​

The Owlie login page shows the configured label, the IdP posts to the tenant-specific ACS URL, Owlie completes the same-browser return, and a session is created after the tenant's normal MFA and post-login policy.

Register Owlie in the IdP​

  1. In Owlie, open Tenant Settings → Authentication → Login methods.
  2. In SAML 2.0, copy SP metadata URL, Assertion Consumer Service (ACS) URL, and SP entity ID. The metadata URL works before SAML is enabled.
  3. Create a SAML 2.0 application in the IdP. Use the copied ACS URL as its reply/consumer URL and SP entity ID as its audience/entity ID.
  4. Configure NameID as the user's email address. Owlie accepts the SAML emailAddress and unspecified formats; an omitted Format is treated as unspecified.
  5. Assign a test user, then obtain the IdP metadata URL or its entity ID, SSO URL, and public signing certificate.

Use the provider-specific procedure for Okta, Microsoft Entra ID, or Google Workspace.

Configure Owlie​

  1. Turn on SAML SSO and set the Display label shown on the login page.
  2. Add one or more Allowed domains.
  3. Under Configuration source, choose Metadata URL or Manual entry.
  4. For metadata, enter the HTTPS Metadata URL and select Fetch metadata. In Confirm SAML metadata trust, compare current and incoming IdP entity ID and SSO host, then review every certificate's SHA-256 fingerprint, subject, and expiry. Select Confirm and save trust only when all values belong to the IdP. Owlie re-fetches before saving and refuses the commit if the proposed trust changed. Owlie does not verify metadata XML signatures in v1; HTTPS plus this explicit confirmation is the deliberate trust model.
  5. For manual entry, enter IdP entity ID, IdP SSO URL, and at least one PEM Signing certificate. Add overlapping certificates during IdP rotation. At sign-in, Owlie skips an expired or otherwise unusable certificate while a valid sibling remains available.
  6. Set Attribute mapping only when the IdP does not send common email/name attributes. Email is required; display, first, last, and picture claims are optional. A pinned mapping reads only that attribute and does not fall back to Owlie's built-in aliases.
  7. Decide whether to enable Trust IdP-asserted email and Just-in-time provisioning. Disable asserted-email trust when the IdP cannot guarantee verified addresses.
  8. Leave Clock skew (seconds) at its default unless the IdP's clocks require a bounded allowance, then select Save changes.
  9. In a private browser window, open https://<tenant>.<root-domain>/auth/login, choose the SAML label, and complete sign-in with the assigned test user.

Default configuration​

  • SP-initiated sign-in, 60 seconds of clock skew, no JIT provisioning, and no attribute overrides.
  • Existing local login remains available unless the tenant deliberately configures SSO-only access.

When to change it​

  • Enable JIT only when the IdP and allowed domains are authoritative for who may enter the tenant.
  • Add attribute overrides when a successful assertion lacks the expected profile values.
  • Select Refresh metadata during a planned IdP certificate or endpoint rotation; refresh is not automatic.

If the IdP reissues NameIDs without changing its entity ID, open Tenant Settings → Authentication → Login methods → SAML 2.0 and choose Reset SAML links. After the locally-held-factor check, confirm Reset all links. Owlie deletes every SAML link for the tenant; the audit log records the actor and number reset. Users eligible under the asserted-email policy establish new links on later sign-in.

This is not an identity merge. When Trust IdP-asserted email is disabled, a user whose email already belongs to an unlinked Owlie identity is rejected after reset instead of linked. The action also cannot merge a duplicate identity. Those cases need a future administrator-approved relink/merge workflow; Owlie does not provide one today.

Impact and risks​

  • A wrong allowed domain, NameID, audience, ACS URL, or certificate blocks sign-in.
  • SSO-only configuration can lock out administrators if the IdP is unavailable; prepare emergency access first.
  • Metadata origin compromise or mistaken administrator confirmation can replace the trusted IdP endpoint or signing certificates.
  • Changing any login-method configuration, refreshing SAML trust, or resetting SAML links requires a locally-held factor: an enrolled second factor, or emergency recovery when none is enrolled. A SAML sign-in, API key, or impersonated session cannot satisfy this gate.

Example​

For tenant acme, copy the values shown in the SAML panel, allow example.com, map NameID to the user's primary email, and test with admin@example.com before assigning the application broadly.

Troubleshooting​

  • Authentication failed: confirm the IdP signs the response or assertion, sends exactly one assertion, and uses the current Owlie certificate trust and audience values.
  • Domain rejected: add the email suffix to Allowed domains or correct the asserted email.
  • Login loops or expires: start again from the Owlie login page; IdP-initiated app-tile launches are not supported. Do not block either flow cookie: the ACS POST is followed automatically by a same-site completion that requires the flow-start cookie and the short-lived token issued to the browser returning from the IdP.
  • Metadata refresh fails: confirm the URL is HTTPS, directly returns SAML metadata without a redirect, and exposes no more than five unique signing keys with usable leaf X.509 certificates. If it changed after preview, review the new preview and confirm again.

Assumptions & Questions​

  • Provider console labels change independently of Owlie. Confirm the current vendor-specific path before a production rollout.

Next steps​