Single Sign-On

Single sign-on lets the people in your organization sign in to Workprentice through the identity provider your company already uses. It speaks SAML 2.0, so it works with Okta, Microsoft Entra ID, Google Workspace, and any other provider that does. It is included on every plan.

Setup has three parts: prove you own your email domain, connect the provider, and, once it works, decide whether to require it. Each provider has its own walkthrough:

• Okta
• Microsoft Entra ID
• Google Workspace

The rest of this page covers what is the same for all of them, and is enough on its own for a provider not listed.

Verify your domain by DNS

Single sign-on signs in people whose email address is at a domain your organization has proven it controls. Open Organization settings → General, find the domain under your organization’s domains, and choose Verify by DNS. Workprentice shows a TXT record:

Field	Value
Name	_workprentice-challenge.<your-domain>
Value	workprentice-domain-verification=…, unique to your organization

Add it at your DNS provider and choose Check record. DNS changes can take a few minutes to appear; if the check fails, wait and check again. The domain then shows DNS verified.

A domain verified only by email, which is what lets teammates join automatically, is not enough for single sign-on. If another organization claimed your domain by email first, verifying by DNS moves the domain to yours and tells that organization’s owners.

Connect your identity provider

Only an organization owner can connect, change, or remove the provider, because whoever names the provider decides who it signs in. Every change emails every owner.

Open Organization settings → Single sign-on. Pick your provider at the top and the page uses that provider’s names for each field.

Create a SAML application at your provider and give it these values from the page:

Workprentice shows	What it is	Also called
Single sign-on URL	Where the provider posts its response	ACS URL, reply URL, recipient
Audience	The name of this application	Entity ID, identifier, audience URI
Start URL	Optional. Where a dashboard tile should send people	Sign-on URL, login URL

Have the provider send each person’s email address, either as the name ID or as an attribute named email. Workprentice also reads mail, emailaddress, user.email, and the emailaddress claim Microsoft sends by default. When an attribute and the name ID both carry an address, the attribute is the one used.

The name ID is what ties a person at the provider to their account here from their first sign-in on, so it has to stay the same for that person. If it changes, by switching it to a different attribute for example, their next sign-in is refused. Settle which attribute it is before people start signing in.

Then enter what the provider gives you back:

Field	What to enter
Issuer	The provider’s entity ID
Sign-in URL	The provider’s SAML sign-in address
Signing certificate	The provider’s X.509 certificate, in PEM form

The provider must sign the response, the assertion, or both. Workprentice does not sign its requests and does not accept encrypted assertions, so leave both of those options off at the provider.

Save, then test it in a private browser window: on the sign-in page, enter your work email and choose Continue with single sign-on.

Who can sign in

A person can sign in through your provider when their email is at one of your DNS-verified domains and the provider lets them use the application.

• Someone who already belongs to your organization is signed in to their existing account.
• Someone new at your domain gets an account in your organization on their first sign-in. They take a seat then, and no earlier. If your organization has reached its seat limit, they wait for a seat instead, and you are told.
• Someone whose email already has an account in a different organization is not signed in. They sign in to that account the way they always have and join yours from an invitation.

Starting from the provider’s dashboard works too. Workprentice does not trust a response it did not ask for, so it sends the browser back through the provider once, which costs one extra redirect.

Require single sign-on

Single sign-on starts as one more way to sign in. To make it the only way, an owner who is signed in through the provider chooses Require single sign-on on the same page. Signing in through it first is what shows that the connection works.

Before it takes effect, Workprentice lists any member whose email is outside your verified domains. Those members will not be able to sign in, apart from owners, who keep the emailed link. The list is a warning and does not stop you, so move those members to a company address or remove them before you confirm.

Once it is required:

• Nobody can sign in with a password or Google, and members can no longer use an emailed link. Sessions started those ways end at the next request.
• Owners can still sign in with an emailed link, and only that, so a problem at the provider cannot lock the organization out. Each time one does, every owner gets an email.
• Invitations to addresses outside your verified domains are refused.
• Workspace API keys, agent tokens, and access a person has granted to an outside application over OAuth are not covered. Each ends when the person who holds it is removed from the organization.

Change or replace the provider

When your provider is about to rotate its signing certificate, paste the new certificate after the old one and save. Both are accepted, and you can remove the old one after the change.

Entering a different issuer replaces the connection. Everyone signed in through the old one is signed out, the requirement is switched off, and an owner has to sign in through the new provider before requiring it again.

When sign-in fails

Message	What it means
Single sign-on is not set up for that email domain	No organization has verified that domain by DNS and connected a provider. Check the address, or finish the two steps above.
Single sign-on could not be completed	The response was refused. The usual causes are a wrong or expired certificate, an Audience or Single sign-on URL that does not match, or a clock more than two minutes off at the provider. It also appears when the provider sends a different name ID for someone who has signed in before, and when the browser blocks the cookie that ties the response to the request.
Your identity provider signed you in, but you do not have access	The email the provider sent is not at a verified domain, an admin removed the person from the organization, or directory provisioning is on and does not list them as active.
Your organization has used all of its seats	The organization reached its seat limit. The person is waiting, the people who manage seats are told, and approving them or adding seats under Members lets them in on their next sign-in.
That email already has an account outside the organization	The person belongs to another organization. They sign in there and accept an invitation to yours.
Your organization requires single sign-on	The person tried another way to sign in. They enter their work email and choose Continue with single sign-on.