# Microsoft Entra ID

Costfluent signs your people in through Microsoft Entra ID over OpenID Connect. You register one application in your own tenant, and Costfluent trusts the addresses at the domains you verify.

## Before you start

- You need the Owner organization role in Costfluent, and the right to register applications in your Entra ID tenant.
- Your people's addresses are at a domain you can publish a DNS TXT record for.
- Assigning groups to an application needs Microsoft Entra ID P1, which Microsoft 365 Business Premium includes.

<PlanAvailability feature="Sso" plan="Core" />

## Register the application

<Stepper>

1. In the Microsoft Entra admin center, open **App registrations** and register a new application.
2. Choose the account type for your organizational directory only (single tenant). Costfluent pins your tenant's issuer, so a multi-tenant registration does not work here.
3. Add a **Web** redirect URI: `https://app.costfluent.com/api/auth/sso/callback`.
4. Under **Certificates & secrets**, create a client secret and copy its value. Note its expiry: Costfluent cannot sign anyone in once it lapses.
5. Copy the **Application (client) ID** and the **Directory (tenant) ID** from the overview.

</Stepper>

Your discovery URL is `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`, with your directory (tenant) ID in place of `<tenant-id>`.

## Send groups

<Stepper>

1. Under **Token configuration**, add the optional claim `email` to the ID token. Entra ID sends no address otherwise.
2. Add a groups claim for the ID token, limited to the groups assigned to the application, and keep the group ID format.
3. Under **Enterprise applications**, open the same application and assign the groups whose members should sign in and be mapped to teams.

</Stepper>

Entra ID sends each group as its object ID, so the **Identity provider group** you map in Costfluent is that ID, not the group's display name.

:::caution
Entra ID leaves the groups claim out for a person in more than 200 groups. Costfluent then adds no team for that sign-in and removes only a team whose mapping you deleted or changed. Limiting the claim to the groups assigned to the application keeps it under the limit.
:::

## Connect in Costfluent

<Stepper>

1. Open **Settings**, then **Single sign-on**, and connect your provider with the discovery URL, the client ID and the client secret.
2. Add your email domains to the connection and verify each with its DNS TXT record.
3. Map the group object IDs to teams, then enable the connection.

</Stepper>

[Sign-in and security](/admin/sign-in-security) covers each of these steps, enforcement and break-glass Owners.

## How it behaves

Costfluent reads these claims from the ID token, and from the userinfo endpoint where the ID token leaves one out:

- `iss`, which must equal the issuer your discovery document named when you connected it, `https://login.microsoftonline.com/<tenant-id>/v2.0`. A token from another tenant is refused.
- `oid`, the person's object ID, as the identity Costfluent keeps. It stays the same if you register the application again; `sub` does not.
- `email`, which must be at one of the connection's verified domains. Entra ID sends no `email_verified` claim, and none is needed: the verified domain is the proof. An address outside every verified domain is refused, and so is a sign-in without an address.
- `name`, for the name of an account Costfluent creates.
- `groups`, the group object IDs, or another claim name you set on the connection.

Costfluent also refuses a token whose signature, audience, nonce or lifetime does not check out, and a discovery document that starts naming another issuer.

## Related

- [Sign-in and security](/admin/sign-in-security)
- [Users, teams and roles](/admin/users-teams-and-roles)