Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions docs/control-plane/idp-setup/entra.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,11 @@ sequenceDiagram
5. Under **Manage**, select **Token configuration**, then **Add groups claim**. Tick **Security groups** and select **Save**. Leave each token's value at the default, the group ID. Switching it to sAMAccountName, cloud display names or role claims breaks DFE's group links.
6. Do not add a `groups` permission or scope. Entra adds the claim from step 5, and asking for a `groups` scope fails the sign-in.

Two optional extras, for when the operator asks:
Three optional extras, for when the operator asks:

- Group names on the Graph path, which otherwise returns each group's id with a blank name: **API permissions > Add a permission > Microsoft Graph > Delegated permissions > GroupMember.Read.All**, then **Grant admin consent for <tenant>**. DFE links on the id, so sign-in works without it.
- An app-only fallback: the Microsoft Graph application permission **GroupMember.Read.All** with admin consent. DFE then reads a user's groups with the app's secret when Graph turns down the user's token, and the operator can run a group sync.
- Linking sign-ins to existing DFE accounts by email: **Token configuration > Add optional claim**, token type **ID**, tick **email** and **xms_edov**, then **Add**. Entra sends no `email_verified`, so DFE treats an Entra email as verified only when `xms_edov` is true.

## Send these to the operator

Expand Down Expand Up @@ -100,7 +101,7 @@ Create the provider with `POST /api/v1/auth/oidc-providers`. The `name` becomes
}
```

`token_claim` reads the `groups` claim, and the overage lookup runs with no setting. The app-only fallback is the one thing that needs `groups.tenant_id`, and it uses the login client secret unless `groups.client_secret` is set. Leave `scopes` unset: the default is `openid email profile`. The client secret goes to the secret store and the provider keeps its path, never the value.
`token_claim` reads the `groups` claim, and the overage lookup runs with no setting. The app-only fallback is the one thing that needs `groups.tenant_id`, and it uses the login client secret unless `groups.client_secret` is set. Leave `scopes` unset: the default is `openid email profile`. The client secret goes to the secret store and the provider keeps its path, never the value. Set `trusted_email_domains` to your users' email domains and have the admin add the `xms_edov` claim: DFE admits only a sign-in whose verified email is in one of them, and links it to an existing account holding that email: see [rbac-sign-in.md, Linked sign-ins](../rbac-sign-in.md#linked-sign-ins).

Link each DFE group by setting two fields in its group file: `source_provider` to `<provider-name>`, the name the provider was created with, and `source_id` to an object id the admin sent. A group file with a `source_id` and no `source_provider` loads unlinked, with a warning naming it in the engine log, and no sign-in reaches it through that id: see [rbac-groups.md, section 4.4](../rbac-groups.md#44-group-sync-process).

Expand All @@ -119,6 +120,8 @@ Behind a TLS-terminating proxy, set `api.forwarded_allow_ips` (`DFE_ENGINE_API_F
- Add a redirect URI: <https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri>
- Add a client secret: <https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials>
- Groups claim and the 200-group limit: <https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims>
- The `xms_edov` claim: <https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference>
- Why an unverified email must not identify a user: <https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization>
- Issuer and discovery: <https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc>
- `transitiveMemberOf` permissions: <https://learn.microsoft.com/en-us/graph/api/user-list-transitivememberof>
- Error codes: <https://learn.microsoft.com/en-us/entra/identity-platform/reference-error-codes>
Expand Down
2 changes: 1 addition & 1 deletion docs/control-plane/idp-setup/google.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Create the provider with `POST /api/v1/auth/oidc-providers`. The `name` becomes
}
```

A `google` provider accepts `api` mode alone, and DFE turns on `enrich_on_login` for it. Leave `scopes` unset: the default holds the Cloud Identity scope. The client secret goes to the secret store and the provider keeps its path, never the value. A service account (`groups.service_account_json`) holding a groups admin role is optional: it runs the group sync and answers a sign-in the user's token could not. Without one the group sync has no directory to list, so the provider's `last_sync_status` reads `user_token` and `sync_error` stays empty.
A `google` provider accepts `api` mode alone, and DFE turns on `enrich_on_login` for it. Leave `scopes` unset: the default holds the Cloud Identity scope. The client secret goes to the secret store and the provider keeps its path, never the value. A service account (`groups.service_account_json`) holding a groups admin role is optional: it runs the group sync and answers a sign-in the user's token could not. Without one the group sync has no directory to list, so the provider's `last_sync_status` reads `user_token` and `sync_error` stays empty. Google's ID token carries `email_verified`. Set `trusted_email_domains` to your Workspace domains: DFE admits only a sign-in whose verified email is in one, and links it to an existing account holding that email ([rbac-sign-in.md, Linked sign-ins](../rbac-sign-in.md#linked-sign-ins)).

Link each DFE group by setting two fields in its group file: `source_provider` to `<provider-name>`, the name the provider was created with, and `source_id` to an id the admin sent. A group file with a `source_id` and no `source_provider` loads unlinked, with a warning naming it in the engine log, and no sign-in reaches it through that id: see [rbac-groups.md, section 4.4](../rbac-groups.md#44-group-sync-process).

Expand Down
2 changes: 1 addition & 1 deletion docs/control-plane/idp-setup/okta.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ source_provider: "<provider-name>"
source_id: "<Okta group name>"
```

A linked group admits its members once it holds a role, and until one does no Okta user can sign in, so link the first group as the local admin or the break-glass account. Behind a TLS-terminating proxy, set `api.forwarded_allow_ips` (`DFE_ENGINE_API_FORWARDED_ALLOW_IPS`), or the engine builds the redirect URI with `http://` and Okta turns it down.
A linked group admits its members once it holds a role, and until one does no Okta user can sign in, so link the first group as the local admin or the break-glass account. Set `trusted_email_domains` to your users' email domains: DFE admits only a sign-in whose verified email is in one, and links it to an existing account holding that email. Okta answers `email_verified` from its userinfo endpoint, which DFE then reads at each sign-in ([rbac-sign-in.md, Linked sign-ins](../rbac-sign-in.md#linked-sign-ins)). Behind a TLS-terminating proxy, set `api.forwarded_allow_ips` (`DFE_ENGINE_API_FORWARDED_ALLOW_IPS`), or the engine builds the redirect URI with `http://` and Okta turns it down.

## Okta references

Expand Down
5 changes: 3 additions & 2 deletions docs/control-plane/oidc-rbac-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,8 +145,9 @@ a pure customer gets the data plane alone.
Providers are YAML files (one per provider, filename stem = name) managed by
`OIDCProviderRegistry`. The model (`src/dfe_engine/auth/oidc/models.py`) holds
`type` (generic, google, entra_id or okta), `enabled`, `issuer`, `client_id`,
`client_id_env`, `client_secret_path`, `client_secret_env`, `scopes`, and a
`groups` block (mode, claim name and the per-provider directory fields).
`client_id_env`, `client_secret_path`, `client_secret_env`, `scopes`, a
`groups` block (mode, claim name and the per-provider directory fields) and
[`trusted_email_domains`](rbac-sign-in.md#linked-sign-ins).

A provider file that does not load, with unreadable YAML or fields that fail validation, is left out of the provider list, the relying party and the sync scheduler. The engine logs it once and counts it on `auth_oidc_providers_skipped_total{reason}` (`unreadable`, `invalid`), and every other provider keeps working.

Expand Down
24 changes: 24 additions & 0 deletions docs/control-plane/rbac-sign-in.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,14 +121,38 @@ A sign-in through `X-Oidc-Groups` resolves its roles the way a token does, from

The linked groups are the sign-in allowlist as well. An IdP sign-in, through the OIDC callback or `X-Oidc-Groups`, is admitted when the account it binds to would hold a role, from a group its identifiers link to or a group with the account in its member list. A linked group with no role, which is every group the sync creates until an admin gives it one, admits nobody.

An OIDC callback sign-in also needs an email the IdP verified, in a domain the provider's `trusted_email_domains` lists, or it gets `401 email_untrusted` and writes nothing. A provider with no trusted domains admits nobody.

Anyone else gets `401 no_role_granted` (a sign-in the console started, with `return_to`, goes back to the console with that code in the URL fragment instead) and an `auth.jit.login_refused` audit event. A first sign-in leaves no account. An existing account records the groups its IdP asserts at that sign-in and has every session ended, as a logout ends them, so an issued token answers `401 session_ended` on any route, refresh included. The local admin or the break-glass account (section 3.5) links the first group, and adding an account to a group by hand admits someone the IdP groups do not cover, which is the one way in through a `manual`-mode provider.

An admin sets `source_id` and `source_provider` together through the groups API or dfe-ui's group form ([section 4.4](rbac-groups.md#44-group-sync-process)). `source_provider` names the provider with the logins the link answers. Where a `token_claim` provider's claim holds names (Okta's default, dex, Keycloak), `source_id` is the name the IdP sends. For Entra it is the object ID.

A groups claim sent as one string is split on commas, never on whitespace (`src/dfe_engine/auth/oidc/rp.py`), and `X-Oidc-Groups` is split on commas. So a string claim of `SOC Analysts` is the one group `SOC Analysts`. A `source_id` containing a comma matches an array claim on the relying-party path and nothing else.

## Linked sign-ins

One account can take several sign-ins: its own password or IdP, plus IdP sign-ins linked to it. A linked sign-in's session is the account's, so disabling, blocking or logging out the account covers all of them. Each sign-in's IdP groups are recorded on its own entry, and the account holds the groups every entry links to.

A sign-in links on its first login through the OIDC callback when all of these hold:

- The IdP vouches for the email: `email_verified` is true, or `xms_edov` from Entra, which sends no `email_verified` (see [idp-setup/entra.md](idp-setup/entra.md)). An address read from `preferred_username` or `upn` never counts.
- The provider's `trusted_email_domains` lists the email's domain.
- Exactly one account holds the email, ignoring case, among accounts whose email is vouched for: an admin set it, a trusted IdP verified it, or it is a local account's email from before linking existed. An email a user set on their own account through `PUT /api/v1/auth/accounts/me` never counts, so nobody can claim another person's address. The local admin, break-glass and soft-deleted accounts never count. With two holders the sign-in is refused, after an `auth.identity.link_skipped` audit event.

An account an IdP owns links at once. A local account links only after its password: the callback answers `409 link_required` with `account` and a `link_ticket` (the console's hand-back carries them in the URL fragment), and `POST /api/v1/auth/oidc/link` with the ticket and the password links and signs in. The ticket lasts 10 minutes and authenticates nothing else. Wrong passwords count against the account's sign-in throttle. Either way the sign-in must leave the account holding a role, and a disabled or blocked account refuses it.

A sign-in through `X-Oidc-*` headers never links, because the headers carry no proof, but it follows a link made through the callback.

A first callback sign-in that does not link while another account holds its email is refused with `email_held` and writes nothing, so one email is one account. An email that account's owner set themselves never blocks, so nobody can lock a colleague out of their identity provider. Trusting the provider's domain lets the sign-in link instead.

Trust a domain only on a provider whose directory you control. An IdP that lets its users set their own email would let them claim another person's account.

Each linked sign-in also has a small link record under the account store's `links/` directory, named after the sign-in, which points at its account so a returning sign-in finds it in one read. An account's `identities` lists its linked sign-ins. `DELETE /api/v1/auth/accounts/{username}/identities/{key}` unlinks one, ends every session of the account and leaves the sign-in an account of its own. Deleting the account deletes its links, and deleting a provider unlinks every sign-in through it. Creating or editing an account refuses an email another linkable account holds (`409 email_taken`). Other accounts that share an email are left as they are.

## Local accounts and role changes

A local account signs in with its username, or with its email when exactly one local account holds that email vouched for, as linking counts it. Failed sign-ins by email count against the account name's throttle.

For a local account the group files are the authority. The API routes keep the account's `groups` list in step, but that list grants nothing. A member removed from a group file in the live store loses that group's roles and orgs at its next engine request, whether the API removed it, someone edited the file in the engine's auth directory, or dfe-infra's `authConfig.groupsConfigMap` value seeded a changed file in at pod start. The engine's auth never reads the deploy repo's `governance/rbac/groups` or `governance/rbac/roles`, so an edit there changes nothing. An account an IdP owns (JIT or SCIM) holds the groups its record says the IdP asserts as well, so a group an operator adds it to by hand sits beside those.

dfe-hyperdx decides on the `role` claim of the token it holds, so there a role taken away lasts until that token expires or is refreshed (`api.jwt_expire_minutes`).
Expand Down
13 changes: 9 additions & 4 deletions docs/reference/api-route-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ One row per operation the engine serves today. **New** is where it goes, and its

| Status | Operations | Meaning |
|---|---|---|
| moved | 87 | A new path, method or both |
| merged into | 9 | Folded into the operation **New** names |
| moved | 88 | A new path, method or both |
| merged into | 10 | Folded into the operation **New** names |
| unchanged | 44 | Same method and path |
| frozen | 54 | Kept as it is |
| frozen | 57 | Kept as it is |
| decide | 128 | Not placed yet: see its question |
| removed | 0 | Gone, with nothing in its place |
| total | 322 | |
| total | 327 | |

## Questions

Expand Down Expand Up @@ -103,12 +103,14 @@ One row per operation the engine serves today. **New** is where it goes, and its
|---|---|---|---|---|---|---|---|
| `GET /api/v1/auth/accounts` | `GET /api/v1/identity/accounts` | `identity.accounts.list` | `dfe identity accounts list` | `dfe_identity_accounts_list` | moved | ui 2, cli 1 | |
| `POST /api/v1/auth/accounts` | `PUT /api/v1/identity/accounts/{account}` | `identity.accounts.apply` | `dfe identity accounts apply` | `dfe_identity_accounts_apply` | merged into | ui 2, cli 1 | One PUT creates (`If-None-Match: *`) and replaces (`If-Match`). |
| `GET /api/v1/auth/accounts/availability` | `PUT /api/v1/identity/accounts/{account}` | `identity.accounts.apply` | `dfe identity accounts apply` | `dfe_identity_accounts_apply` | merged into | 0 | Validation is the apply with `dry_run=true`. |
| `DELETE /api/v1/auth/accounts/{username}` | `DELETE /api/v1/identity/accounts/{account}` | `identity.accounts.delete` | `dfe identity accounts delete` | `dfe_identity_accounts_delete` | moved | ui 2 | |
| `GET /api/v1/auth/accounts/{username}` | `GET /api/v1/identity/accounts/{account}` | `identity.accounts.get` | `dfe identity accounts get` | `dfe_identity_accounts_get` | moved | ui 2 | |
| `PUT /api/v1/auth/accounts/{username}` | `PUT /api/v1/identity/accounts/{account}` | `identity.accounts.apply` | `dfe identity accounts apply` | `dfe_identity_accounts_apply` | moved | ui 2 | |
| `GET /api/v1/auth/accounts/{username}/attributes` | `GET /api/v1/identity/accounts/{account}/attributes` | `identity.accounts.attributes.get` | `dfe identity accounts attributes get` | `dfe_identity_accounts_attributes_get` | moved | 0 | |
| `PUT /api/v1/auth/accounts/{username}/attributes` | `PUT /api/v1/identity/accounts/{account}/attributes` | `identity.accounts.attributes.apply` | `dfe identity accounts attributes apply` | `dfe_identity_accounts_attributes_apply` | moved | 0 | |
| `GET /api/v1/auth/accounts/{username}/git-status` | `GET /api/v1/identity/accounts/{account}/git-status` | `identity.accounts.git-status` | `dfe identity accounts git-status` | `dfe_identity_accounts_git_status` | moved | 0 | |
| `DELETE /api/v1/auth/accounts/{username}/identities/{key}` | `DELETE /api/v1/identity/accounts/{account}/identities/{identity}` | `identity.accounts.identities.delete` | `dfe identity accounts identities delete` | `dfe_identity_accounts_identities_delete` | moved | 0 | |
| `POST /api/v1/auth/accounts/{username}/reset-password` | `POST /api/v1/identity/accounts/{account}/reset-password` | `identity.accounts.reset-password` | `dfe identity accounts reset-password` | `dfe_identity_accounts_reset_password` | moved | ui 2 | |
| `POST /api/v1/auth/accounts/{username}/rotate-password` | `POST /api/v1/identity/accounts/{account}/rotate-password` | `identity.accounts.rotate-password` | `dfe identity accounts rotate-password` | `dfe_identity_accounts_rotate_password` | moved | 0 | |
| `GET /api/v1/auth/accounts/{username}/sensitive-attributes` | `GET /api/v1/identity/accounts/{account}/sensitive-attributes` | `identity.accounts.sensitive-attributes.get` | `dfe identity accounts sensitive-attributes get` | `dfe_identity_accounts_sensitive_attributes_get` | moved | 0 | |
Expand Down Expand Up @@ -241,9 +243,12 @@ Protocol surface: token issue, OIDC or SCIM (RFC 7644) fixes its shape.
| `POST /api/v1/auth/login` | `POST /api/v1/auth/login` | `auth.login` | `dfe auth login` | - | frozen | ui 6, infra 1, docker 1, cli 1 | |
| `POST /api/v1/auth/logout` | `POST /api/v1/auth/logout` | `auth.logout` | `dfe auth logout` | - | frozen | ui 3 | |
| `GET /api/v1/auth/me` | `GET /api/v1/auth/me` | `auth.me.list` | `dfe auth me list` | - | frozen | ui 7, cli 1 | |
| `POST /api/v1/auth/oidc/link` | `POST /api/v1/auth/oidc/link` | `auth.oidc.link` | `dfe auth oidc link` | - | frozen | 0 | |
| `POST /api/v1/auth/oidc/reauth` | `POST /api/v1/auth/oidc/reauth` | `auth.oidc.reauth` | `dfe auth oidc reauth` | - | frozen | 0 | |
| `GET /api/v1/auth/oidc/{provider}/callback` | `GET /api/v1/auth/oidc/{provider}/callback` | `auth.oidc.callback.list` | `dfe auth oidc callback list` | - | frozen | ui 2, infra 3 | |
| `GET /api/v1/auth/oidc/{provider}/login` | `GET /api/v1/auth/oidc/{provider}/login` | `auth.oidc.login.list` | `dfe auth oidc login list` | - | frozen | ui 3, infra 1 | |
| `GET /api/v1/auth/permissions` | `GET /api/v1/auth/permissions` | `auth.permissions.list` | `dfe auth permissions list` | - | frozen | ui 2 | |
| `POST /api/v1/auth/reauth` | `POST /api/v1/auth/reauth` | `auth.reauth` | `dfe auth reauth` | - | frozen | 0 | |
| `POST /api/v1/auth/refresh` | `POST /api/v1/auth/refresh` | `auth.refresh` | `dfe auth refresh` | - | frozen | ui 5 | |
| `GET /api/v1/auth/setup-status` | `GET /api/v1/auth/setup-status` | `auth.setup-status.list` | `dfe auth setup-status list` | - | frozen | ui 4, infra 5, docker 3 | |
| `POST /api/v1/auth/setup/retire-admin` | `POST /api/v1/auth/setup/retire-admin` | `auth.setup.retire-admin` | `dfe auth setup retire-admin` | - | frozen | docker 1 | |
Expand Down
Loading
Loading