EvergreenDocs

Single sign-on and SCIM

Verify your company's domain, connect your identity provider over OpenID Connect or SAML, give roles from its groups, and let it add and remove people for you.

  • Owner · Admin
  • Enterprise
  • 30 minutes

Enterprise

Single sign-on, SCIM, group rules, required single sign-on, and domain capture come with the Enterprise plan. Verified domains and joining by domain come with Pro. An Owner on Pro can switch the workspace to Enterprise under Workspace settings › General. See General.

Setup happens on two pages of Workspace settings. Domains proves you own your email domain, and Sign-in connects your identity provider. Owners and Admins can set it up, and only the Owner can turn it on.

Verify your domain

  1. Add the domain

    On Workspace settings › Domains, choose Add domain and enter the part after the @ in your team’s email addresses. Evergreen refuses free email domains, disposable domains, domains that accept no email, and domains another workspace has already verified.

  2. Add the TXT record

    Evergreen shows a record to add at your DNS provider, under Add this TXT record at your DNS provider:

    Field What to enter
    Type TXT
    Name _evergreen-verify, or _evergreen-verify.<subdomain> for a subdomain
    Value evergreen-verification= followed by the code Evergreen shows you

    Most providers fill in the rest of the name for you. If yours asks for the full name, use _evergreen-verify.<your domain>. When Evergreen recognizes your DNS provider, Set it up with and the provider’s name adds the record for you. Email to IT sends the record to whoever manages your DNS.

  3. Verify

    Choose Verify now. DNS changes can take a few minutes to an hour to show.

Evergreen rechecks a pending domain every hour for seven days, and after that only when you choose Verify now. A verified domain is checked daily. If the record is missing three checks in a row, the domain becomes Lapsed and its settings pause until you add the record again.

Once a domain is verified you can set what happens for people with an address on it:

Setting Choices
Who can create other workspaces with an address on this domain No one (the default), Admins, or Anyone.
Whether people can join without an invitation Invitation only (the default) or Anyone can join.
Whether only this workspace can invite addresses on the domain Off by default.
How people sign in Any way (the default) or Single sign-on only. Needs Enterprise and a provider that’s on.
Where new sign-ups go Their own (the default) or This workspace. Needs Enterprise and a provider that’s on.

Removing a verified domain means your workspace no longer owns it, and another workspace could verify it. While required single sign-on or domain capture is on for a domain, only the Owner can remove it.

People already on your domain

People may have signed up with an address on your domain before you verified it, and have a workspace of their own. A verified domain’s card lists them under People outside this workspace, with how they sign in, when they last signed in, and whether they own a workspace. Send invite invites one of them, and Invite everyone invites them all. Evergreen also emails them, so they can join your workspace or move their account to another address.

If one of them set up a workspace for the company, your Owner can Claim workspace. The workspace moves to your Owner after 14 days unless the person who set it up objects. That person stays on as an Admin, and the workspace’s sessions, projects, and history stay as they are. A workspace’s Owner can also offer it to you. The offer shows under Workspaces coming to your workspace for the Owner to accept or decline, and it lapses after 30 days if nobody answers.

Connect your identity provider

On Workspace settings › Sign-in, choose Set up under Single sign-on. Evergreen walks you through the steps one at a time and saves a draft as you go, so you can stop and pick up later with Finish setup. The terminal has the same walk: evergreen sso setup.

  1. Choose your provider

    Pick Okta, Microsoft Entra ID, Google Workspace, JumpCloud, Other SAML, or Other OIDC, and the protocol where your provider offers both. Name it in Name on the sign-in button, the way people will see it.

  2. Verify your domain

    This step shows only while none of your domains is verified. It walks you through the TXT record described above.

  3. Copy Evergreen’s values into your provider

    Create an app for Evergreen in your provider and paste in the values Evergreen shows. For OpenID Connect, that’s the Redirect URI. For SAML, it’s the ACS URL and the Entity ID, or the Metadata URL. Each value is named the way your provider names its field.

  4. Paste back what it gives you

    For OpenID Connect, enter the Issuer URL, Client ID, and Client secret. Under Endpoints and scopes you can also set the endpoints and scopes. The defaults are openid email profile, and openid has to stay.

    For SAML, enter the Identity provider entity ID, the Single sign-on URL, and the Signing certificate.

  5. Test sign-in

    Choose Run a test sign-in. It signs you in through your provider without signing anyone in to Evergreen. When it works you see Test sign-in worked., the provider is marked Tested, and you see the groups the sign-in carried.

  6. Turn it on

    The Owner chooses Turn on single sign-on. An Admin sees Ask the Owner to turn it on instead, which sends the Owner a request, once a day at most.

  7. Connect SCIM

    This step is optional, only the Owner sees it, and it’s offered only where your provider supports SCIM over the protocol you picked. See Provision people with SCIM.

Turning single sign-on on adds it as a way in. Emailed codes and Google keep working until you require single sign-on on a domain. Someone on your verified domains whom your provider lets in, and who isn’t in your workspace yet, becomes a member at their first sign-in.

A provider is Draft, then Tested, then On. Sign-in has to start from Evergreen. Evergreen doesn’t support starting it from a tile in your provider’s dashboard. A person’s email must be on one of your verified domains, and an OpenID Connect provider has to report the address as verified.

Warning

If you change anything but the name on a provider that’s on, single sign-on turns off until you test it again. Only the Owner can make that change.

Require single sign-on and capture sign-ups

On Domains, the Owner can set a domain to Single sign-on only. If people on the domain use Evergreen outside your workspace, the card warns that requiring it locks them out until you invite them.

When you require it, Evergreen asks when it starts. Give people 14 days lets everyone on the domain keep signing in the way they do now until then, so they have time to join your workspace or move their account, and the card shows the day it starts. Lock now starts it at once. From then on, anyone signed in another way is signed out within a few minutes, and they have to sign in through your provider. In the terminal, evergreen domains policy takes a grace of 0 to 30 days.

While any domain requires single sign-on, you can’t turn the provider off, remove it, or change it in a way that sends it back to draft.

The Owner can also choose This workspace for where new sign-ups go. This is domain capture. People who sign up with an address on the domain join your workspace instead of starting their own, and existing accounts aren’t affected.

Give roles from your provider’s groups

Group rules give people a role and audiences from the groups your identity provider sends. They’re under Group rules on Workspace settings › Sign-in, and they need Enterprise and single sign-on. Your provider sends groups with each sign-in, through SCIM, or both. If it isn’t sending any yet, the Sign-in page shows how to add a groups claim in your provider, and a test sign-in shows the groups it carried.

  1. Add a rule

    Choose Add rule and pick a group your provider has sent, or type a group name or Entra object ID it hasn’t sent yet.

  2. Choose what it gives

    Under Role, choose None, User, or Admin. Under Audiences, pick the audiences its people join. The preview shows who the rule reaches and what changes for them.

  3. Save it

    Choose Save rule. It applies at once, and again whenever your provider sends new groups.

While someone is in a group whose rule sets a role, their role follows the rule and is locked on Members. If they match more than one rule, the highest role applies. A rule with None leaves roles alone, so you can still change them by hand. Places in an audience that a rule gives can’t be removed by hand either. People leave when they leave the group in your provider.

Owners and Admins manage group rules, but only the Owner adds, changes, or deletes a rule that gives Admin. An Admin’s change can’t move another Admin’s role, or the Owner’s or another Admin’s audiences.

Rules apply when someone signs in, when your provider changes a group or a person over SCIM, when single sign-on is turned on, every night, and to the previous Owner after an ownership transfer. While single sign-on is off, the rules pause, and you can change roles on Members again. In the terminal, evergreen sso rules lists and edits them.

Provision people with SCIM

SCIM lets your identity provider add people to the workspace and remove them. It needs Enterprise and single sign-on turned on.

  1. Generate a token

    On Workspace settings › Sign-in, under Provisioning (SCIM), the Owner chooses Generate token. The token is shown once, so copy it with Copy token.

  2. Give your provider the address and the token

    Copy the SCIM base URL with Copy SCIM base URL and enter it, with the token, in your provider’s provisioning settings.

What SCIM does:

  • It adds people whose email is on a verified domain. They join as Users and sign in through single sign-on.
  • It doesn’t set roles by itself. You set them on Members, or through group rules that read the groups your provider pushes.
  • It removes people when your provider unassigns or deactivates them, the same way Remove from workspace does. The Owner always stays.
  • Groups your provider pushes show up as People groups, and your provider owns them. They don’t gate features themselves, but a group rule can match them.

Only the Owner can generate, rotate, or revoke the token, because it adds and removes people, Admins among them. Rotating it stops the old token straight away. Revoking it means your provider can no longer add or remove people, and everyone it added stays.

Last updated

Esc