Company sign-in (SSO)

Company sign-in lets a team’s members sign in to ZestSSH through your company’s identity provider, such as Okta, Microsoft Entra ID or Google Workspace. It answers only for addresses at domains the team has proven it owns.

Setting it up takes four steps: prove a domain, connect the provider, test a sign-in, turn it on. To make members use it, turn on the Company sign-in required rule.

Before you start

You are an owner of the team. The Sign-in page is for owners only.
The team has Business. Setting up, changing, testing and turning on company sign-in need it to be active. On a computer, an owner gets it from the Seats page: Buy seats opens zestssh.com, where Business is too. For what it costs, see Seats and Business. Signing in through company sign-in once it is on does not depend on Business.
You can add a TXT record to your company’s DNS.
You can create a SAML or OIDC app in your identity provider.

Each change to company sign-in needs a sign-in from the last ten minutes. If ZestSSH asks you to Confirm it’s you, choose Sign in again.

On a computer: open the team, choose Team in the rail, then Sign-in.
On a phone: open More, tap the team under Team, then tap Sign-in.

The page says “Company sign-in and directory sync for your own domains. A proven domain unlocks the steps after it.” It has three steps, one under the other:

Prove your domains.
Company sign-in (SSO).
Directory sync (SCIM). See Directory sync (SCIM).

A step that waits shows a lock and what it waits for: “Unlocks when northwind.example is proven.” (or “Unlocks when a domain is proven.”), and, while the team has no Business, Needs Business and “Business is not on for this team.” with See Business, which opens the Seats page. A step that is done shows a check, and still shows what it set up.

Step 1: Prove a domain

Under Prove your domains, type the domain your company’s addresses use, for example northwind.example, and choose Add. To add more, type the next one where it says Add another domain.
The domain shows Waiting for its DNS record and “Add this TXT record where you manage DNS for northwind.example:”, with the record in three parts: Type (TXT), Name (the domain) and Value, zestssh-verify= followed by 24 characters. Each part has a copy button.
In your DNS, add a TXT record with that exact value on the domain itself: for northwind.example, on northwind.example, not on a subdomain. A value your DNS splits into several strings still counts.
Choose Check now. Once ZestSSH Cloud finds the record you see northwind.example is proven, and the domain shows Proven on with the date.

If the record is not there yet you see The record isn’t there yet. DNS changes can take a while to spread, so try again in a few minutes., and the domain says when it was last checked and that the record was not found yet.

Keep the TXT record in place. ZestSSH Cloud checks every proven domain again once a day. When three checks in a row miss the record, the domain is no longer proven and shows Waiting for its DNS record again. Company sign-in stops working for its addresses until you prove it again.

Limits:

A team can claim up to 20 domains.
Only one team can prove a domain. Any other sees Another team has already proven this domain.
At most 30 claims and checks an hour.
Removing a proven domain with Remove domain needs a recent sign-in. Company sign-in then stops working for addresses at that domain until it is proven again.

What a proven domain changes

Company sign-in and directory sync answer only for addresses at proven domains.
Once a team has a proven domain, anyone whose address is elsewhere is a guest. Only owners invite guests, always with an end date. See Guests.

Proven domains are not the Allowed email domains rule. That rule needs no proof and decides whose accounts may sync the team. Proven domains decide which addresses company sign-in may answer for.

Step 2: Connect your identity provider

In step 2, Company sign-in (SSO), choose SAML or OIDC. The box Give your identity provider these lists what your provider needs from ZestSSH, each with a copy button. Copy the values from the app: they are made for your team.

SAML

Give your identity provider:

In the app	What it is
Reply URL (ACS)	Where the provider sends its answer: the Assertion Consumer Service URL.
Entity ID (audience)	Who is asking. It starts with `urn:zestssh:orchard:`.

Then fill in:

Field	What to enter
Name people see	The name of this sign-in, for example “Northwind sign-in”.
Sign-in URL (SSO URL)	The provider’s single sign-on URL. It must start with `https://`.
Identity provider entity ID	The provider’s entity ID.
Signing certificate (PEM)	The provider’s signing certificate, from `-----BEGIN CERTIFICATE-----` to `-----END CERTIFICATE-----`. A certificate that has run out is refused.

OIDC

Give your identity provider the Redirect URI. ZestSSH uses the authorization code flow, so create an app with a client secret.

Then fill in:

Field	What to enter
Name people see	The name of this sign-in.
Issuer URL	The provider’s issuer. It must start with `https://`.
Client ID	The app’s client ID.
Client secret	The app’s client secret.

Save

Choose Save. ZestSSH Cloud registers the provider with Identity Platform, the sign-in service behind ZestSSH accounts, and you see Saved. Test a sign-in, then turn it on. The status reads Set up. Test a sign-in, then turn it on.

ZestSSH Cloud keeps nothing secret. The OIDC client secret goes to Identity Platform only. A SAML certificate is kept as its fingerprint and the date it runs out. The page shows Certificate valid until that date, and from 30 days before it The certificate runs out on … Paste the new one from your identity provider.

Choose Test a sign-in.
Sign in with an address at a proven domain. On Windows and Linux, this happens in your browser. The test does not change who is signed in on this device.
When it works you see Company sign-in works, with the address your provider sent. The status reads Tested. Turn it on when you are ready.

The test fails with That address is not at one of your proven domains. when the provider answers with an address elsewhere. It fails with ZestSSH Cloud’s sign-in check didn’t see this sign-in, so it can’t count as the test yet. when the sign-in gate did not see the sign-in. Try again in a few minutes.

Step 4: Turn it on

Choose Turn on. You see Company sign-in is on, and the status reads On. People at northwind.example can sign in with SSO. From then on, Sign in with SSO finds your company sign-in from a work address at a proven domain.

Turning it on does not make anyone use it. To require it, turn on the Company sign-in required rule.

Change it later

Change the fields and choose Save again. Leave Signing certificate (PEM) or Client secret empty to keep the saved one. The fields say Leave empty to keep the saved certificate and Leave empty to keep the saved secret.

Remove it

Choose Remove, read Remove company sign-in? and confirm. People can no longer sign in through it, and anyone signed in through it, on a phone or a computer, has to sign in again another way, you included.

Removing is refused while the rules require company sign-in: The rules require company sign-in. Turn that rule off first.
Removing needs a recent sign-in.

On a phone, a tablet or a Mac

On the sign-in sheet, choose Sign in with SSO.
Enter your Work email, for example robin@northwind.example, and choose Continue.
Your company’s sign-in page opens in a browser. Sign in there.

You see Signed in with Northwind sign-in when it worked. To find your company sign-in, ZestSSH sends ZestSSH Cloud only the domain of your address, never the address itself.

On Windows or Linux

ZestSSH signs you in on the ZestSSH website in your browser. Type your work email there and choose Continue: when your company signs you in, its sign-in opens next by itself (there is no separate SSO button). Any other address goes on to its password. Here too, only the domain of your address is looked up.

If your address already has an account

If your work address already has a ZestSSH account that signs in another way, ZestSSH says You already have an account. Sign in the way you usually do (Continue with Google, Continue with Apple or Continue with email), and company sign-in is added to that account. You see Northwind sign-in now signs you in.

One address is one account. A company sign-in is added only after you signed in to the account yourself, so it can never take an existing account over by its address alone, and your personal space stays yours.

When a team requires it

If a team requires company sign-in and you signed in another way, its banner says Sign in through your company’s SSO to keep syncing it. Choose Sign in with SSO on the banner.

What members may see

Message	What it means
No company sign-in answers for northwind.example. The owner of your company’s team sets it up in ZestSSH, under Team, then Sign-in.	No team has proven that domain with company sign-in turned on.
That company sign-in is not turned on.	It is set up but off, for example just after an owner changed it.
Your company answered with an address outside its domains. Use your work account.	Your provider signed you in with an address at a domain the team has not proven.
ZestSSH Cloud couldn’t check this company sign-in. Try again in a few minutes.	The sign-in gate could not reach ZestSSH Cloud.
Company sign-in did not complete. Try again, or ask your team’s owner to check it.	Any other failure.

Your company controls its provider, and the provider is registered in the one sign-in service that holds every ZestSSH account. A provider can say any address. Without a check, a provider could make a ZestSSH account for an address it does not own, keep a way into it, and use it once the address’s real owner starts using that account.

ZestSSH checks twice:

Before a sign-in completes. Before the sign-in service makes an account, signs one in, or links a provider to one through a team’s provider, it asks ZestSSH Cloud. The answer is yes only when every address the sign-in carries (the account’s address, and the one the provider sent) is at one of that team’s proven domains. Anything but a yes stops the sign-in.
On every request. ZestSSH Cloud counts a sign-in through a team’s provider only while that company sign-in is on, and only for an address at one of the team’s proven domains. A computer’s session is checked the same way as a phone’s. The one exception is a change: a company sign-in that saving turned off still counts for sign-ins made through it before the change, until it is on again. A removed one counts for nobody.

So your provider can only ever sign in addresses at domains your company has proven it owns.

Sign-ins with a password, Google, Apple or Microsoft are not asked about and are never held up.
If ZestSSH Cloud does not answer the check within 4 seconds, the company sign-in stops with ZestSSH Cloud couldn’t check this company sign-in.
The check logs nothing: not the address, not the provider.
A sign-in that passes both checks counts as a verified address, because your company answers for it. No verification email is needed.
An owner’s test sign-in counts only once the check saw it.

It adds nobody to the team. Members still join by invitation or with an invite code, and their keys are still checked before they are let in. To have your directory propose changes, see Directory sync (SCIM).
It does not require itself. Without the Company sign-in required rule, members may still sign in with a password, Google or Apple.
It answers only for proven domains. People at other domains sign in their usual way. While the Company sign-in required rule is on, they cannot meet it, so guests cannot join or sync the team.
One provider per team. A team has one company sign-in, SAML or OIDC.

Troubleshooting for owners

Message	What to do
Prove a domain first: company sign-in answers only for addresses at your proven domains.	Prove a domain under Domains.
Company sign-in and directory sync need Business for this team. An owner can turn it on from the Team page, under Seats.	On a computer, choose Buy seats on the Seats page and get Business on zestssh.com.
Identity Platform did not take these details. Check them and try again.	Check the URLs, the IDs and the certificate.
Check this or This certificate has run out under a field	Correct that field, or paste the provider’s current certificate.
That sign-in did not check out. Try again with an address at your company.	The test sign-in failed. Try again.
Company sign-in can’t be set up on ZestSSH Cloud yet. If this keeps happening, contact ZestSSH support.	The sign-in gate is not in place on ZestSSH Cloud. Contact ZestSSH support.
The rules require company sign-in. Turn that rule off first.	Turn the Company sign-in required rule off, then remove.
Too many changes to company sign-in for now. Try again later.	At most 30 changes an hour, tests included.

An error on the page comes with Copy details, to paste into a support request.

Next steps

Team rules: require company sign-in with Company sign-in required.
Directory sync (SCIM): let your directory take access away.
Approved devices: let members in only from approved devices.
Two-step sign-in: a second factor on the ZestSSH account.