Single sign-on with SAML

Pilot

Company single sign-on is currently enabled only for pilot organizations. It is not generally available yet. SAML is offered only when Workify360 has enabled SAML for the service; until then the wizard shows no SAML option and a SAML connection is refused (sso_saml_not_configured).

Besides OpenID Connect, Focus accepts identity providers that speak SAML 2.0, such as Active Directory Federation Services (ADFS), Microsoft Entra ID, Okta, OneLogin or Keycloak. Company single sign-on, SAML included, is part of the Premium plan. Read single sign-on first: adding people on their first sign-in, two-step verification and how quickly access ends work the same way for SAML.

Before you start

• You are the owner of the organization, and your organization has a verified domain (domain verification).
• Your identity provider can export its SAML metadata as an XML file or publish it at an https address.
• The identity provider sends a persistent NameID that never changes for a person, and the attributes email, firstName and lastName.

What to register at the identity provider

Create a SAML application (a relying party trust in ADFS) with these values:

Value at the identity provider	Value for Workify360 Focus
Entity ID (audience, identifier)	https://auth.focus.workify360.com/sso/saml
Assertion consumer service (ACS, reply URL)	https://auth.focus.workify360.com/sso/saml/api/oauth/saml
Service provider metadata	https://auth.focus.workify360.com/sso/saml/.well-known/sp-metadata
Signing certificate of the service provider	https://auth.focus.workify360.com/sso/saml/.well-known/saml.cer
NameID format	Persistent
Attributes	email, firstName, lastName

Many identity providers can read the service provider metadata address and fill in the other values themselves. The connection card in Focus shows the same values with copy buttons after you save the connection.

Sign-in always starts at Focus. Sign-in started at the identity provider (IdP-initiated) is not accepted.

Add the connection

1. Open Settings → Security → Single sign-on and choose Add connection.
2. Choose SAML as the provider and enter the name shown on the sign-in page.
3. Upload the identity provider’s metadata XML, or enter its metadata address. Focus checks that it is SAML metadata of an identity provider and at most 1 MB (saml_metadata_invalid).
4. Choose whether people who sign in for the first time are added, with which role and team, as for any connection.
5. Save. The connection is draft, and its card shows the identity provider’s entity ID and when its signing certificate expires.

Test, then activate

Choose Test connection and sign in at your identity provider with an account of a verified domain. The test page shows the checks and the attributes the identity provider sent, and warns you when the NameID is not persistent. After a passed test the connection is testing; choose Activate to let people sign in with it (sso_test_required).

New metadata, such as a new signing certificate, takes the connection back to draft and needs a new test; disable an active connection first (sso_connection_active). Renew the certificate at the identity provider before the expiry date the card shows, and upload the new metadata. An organization can have up to 3 connections, SAML and OpenID Connect together (sso_connection_limit).

How it works

Focus signs people in through a SAML service that Workify360 runs on its own private network, and the identity provider only ever talks to auth.focus.workify360.com. The identity provider’s signature, the audience, the recipient, the validity time and the one-time use of every answer are checked before Focus opens a session. When the SAML service cannot be reached, sign-in with SAML fails until it is back (polis_unavailable); other sign-in methods keep working.

To add and remove people automatically from the same identity provider, set up SCIM as well (SCIM provisioning).

Error messages

Code	What to do
saml_metadata_invalid	Upload the identity provider’s metadata XML (an EntityDescriptor with an identity provider part, at most 1 MB), or check that its address can be reached
sso_saml_not_configured	SAML is not enabled for the service yet; use OpenID Connect or contact support@workify360.com
polis_unavailable	The SAML service cannot be reached right now; try again in a few minutes
sso_test_required	Run a successful connection test first
sso_connection_active	Disable the connection before you change it
sso_connection_limit	Your organization has 3 connections; delete one you no longer use