Single sign-on

Single sign-on lets people at your company’s domains sign in to Jiayang Cloud through your own identity provider: Okta, Microsoft Entra ID, Google Workspace, or any provider that speaks SAML 2.0 or OpenID Connect. You can then require it, so nobody in your workspace opens its apps or its dashboard any other way.

Owners set it up in the dashboard, under the workspace’s Settings, in Single sign-on. Only owners can see it or change it, since it speaks for everyone at your domains. Changing it asks for a sign-in from the last 15 minutes. jiayang sso acme opens that page in your browser. jiayang sso acme --status shows the provider, who has to use it and your domains, and jiayang scim acme --status whether your provider’s SCIM token works, never the token. An agent reads the same with sso_status and scim_status. A CLI session can’t change either, since they decide who signs in.

Plans

Single sign-on and SCIM are Enterprise features. They’re included on Business for early customers, for a limited time. On Free and Team the Single sign-on section says which plans have them, and the API refuses with 403 plan_limit. After an upgrade to Business, they’re there once the upgrade is paid for.

If your workspace moves to a plan without them, after a downgrade or a failed payment, nothing you set up stops working. Your provider still signs people in, and if you require it, everyone it covers still has to use it. You can’t change the provider, add a domain or require it for more people, but you can always require it for fewer, from everyone down to members, or turn the requirement off, remove a domain or remove the provider. Your SCIM token keeps working for deactivating and deleting users, so your provider can still take people away. It can’t add anyone, or change someone who stays active, and you can’t make a new token. You can revoke it.

Changing the provider includes a new SAML signing certificate or a new OpenID Connect client secret. So on a plan without single sign-on, you can’t rotate either. Before one expires, turn the requirement off, so people can still sign in the other ways, or move back to a plan with single sign-on.

Prove your domains

Your provider can only sign in addresses at domains your workspace has proved it holds.

1. Under Prove your domains, enter a domain, such as example.com, and choose Add domain.
2. Add the TXT record it shows to your DNS. Its name is _jiayang-verify.example.com and its value starts with jiayang-verify=.
3. Choose Check the record. DNS changes can take a few minutes to show.

A domain can be held by one workspace at a time. Until a domain is proved, nobody is sent to your provider. Add each domain your people’s addresses use. A subdomain like eu.example.com is a domain of its own. A mail provider’s domain that anyone can get an address at, like gmail.com, can’t be added, nor can a mail testing service’s, like resend.dev, which nobody but that service can prove, and nor can a suffix anyone registers names under, like co.uk, or a name under no suffix anyone can register, like acme.internal.

Connect your provider

Make an app for Jiayang Cloud in your provider, then fill in what it gives you. The dashboard shows the values your provider asks for, ready to copy.

SAML 2.0

Give your provider:

• ACS URL (also called the reply URL): https://app.jiayang.cloud/v1/auth/sso/<id>/saml
• Entity ID (also called the audience): https://app.jiayang.cloud/v1/auth/sso/<id>
• Name ID: the person’s email address. You can send it as an email attribute instead.

Or point it at our metadata, https://app.jiayang.cloud/v1/auth/sso/<id>/metadata.

Then paste your provider’s metadata XML into the dashboard. You can enter its entity ID, its sign-in URL for the HTTP-Redirect binding and its signing certificate instead.

Assertions have to be signed with that certificate, and name our entity ID as their audience. We refuse an answer that isn’t signed, is signed by another key, is meant for another service, or has expired, and each assertion works once.

OpenID Connect

Give your provider the Redirect URI: https://app.jiayang.cloud/v1/auth/sso/<id>/callback. Then enter its issuer URL, the client ID and the client secret. We read the issuer’s discovery document when you save, and keep the secret encrypted. It never comes back to the dashboard.

The provider’s ID token has to carry the person’s email.

Test it

Choose Test sign-in. You go to your provider and come back signed in through it. Do this before you require it: we only let you require single sign-on from a session your provider made. Test sign-in works once you’ve proved a domain, since your provider can only sign in addresses at proved domains.

Changing the provider’s settings stops requiring it until you test again. Changing to a different provider also signs out everyone the old one signed in, and unlinks their accounts from it. Adding a new SAML signing certificate beside the current one, to rotate it, doesn’t.

Require it

Under Require it, choose who has to sign in through your provider:

• Nobody yet. People can still sign in the other ways: with a code by email, with a passkey, and with Google or Microsoft where we offer them. The dashboard names the ones that are on.
• Members of this workspace, and anyone at its domains.
• Everyone who opens this workspace’s apps, people outside your domains included. Someone outside your domains can’t sign in through your provider, so this keeps them out.

Once it’s on, a session made any other way, a passkey included, can’t open the workspace’s dashboard or its apps. The app’s own session ends within 60 seconds and the browser goes back to sign in. A CLI session counts as however the browser that approved it signed in. Sessions in other workspaces aren’t affected.

Bypass tokens and agents’ credentials count as however the session that made them signed in. Once the rule covers whoever made one, a token or credential made on a session your provider didn’t make stops working, as that session does. Make new ones after signing in through your provider. Webhooks and Slack can tell you each time the rule changes: see the sso.* events in Webhooks.

Owners can always reach Single sign-on in the dashboard, however they signed in, to fix a provider that stops working.

After the workspace is deleted

While a deleted workspace that requires single sign-on can still be restored, its owners can still sign in through your provider, to restore it or delete it for good. On the sign-in page, choose Restore a deleted workspace and type your work address. Your provider asks you to sign in again, and you land on the deleted workspaces you can restore.

That sign-in is for nothing else. It can’t open the dashboard’s other pages or any app, approve the CLI or an AI client, add a passkey, or make a token. It lasts an hour at most, and ends as soon as the workspace is restored or deleted for good, you sign out, any of your other sessions in a browser or the CLI is signed out, or we sign you out everywhere. That last one ends it even when you have no other session left. Members who aren’t owners can’t sign in this way. The audit log has an sso.kept_sign_in entry for each one.

We email you each time one is made, and it’s listed on your Sessions page, marked Deleted workspace, where you can revoke it on its own. Deleting a workspace for good needs a sign-in from the last 15 minutes, so after that your provider asks you to sign in again, and you come back to the same page.

Signing in

On the sign-in page, people type their work address as usual. If its domain has a provider, they go there instead of getting a code. The first sign-in links their provider account to the Jiayang Cloud account at that address, or makes one.

Provisioning with SCIM

Your provider can add people to the workspace, and remove them when they leave, over SCIM 2.0. Under Provisioning (SCIM), choose Make a token, then give your provider:

• SCIM base URL: https://api.jiayang.cloud/scim/v2
• Token: the one shown, as a bearer token. It’s shown once. Make a new token replaces it, and asks first, since your provider stops syncing until it has the new one.

Only owners see the token, or make or revoke one. jiayang scim acme opens the page in your browser.

What it does:

• A user it creates, or makes active, becomes a member of the workspace by their email address (userName). Someone already a member keeps their role. Someone new gets an email from us saying their company’s identity provider added them, and how they sign in. Someone it brings back gets one saying their access is back.
• A user it makes inactive, or deletes, stops being a member. If their address is at one of your domains, every session they have ends too, in every workspace: your company says they’ve left.
• Someone it added whom you remove by hand, on the Members page or with jiayang workspace remove, is out at once. Your provider still has them as active, though, and reading them over SCIM says so: the next time it updates them, they’re added back. To keep someone out, unassign them in your provider.
• It supports finding users with filter=userName eq "…" or externalId eq "…", and PATCH as Okta and Microsoft Entra ID send it. It keeps displayName and the name your provider sends, given and family names included, and gives them back as they were sent.
• /ServiceProviderConfig, /ResourceTypes and /Schemas say what it supports.
• It keeps groups too. See Groups.

The token acts as the owner who made it. It stops working if they stop being an owner, and Provisioning (SCIM) then says so: make a new one and give it to your provider. It also stops working a year after it was made. Provisioning (SCIM) shows the date, and the workspace’s owners get an email 30 days before and again 7 days before. Make a new one before then: once it ends, your provider can’t add anyone, or remove someone who leaves. Your provider’s log says so too, in the 401 answer to its calls. You can revoke it in Settings. Deleting the workspace revokes it too, and it stays revoked if the workspace is restored. A restored workspace holds everyone your provider added, except the owner who restored it, until your provider confirms them with a new token: until then they can’t open the workspace or its apps, an owner who is held gets none of its email, and the webhooks, audit streams and scheduled jobs they added wait. The Members page marks who is waiting. Your provider confirms someone by looking them up or updating them, which it does when you start provisioning again. An owner or an admin can also let someone in by adding them again, and only an owner can let in an owner. Each is in the audit log as a member.put with let_back_in, marked (SCIM) when your provider did it. Once single sign-on is required, only someone signed in through your provider can make one.

Every change to a workspace’s domains, provider, SCIM token, members and groups is in its audit log. A change your provider made, and the invitation email it sent, are marked (SCIM) beside the address of the owner who made the token.

Groups

Your provider can push groups as well as users. Each one it pushes is a workspace group, so you can share an app with it, or have it give a custom role. Your provider then decides who opens the app, or who holds the role.

• A group it makes gets a short name from its own: “Finance Team” becomes finance-team. A name another group already has, or that is another group’s short name, in any case, is refused as taken, whether your provider makes the group or renames one to it. jiayang share --group and the dashboard use the short name. Renaming the group in your provider keeps the short name, so nothing shared with it breaks.
• Its members are the users your provider pushed, by their ids. Someone your provider made inactive isn’t put in a group.
• Someone taken out of the group in your provider loses what it gave them within 60 seconds, open connections too, as when an owner takes them out here. A user your provider deactivates, deletes or gives a new address leaves every group too. A new address keeps the old one’s groups.
• A group made here first is found by its name, in any case, so your provider can link to it. From its first change, your provider keeps it: the dashboard and jiayang group add can’t change who is in it, and say so. A replace of its members takes out anyone your provider didn’t name, people added here by address included.
• It supports finding groups with filter=displayName eq "…", externalId eq "…", id eq "…", and with and members eq "…", and excludedAttributes=members. It takes PATCH as Okta and Microsoft Entra ID send it: members added, taken out by value or by members[value eq "…"], replaced, and the group renamed.
• Deleting the group in your provider deletes it here, and every share it had.

A group has up to 500 people, and a workspace up to 100 groups.

On a plan without SCIM, your provider can still take people out of groups and delete them. Making, renaming or filling one is refused.

When we refuse a change, we answer your provider with an error whose detail says why, in the words the dashboard uses, so your provider’s log tells you what to fix. Nothing about the user changes: reading them back shows them as they were.

When your provider deactivates or deletes someone who is the only owner of an app, or the workspace’s only owner, we keep them in the workspace and the error names what’s in the way. If their address is at one of your domains, we end their sessions anyway. Give the app or the workspace another owner, and the provider’s next try removes them.