# SCIM provisioning

> Let your identity provider add, update and remove the members of your By Dawn organization, and map its groups to By Dawn roles.

This page helps you connect your identity provider to By Dawn over SCIM, so that adding someone to the By Dawn app in
your identity provider adds them to your organization, and switching them off removes them. By the end you'll
also know how to let your identity provider's groups decide who is an admin, or who is on a project.

SCIM is the standard way an identity provider such as Okta or Microsoft Entra ID keeps other apps' user lists
in step with its own. It works with or without [single sign-on](https://docs.bydawn.com/sso/), and the two go well together: single
sign-on decides how people sign in, and SCIM decides who's a member.

## Before you start

- **Your plan must include SCIM provisioning.** Without it, the section shows **SCIM provisioning is not on
  your plan** (see [Plans and billing](https://docs.bydawn.com/billing/)). Tokens made before stay listed and can still be revoked.
- **Verify a domain.** SCIM only adds people whose email is at one of your
  [verified domains](https://docs.bydawn.com/sso-domains/), so you can't create a token until you have one.
- **You need to be the organization's owner.** Admins can open
  **Settings › Organization › SCIM provisioning** and see the tokens, but only the owner can
  create or revoke one.

## Connect your identity provider

1. Open **Settings › Organization › SCIM provisioning**. Type a **Name** for the token, such as
   `Okta`, and choose **Create token**.

2. By Dawn shows two values: "Copy this token now — you won't see it again." Copy the **SCIM base URL** and the
   **Token** into your identity provider's SCIM settings, with the token as an HTTP bearer token. Then choose
   **Done**.

3. Turn provisioning on in your identity provider, as below for Okta or Microsoft Entra ID. Other providers
   that speak SCIM 2.0, such as OneLogin or JumpCloud, take the same two values.

### Okta

In the By Dawn app integration in Okta, turn on SCIM provisioning. Set **SCIM connector base URL** to By Dawn's
**SCIM base URL**, **Unique identifier field for users** to `userName`, and the authentication mode to
**HTTP Header** with the token. Then turn on **Push New Users**, **Push Profile Updates** and, for
[group mappings](#map-groups-to-roles), **Push Groups**.

### Microsoft Entra ID

In the By Dawn enterprise application, open **Provisioning** and set **Provisioning Mode** to **Automatic**. Set
**Tenant URL** to By Dawn's **SCIM base URL** and **Secret Token** to the token, and test the connection. Entra's
default attribute mappings work as they are. By Dawn accepts the attributes it doesn't keep, such as job title and
phone numbers, and ignores them.

## What your identity provider changes in By Dawn

| In your identity provider | In By Dawn |
| --- | --- |
| Assign someone to the By Dawn app | They join your organization. If they don't have a By Dawn account, By Dawn creates one. Their role is the one in a pending invitation, else your single sign-on connection's **Their role**, else **member**. It's never owner. |
| Change their details | Their name is filled in if By Dawn doesn't have one. Their By Dawn email never changes. |
| Unassign or deactivate them | They're removed from the organization, exactly as if an admin had removed them (see [Remove someone](https://docs.bydawn.com/members/#remove-someone)), and signed out of their single sign-on sessions straight away. By Dawn remembers their role. |
| Reactivate them | They're back, with the role they had (an admin at most). |
| Delete them | They're removed from the organization. Their By Dawn account stays, because they may belong to other organizations. |

Someone who's already a member keeps their role when your identity provider takes them over. Each new member
takes a seat, and your identity provider gets an error if your organization is at its member limit. The
organization's last owner can't be removed this way.

Without SCIM, someone you switch off in your identity provider can keep using By Dawn until their single sign-on
session runs out, which takes up to 24 hours. With SCIM, it's immediate.

> **Note:** If an admin removes someone in By Dawn whom your identity provider still has assigned, By Dawn keeps them removed. They
> only come back if your identity provider deactivates and reactivates them, or deletes and adds them again.

## Map groups to roles

**Group mappings** let your identity provider's groups decide who is an admin, who is on a project, or who is on a
[team](https://docs.bydawn.com/teams/). They're
on **Settings › Organization › Single sign-on**, under **Group mappings**, and need SCIM
provisioning with **Push Groups** (or your provider's equivalent) on. Only the owner can change them.

1. Under **Choose a group**, pick one of the groups your identity provider pushed. If none are listed, By Dawn says
   "Your identity provider hasn't pushed any groups yet."

2. Pick what the group gives: **Organization role**, a project (**Project ·** and its name), or a team (**Team ·**
   and its name).

3. Pick the role, and choose **Add mapping**. An organization role can be **admin** or **member**. A project
   role can be **viewer**, **member** or **admin**. A team has no role to pick: "The group's members join the team
   as members, and leave it when they leave the group."

By Dawn applies a mapping straight away, and again whenever the group's members change. The card states the rules:
"When someone is in several mapped groups, the highest role wins. Leaving every mapped group puts them back on
the connection's default role. Roles you change by hand in Members stay as you set them, and an owner's role
never changes." Leaving every group mapped to a project takes the person off that project.

A team mapped to a group is managed by your identity provider: "People can no longer be added to or removed from
the team by hand." It shows **Managed by your identity provider** in the teams list, and its leads are still chosen
in By Dawn.

A mapping never adds anyone to the organization or removes them: SCIM provisioning does that.

### Roles set by hand

A role your identity provider gives shows an **IdP** badge in [Members and invites](https://docs.bydawn.com/members/) and on the
project's members. If you change that role by hand, By Dawn keeps your choice and stops applying the mapping to it.
To hand it back, choose **Let IdP manage** in the person's row.

While a mapping gives someone a project, you can't remove them from it by hand. Remove them from the group in
your identity provider, or change their role in By Dawn first so By Dawn keeps it.

## Rotate or revoke a token

An organization can hold two live tokens: "An organization can hold two live tokens, so you can rotate one in at
your identity provider before revoking the old one." To rotate, create a second token, put it in your identity
provider, then choose **Revoke** next to the old one and **Revoke token**.

A revoked token stops working on your identity provider's next call, and provisioning stops until it has a live
token. Members it already added stay. Each token shows when it was created and last used, and revoked tokens
stay in the list.

## FAQ

**Do I need single sign-on to use SCIM?**

No. SCIM only needs a verified domain. With single sign-on as well, people your identity provider adds can sign
in through it, and a new member gets the connection's **Their role**.

**Can group claims in a sign-in set roles?**

No. Only groups pushed through SCIM feed group mappings, because a sign-in doesn't tell By Dawn when someone leaves
a group.

**Our identity provider gets an error for some people. Why?**

Usually their email isn't at one of your verified domains, so By Dawn won't add them. Verify that domain, or check
which email your identity provider sends. A person can also only be provisioned once per organization.

## Where to go next

- [Single sign-on](https://docs.bydawn.com/sso/): sign the people SCIM adds in through your identity provider.
- [Members and invites](https://docs.bydawn.com/members/): see who's in, and the roles they have.

Source: https://docs.bydawn.com/scim/