SAML Single Sign-On (SSO)

SAML Single Sign-On lets the members of your organization sign in to the Obkio App with your own identity provider, such as Okta, Microsoft Entra ID, Auth0 or Google Workspace. Authentication happens at your identity provider, so your own password policies, multi-factor authentication and access rules apply.

SAML SSO is different from SSO Login with Google or Microsoft. That is a choice each user makes for themselves. SAML SSO is configured once for the whole organization by an org admin, and can be required for every member.

SAML connects your identity provider to accounts that already exist in your organization. It does not create new users. Invite people first, as described in Organizations and Users, and their SAML sign-in will link to the account they already have.

You will need:

• An org admin role in the organization.
• Admin access to your identity provider, to create a SAML application.
• The ability to add a DNS TXT record for your email domain, to prove you own it.

The SAML settings are found in the Organization settings (Menu -> Company Name), under Change Organization's Advanced Parameters, in the SAML tab.

In your identity provider, create a new SAML 2.0 application for Obkio.

Obkio's service provider URLs are only generated once the configuration exists in Obkio, so at this stage enter a temporary value for the sign-on and audience URLs. You will replace them in Step 3.

Once the application is created, collect these three values from your identity provider:

• Identity Provider Entity ID (sometimes called Issuer)
• Identity Provider Single Sign-On URL
• X.509 Certificate (the signing certificate)

In the SAML tab, fill in:

• Email Domain: the domain your users sign in with, for example company.com. Only one organization can claim a given domain.
• IdP Entity ID, IdP SSO URL and IdP X.509 Certificate: the three values from Step 1.

All four fields are required, and the configuration is saved once they are all filled in.

Obkio now displays its service provider values. Copy each one into the matching field of your identity provider application:

These two URLs are not the same. The ACS URL ends in /acs/ and the SP Entity ID ends in /metadata/. Entering the same value in both is the most common configuration mistake.

Obkio identifies the user by the email address in the SAML assertion, so your identity provider must send it.

Obkio automatically looks for the attribute names that identity providers commonly use: the standard claim URI http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, the SAML 2.0 OID urn:oid:0.9.2342.19200300.100.1.3, and the short names email, emailaddress and mail.

Some identity providers send no attributes at all unless you add them. In Okta, for example, the Attribute Statements section of the SAML application is empty by default. Add one statement with the value user.email.

If your identity provider uses an attribute name that Obkio does not recognise, enter it in the Email Attribute Name field in the SAML tab. Several names can be given, separated by commas, and Obkio tries each in turn.

Before Obkio accepts any SAML sign-in for your domain, you must prove that you own it. This stops another organization from claiming your domain and pointing it at their own identity provider.

The SAML tab shows the record to publish:

• Record name: _obkio-verification. followed by your email domain
• Type: TXT
• Value: a unique value generated for your organization

Add that record in your DNS, then click Verify domain in Obkio.

DNS changes can take from a few minutes to several hours to publish. If the check does not find the record right away, wait and try again. Until the domain is verified, SAML sign-in is refused and the login page reports that SSO is not configured for your domain.

The email domain cannot be edited once the configuration is saved. To use a different domain, delete the configuration with Delete SAML Configuration and create it again. Verification does not carry over: the new domain has to be verified on its own.

Tick the Enabled checkbox, then test a sign-in as described below. We recommend testing with a second browser or a private window, so that you keep your current session in case anything needs adjusting.

To sign in:

1. Go to https://app.obkio.com
2. Click Continue with SSO
3. Enter your email address
4. You are redirected to your identity provider to authenticate, and returned to Obkio signed in

Obkio only accepts sign-ins that begin at Obkio. Launching the application tile from your identity provider's dashboard, or using a button such as Okta's Test SAML Login, will not work, and this is intentional: a sign-in that Obkio did not initiate cannot be verified as genuine.

If you would like your team to have a tile on their identity provider dashboard, create a bookmark application instead of using the SAML application's own tile, and point it at your organization's Obkio sign-in URL. That URL has the same form as your ACS URL, ending in /login/ instead of /acs/.

You can also hide the SAML application's tile from your users, so that nobody clicks the one that does not work. The application itself stays active, since it is what performs the authentication.

Once SAML SSO is working, you can require it for the organization by ticking Require SAML SSO.

When SSO is required, members can only reach this organization's data with a session obtained through your identity provider. A password or Google or Microsoft sign-in will no longer give access to it. If a member also belongs to other organizations, their access to those is unaffected.

Two safeguards apply:

• The option only becomes available after at least one user has signed in successfully through your identity provider. This prevents an organization from locking itself out behind a configuration that has never worked.
• Turning off Enabled also turns off the requirement.

If your identity provider becomes unavailable after you require SSO, contact Obkio's support team.

SSO is not configured for this email domain

Shown on the login page after Continue with SSO. The domain you entered has no SAML configuration that is both verified and enabled. Complete Step 5 and Step 6, and check that the email domain in the SAML tab is the one your users sign in with.

Third-Party Login Failure

The assertion was rejected before Obkio could read it. Check that the ACS URL and SP Entity ID in your identity provider match the values shown in the SAML tab exactly, and that the X.509 certificate is the current one.

Sign-in works from Obkio but not from the identity provider dashboard

Expected. See Sign-In Must Start at Obkio.

SAML response did not include an email

The assertion arrived without a recognised email attribute. Add an attribute statement in your identity provider, or set the Email Attribute Name field. See Step 4.

Email not authorized for this SAML provider

The address in the assertion is not a member of this organization, or its domain does not match the configured email domain. Invite the user first, as described in Organizations and Users.

This SAML domain has not been verified

Domain verification has not been completed, or the DNS record has been removed. See Step 5.

This field must be unique

Shown under the Email Domain field when saving the configuration. Another organization has already claimed that domain. Contact Obkio's support team.

SAML Single Sign-On availability depends on your subscription plan. Contact Obkio's support team for more details.

Learn more ...