diff --git a/docs/control-plane/idp-setup/entra.md b/docs/control-plane/idp-setup/entra.md index 0c9723d5a..c12d4bfc9 100644 --- a/docs/control-plane/idp-setup/entra.md +++ b/docs/control-plane/idp-setup/entra.md @@ -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 **. 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 @@ -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 ``, 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). @@ -119,6 +120,8 @@ Behind a TLS-terminating proxy, set `api.forwarded_allow_ips` (`DFE_ENGINE_API_F - Add a redirect URI: - Add a client secret: - Groups claim and the 200-group limit: +- The `xms_edov` claim: +- Why an unverified email must not identify a user: - Issuer and discovery: - `transitiveMemberOf` permissions: - Error codes: diff --git a/docs/control-plane/idp-setup/google.md b/docs/control-plane/idp-setup/google.md index 4d413799d..1986ed9c3 100644 --- a/docs/control-plane/idp-setup/google.md +++ b/docs/control-plane/idp-setup/google.md @@ -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 ``, 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). diff --git a/docs/control-plane/idp-setup/okta.md b/docs/control-plane/idp-setup/okta.md index c0a1dde61..33524ab0a 100644 --- a/docs/control-plane/idp-setup/okta.md +++ b/docs/control-plane/idp-setup/okta.md @@ -94,7 +94,7 @@ source_provider: "" source_id: "" ``` -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 diff --git a/docs/control-plane/oidc-rbac-architecture.md b/docs/control-plane/oidc-rbac-architecture.md index 62421f29f..88094b4e2 100644 --- a/docs/control-plane/oidc-rbac-architecture.md +++ b/docs/control-plane/oidc-rbac-architecture.md @@ -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. diff --git a/docs/control-plane/rbac-sign-in.md b/docs/control-plane/rbac-sign-in.md index cae581c5b..696d54f9c 100644 --- a/docs/control-plane/rbac-sign-in.md +++ b/docs/control-plane/rbac-sign-in.md @@ -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`). diff --git a/docs/reference/api-route-map.md b/docs/reference/api-route-map.md index 5d0f2dd21..71375595a 100644 --- a/docs/reference/api-route-map.md +++ b/docs/reference/api-route-map.md @@ -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 @@ -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 | | @@ -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 | | diff --git a/openapi/openapi.json b/openapi/openapi.json index ae2961953..cbccc41b8 100644 --- a/openapi/openapi.json +++ b/openapi/openapi.json @@ -436,6 +436,20 @@ "summary": "Retire Bootstrap Admin", "description": "Retire the bootstrap admin: disable it and record the fact in the deploy repo.\n\nThe deployment mints the admin password and the engine reissues it whenever\nthe injected value changes, so until it is retired anyone able to write the\nSecret or ``.env`` can issue themselves the admin at the next boot. Retiring\nends the reseed: the account stays disabled, the password may be deleted, and\n``breakglass`` is the recovery path.\n\nThe console keeps the bootstrap admin. Retiring it is an operator's policy\nchoice made here. Refused unless the deployment already has an enabled\nadmin-role account of its own -- ``retire_admin_available`` on the setup status\nis the same predicate. Returns the setup status, which now\nreports ``admin_retired``. Reversal is not an API: remove ``admin_retired``\nfrom ``governance/settings/auth.yaml`` in the deploy repo and restart.", "operationId": "auth.setup.retire-admin", + "parameters": [ + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" + } + ], "responses": { "200": { "description": "Successful Response", @@ -467,6 +481,16 @@ } } }, + "422": { + "description": "Validation Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, "default": { "description": "Problem details (RFC 9457)", "content": { @@ -500,6 +524,97 @@ } } }, + "/api/v1/auth/reauth": { + "post": { + "tags": [ + "Auth" + ], + "summary": "Reauth", + "description": "Re-enter your password to earn a grant for editing one account, which every edit of it needs.\n\n403 ``invalid_password`` on a wrong password, counted against the sign-in throttle. 409 ``reauth_via_idp`` for a caller with no local password, who re-signs in at its identity provider instead.", + "operationId": "auth.reauth", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReauthRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReauthResponse" + } + } + } + }, + "401": { + "description": "No valid session: the credentials are missing, invalid or expired, or the account behind them is disabled or blocked", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "403": { + "description": "Refused: the session lacks the action this route checks, or its account must replace an issued password first. A SCIM route answers a refused action in the RFC 7644 error envelope", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "default": { + "description": "Problem details (RFC 9457)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "x-scalo": { + "group": "auth", + "resource": "auth", + "hierarchy": [ + "auth" + ], + "verb": "reauth", + "read_only": false, + "cli": { + "hidden": false, + "aliases": [], + "positional": [] + } + } + } + }, "/api/v1/auth/oidc/{provider}/login": { "get": { "tags": [ @@ -633,7 +748,17 @@ } }, "303": { - "description": "Login started with return_to: redirect there with the engine token in the URL fragment, or with the refusal's code (#error=&provider=...) when the login is refused." + "description": "Login started with return_to: redirect there with the engine token in the URL fragment, or with the refusal's code (#error=&provider=...) when the login is refused. A sign-in that links to a local account comes back with #error=link_required&link_ticket=...&account=...&provider=... instead." + }, + "409": { + "description": "link_required: the sign-in's trusted email matches a local account. The body's link_ticket and that account's password go to POST /auth/oidc/link, and account names it.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } }, "422": { "description": "Validation Error", @@ -674,14 +799,227 @@ } } }, + "/api/v1/auth/oidc/link": { + "post": { + "tags": [ + "OIDC Login" + ], + "summary": "Oidc Link", + "description": "Link the sign-in a ``link_required`` callback held to its local account, on that account's password, and sign it in.\n\nWrong passwords count against the account's sign-in throttle (``auth.login_throttle``), as a password login's do. The answer is the callback's, and from then on the sign-in reaches the account without a password.", + "operationId": "auth.oidc.link", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OidcLinkRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OidcCallbackResponse" + } + } + } + }, + "401": { + "description": "link_ticket_invalid (expired or not this engine's), a wrong password, link_stale (the account or the sign-in changed since the ticket), or the account is disabled, blocked or would hold no role", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "404": { + "description": "The ticket's provider is no longer registered and enabled", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "429": { + "description": "Too many failed attempts for this account or from this address; Retry-After gives the seconds to wait", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "default": { + "description": "Problem details (RFC 9457)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + } + }, + "x-scalo": { + "group": "auth", + "resource": "oidc", + "hierarchy": [ + "auth", + "oidc" + ], + "verb": "link", + "read_only": false, + "cli": { + "hidden": false, + "aliases": [], + "positional": [] + } + } + } + }, + "/api/v1/auth/oidc/reauth": { + "post": { + "tags": [ + "OIDC Login" + ], + "summary": "Oidc Reauth", + "description": "Start a fresh sign-in at your own identity provider, which earns a grant for changing one account or group.\n\nThe IdP is asked to take your credentials again (``prompt=login``, ``max_age=0``), and the callback answers with the grant instead of a session.", + "operationId": "auth.oidc.reauth", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OidcReauthRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OidcLoginResponse" + } + } + } + }, + "401": { + "description": "No valid session: the credentials are missing, invalid or expired, or the account behind them is disabled or blocked", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "403": { + "description": "Refused: the session lacks the action this route checks, or its account must replace an issued password first. A SCIM route answers a refused action in the RFC 7644 error envelope", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "409": { + "description": "reauth_via_password: the caller has no identity-provider sign-in, so it confirms with its password at POST /auth/reauth", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "default": { + "description": "Problem details (RFC 9457)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "x-scalo": { + "group": "auth", + "resource": "oidc", + "hierarchy": [ + "auth", + "oidc" + ], + "verb": "reauth", + "read_only": false, + "cli": { + "hidden": false, + "aliases": [], + "positional": [] + } + } + } + }, "/api/v1/auth/accounts": { "post": { "tags": [ "Accounts" ], "summary": "Create Account", - "description": "Create a new local user account (admin only).", + "description": "Create a new local user account: an admin of an org other than yours creates it in that org only.", "operationId": "auth.accounts.create", + "parameters": [ + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" + } + ], "requestBody": { "required": true, "content": { @@ -771,7 +1109,7 @@ "Accounts" ], "summary": "List Accounts", - "description": "List accounts (admin only), paginated. No password hashes returned.", + "description": "List the accounts the caller administers, paginated: every account across orgs, else its orgs' own. No password hashes returned.", "operationId": "auth.accounts.list", "parameters": [ { @@ -915,10 +1253,10 @@ "type": "null" } ], - "description": "Ordering over created_at, updated_at, username, each optionally followed by desc", + "description": "Ordering over created_at, org, updated_at, username, each optionally followed by desc", "title": "Order By" }, - "description": "Ordering over created_at, updated_at, username, each optionally followed by desc" + "description": "Ordering over created_at, org, updated_at, username, each optionally followed by desc" } ], "responses": { @@ -996,6 +1334,115 @@ } } }, + "/api/v1/auth/accounts/availability": { + "get": { + "tags": [ + "Accounts" + ], + "summary": "Get Account Availability", + "description": "Whether a new account could take *username* and hold *email*, judged as account create judges them.", + "operationId": "auth.accounts.availability", + "parameters": [ + { + "name": "email", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "An email a new account would hold", + "default": "", + "title": "Email" + }, + "description": "An email a new account would hold" + }, + { + "name": "username", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "A name a new account would take", + "default": "", + "title": "Username" + }, + "description": "A name a new account would take" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountAvailabilityResponse" + } + } + } + }, + "401": { + "description": "No valid session: the credentials are missing, invalid or expired, or the account behind them is disabled or blocked", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "403": { + "description": "Refused: the session lacks the action this route checks, or its account must replace an issued password first. A SCIM route answers a refused action in the RFC 7644 error envelope", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "default": { + "description": "Problem details (RFC 9457)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ], + "x-scalo": { + "group": "auth", + "resource": "accounts", + "hierarchy": [ + "auth", + "accounts" + ], + "verb": "availability", + "read_only": true, + "cli": { + "hidden": false, + "aliases": [], + "positional": [] + }, + "action": "account:write" + } + } + }, "/api/v1/auth/accounts/me": { "get": { "tags": [ @@ -1164,7 +1611,7 @@ "Accounts" ], "summary": "Get Account", - "description": "Get a single account by username (admin only).\n\nSoft-deleted (anonymized) accounts answer 404 the same as a missing name.", + "description": "Get a single account by username (admin only).\n\nSoft-deleted (anonymized) accounts, and those the caller does not administer, answer 404 the same as a missing name.", "operationId": "auth.accounts.get", "parameters": [ { @@ -1267,6 +1714,18 @@ "type": "string", "title": "Username" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -1379,6 +1838,18 @@ "type": "string", "title": "Username" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -1578,6 +2049,18 @@ "type": "string", "title": "Username" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -1682,6 +2165,18 @@ "type": "string", "title": "Username" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -1746,11 +2241,100 @@ } } }, - "security": [ - { - "BearerAuth": [] - } - ], + "security": [ + { + "BearerAuth": [] + } + ], + "x-scalo": { + "group": "auth", + "resource": "accounts", + "hierarchy": [ + "auth", + "accounts" + ], + "verb": "rotate-password", + "read_only": false, + "cli": { + "hidden": false, + "aliases": [], + "positional": [] + }, + "action": "accounts:reset_password" + } + } + }, + "/api/v1/auth/accounts/{username}/git-status": { + "get": { + "tags": [ + "Accounts" + ], + "summary": "Account Git Status", + "description": "Poll whether an account's password has merged to the deploy repo's main.\n\nStep 2 of the review-PR path for the local admin and ``breakglass``: the UI\npolls this after the operator merges the PR. It fetches remote main and flips\n``merged`` true. Durable immediately in the auto-merge and file-share modes. A\nregular user is never git-persisted, so it reports not-git-backed (durable in\nits own store).", + "operationId": "auth.accounts.git-status", + "parameters": [ + { + "name": "username", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Username" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountGitState" + } + } + } + }, + "401": { + "description": "No valid session: the credentials are missing, invalid or expired, or the account behind them is disabled or blocked", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "403": { + "description": "Refused: the session lacks the action this route checks, or its account must replace an issued password first. A SCIM route answers a refused action in the RFC 7644 error envelope", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "default": { + "description": "Problem details (RFC 9457)", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + } + }, "x-scalo": { "group": "auth", "resource": "accounts", @@ -1758,25 +2342,30 @@ "auth", "accounts" ], - "verb": "rotate-password", - "read_only": false, + "verb": "git-status", + "read_only": true, "cli": { "hidden": false, "aliases": [], "positional": [] }, - "action": "accounts:reset_password" - } + "action": "account:read" + }, + "security": [ + { + "BearerAuth": [] + } + ] } }, - "/api/v1/auth/accounts/{username}/git-status": { - "get": { + "/api/v1/auth/accounts/{username}/identities/{key}": { + "delete": { "tags": [ "Accounts" ], - "summary": "Account Git Status", - "description": "Poll whether an account's password has merged to the deploy repo's main.\n\nStep 2 of the review-PR path for the local admin and ``breakglass``: the UI\npolls this after the operator merges the PR. It fetches remote main and flips\n``merged`` true. Durable immediately in the auto-merge and file-share modes. A\nregular user is never git-persisted, so it reports not-git-backed (durable in\nits own store).", - "operationId": "auth.accounts.git-status", + "summary": "Unlink Identity", + "description": "Unlink an IdP sign-in from an account (admin only).\n\nThe sign-in's record becomes an account of its own, which its next sign-in judges on its own groups. Every session of the account ends, so one opened through the sign-in does not outlive the link. Taking away the groups the sign-in linked needs the roles they carry, as removing a group does.", + "operationId": "auth.accounts.identities.delete", "parameters": [ { "name": "username", @@ -1786,21 +2375,45 @@ "type": "string", "title": "Username" } + }, + { + "name": "key", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Key" + } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { - "200": { - "description": "Successful Response", + "204": { + "description": "Successful Response" + }, + "401": { + "description": "No valid session: the credentials are missing, invalid or expired, or the account behind them is disabled or blocked", "content": { - "application/json": { + "application/problem+json": { "schema": { - "$ref": "#/components/schemas/AccountGitState" + "$ref": "#/components/schemas/Problem" } } } }, - "401": { - "description": "No valid session: the credentials are missing, invalid or expired, or the account behind them is disabled or blocked", + "403": { + "description": "Refused: the session lacks the action this route checks, or its account must replace an issued password first. A SCIM route answers a refused action in the RFC 7644 error envelope", "content": { "application/problem+json": { "schema": { @@ -1809,8 +2422,18 @@ } } }, - "403": { - "description": "Refused: the session lacks the action this route checks, or its account must replace an issued password first. A SCIM route answers a refused action in the RFC 7644 error envelope", + "404": { + "description": "not_found: no such account, or it lists no sign-in under key", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, + "409": { + "description": "last_admin: the sign-in gives the last usable account its system admin role", "content": { "application/problem+json": { "schema": { @@ -1840,27 +2463,28 @@ } } }, + "security": [ + { + "BearerAuth": [] + } + ], "x-scalo": { "group": "auth", - "resource": "accounts", + "resource": "identities", "hierarchy": [ "auth", - "accounts" + "accounts", + "identities" ], - "verb": "git-status", - "read_only": true, + "verb": "delete", + "read_only": false, "cli": { "hidden": false, "aliases": [], "positional": [] }, - "action": "account:read" - }, - "security": [ - { - "BearerAuth": [] - } - ] + "action": "account:write" + } } }, "/api/v1/auth/accounts/{username}/attributes": { @@ -1971,6 +2595,18 @@ "type": "string", "title": "Username" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -2165,6 +2801,18 @@ "type": "string", "title": "Username" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -2259,6 +2907,20 @@ "summary": "Create Group", "description": "Create a new RBAC group at a scope.", "operationId": "auth.groups.create", + "parameters": [ + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" + } + ], "requestBody": { "required": true, "content": { @@ -2613,6 +3275,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -2714,6 +3388,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -2800,6 +3486,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -2913,6 +3611,18 @@ "type": "string", "title": "Username" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -3098,6 +3808,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -3292,6 +4014,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -3384,8 +4118,22 @@ "API Keys" ], "summary": "Create Api Key", - "description": "Create a new API key. Returns the full key exactly once.\n\n422 ``unknown_org`` when ``org`` names no registered org.", + "description": "Create a new API key. Returns the full key exactly once.\n\n422 ``unknown_org`` when ``org`` names no registered org, ``org_role_only`` when a key bound to an org other than yours names a group outside that org's admin and viewer roles.", "operationId": "auth.api-keys.create", + "parameters": [ + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" + } + ], "requestBody": { "required": true, "content": { @@ -3651,6 +4399,18 @@ "type": "string", "title": "Short Token" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -3894,6 +4654,20 @@ "summary": "Create Role", "description": "Create a new RBAC role granting no more than the caller holds.", "operationId": "auth.roles.create", + "parameters": [ + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" + } + ], "requestBody": { "required": true, "content": { @@ -4255,6 +5029,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -4357,6 +5143,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -4435,6 +5233,20 @@ "summary": "Create Provider", "description": "Create a new OIDC provider configuration (admin only).\n\nSecret values in the body are written to the secret store before the YAML, and only once the name is free and the provider passes the field rules for its type and mode, so a refused provider leaves nothing behind. A secret named by an env var the engine does not set, with no value sent for it, is refused the same way (``env_var_not_set``).", "operationId": "auth.oidc-providers.create", + "parameters": [ + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" + } + ], "requestBody": { "required": true, "content": { @@ -4524,7 +5336,7 @@ "OIDC Providers" ], "summary": "List Providers", - "description": "List OIDC providers (admin only), paginated.", + "description": "List the OIDC providers the caller manages, paginated: every one across orgs, else its orgs' own.", "operationId": "auth.oidc-providers.list", "parameters": [ { @@ -4689,7 +5501,7 @@ "OIDC Providers" ], "summary": "Get Provider", - "description": "Get a single OIDC provider by name (admin only).", + "description": "Get a single OIDC provider by name, 404 for one of an org the caller does not manage.", "operationId": "auth.oidc-providers.get", "parameters": [ { @@ -4781,7 +5593,7 @@ "OIDC Providers" ], "summary": "Update Provider", - "description": "Update an OIDC provider configuration (admin only).\n\nA secret the body omits, value and env var name alike, keeps what the provider already holds, so an update that only flips ``enabled`` does not strand a stored credential. An empty env var name clears the name and keeps the stored copy. A secret the body names an env var for and sends no value for moves onto that env var and its stored copy is deleted once the update is saved, unless the name is the one already held with nothing stored. A move onto an env var the engine does not set is refused (``env_var_not_set``). Any update that touches more than ``enabled`` or ``display_name`` must leave the provider passing the field rules. Both are checked before a secret is written or deleted.", + "description": "Update an OIDC provider configuration (admin only).\n\nA secret the body omits, value and env var name alike, keeps what the provider already holds, so an update that only flips ``enabled`` does not strand a stored credential. An empty env var name clears the name and keeps the stored copy. A secret the body names an env var for and sends no value for moves onto that env var and its stored copy is deleted once the update is saved, unless the name is the one already held with nothing stored. A move onto an env var the engine does not set is refused (``env_var_not_set``). Any update that touches more than ``enabled``, ``display_name`` and ``trusted_email_domains`` must leave the provider passing the field rules. Both are checked before a secret is written or deleted.", "operationId": "auth.oidc-providers.apply", "parameters": [ { @@ -4792,6 +5604,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "requestBody": { @@ -4883,7 +5707,7 @@ "OIDC Providers" ], "summary": "Delete Provider", - "description": "Detach an OIDC provider and soft-delete its accounts (admin only).\n\nDoes NOT delete groups -- they become orphaned with their source_provider\nstill set to the deleted provider name. Accounts owned by the provider\n(``source_provider``) or last logged in through it (``oidc_id``) are\nsoft-deleted: disabled and renamed to ``{uuid}-deleted`` with contact fields\ncleared. The provider's stored credentials ARE removed: nothing is left that\ncan authenticate as a detached provider.", + "description": "Detach an OIDC provider and soft-delete its accounts (admin only).\n\nDoes NOT delete groups -- they become orphaned with their source_provider\nstill set to the deleted provider name. Accounts owned by the provider\n(``source_provider``) or last logged in through it (``oidc_id``) are\nsoft-deleted: disabled and renamed to ``{uuid}-deleted`` with contact fields\ncleared. A sign-in linked through it to another account is unlinked and that\naccount's sessions end, but the account stays. The provider's stored credentials\nARE removed: nothing is left that can authenticate as a detached provider.", "operationId": "auth.oidc-providers.delete", "parameters": [ { @@ -4894,6 +5718,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -4988,6 +5824,18 @@ "type": "string", "title": "Name" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -15836,7 +16684,7 @@ "queries" ], "summary": "Execute View", - "description": "Execute a parameterized view and return JSON results.\n\nThe ``org_id`` parameter is always injected from the authenticated\nuser's context -- it cannot be overridden by the client. It is the org the\nsession's account is bound to, and a view taking it runs only when the caller's\ngroups grant that org or it reads every org (``granted_bound_org``).", + "description": "Execute a parameterized view and return JSON results.\n\nThe ``org_id`` parameter is always injected from the authenticated\nuser's context -- it cannot be overridden by the client. It is the org the\nsession's account is bound to, and a view taking it runs only when the caller's\ngroups grant that org or it reads every org (``granted_bound_org``). Any other\nview needs ``query:execute`` at system scope.", "operationId": "queries.views.execute", "parameters": [ { @@ -20855,6 +21703,20 @@ "summary": "Create User", "description": "Provision a user. IdP-owned. Local password is randomised when omitted.\n\nA password the IdP does send is held to the same length floor as every other\npassword the API sets, and one under it is refused rather than replaced.", "operationId": "scim.v2.users.create", + "parameters": [ + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" + } + ], "responses": { "200": { "description": "Successful Response", @@ -20884,6 +21746,16 @@ } } }, + "422": { + "description": "Validation Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, "default": { "description": "Problem details (RFC 9457)", "content": { @@ -21027,6 +21899,18 @@ "type": "string", "title": "User Id" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -21118,6 +22002,18 @@ "type": "string", "title": "User Id" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -21209,6 +22105,18 @@ "type": "string", "title": "User Id" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -21363,6 +22271,20 @@ "summary": "Create Group", "description": "Provision a group with its member set (member Account.groups kept in sync).", "operationId": "scim.v2.groups.create", + "parameters": [ + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" + } + ], "responses": { "200": { "description": "Successful Response", @@ -21392,6 +22314,16 @@ } } }, + "422": { + "description": "Validation Error", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/Problem" + } + } + } + }, "default": { "description": "Problem details (RFC 9457)", "content": { @@ -21535,6 +22467,18 @@ "type": "string", "title": "Group Id" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -21626,6 +22570,18 @@ "type": "string", "title": "Group Id" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -21717,6 +22673,18 @@ "type": "string", "title": "Group Id" } + }, + { + "name": "X-DFE-Reauth", + "in": "header", + "required": false, + "schema": { + "type": "string", + "description": "The grant POST /auth/reauth returned for this change", + "default": "", + "title": "X-Dfe-Reauth" + }, + "description": "The grant POST /auth/reauth returned for this change" } ], "responses": { @@ -35404,6 +36372,25 @@ "title": "APIKeyResponse", "description": "API key metadata -- key_hash is NEVER included." }, + "AccountAvailabilityResponse": { + "properties": { + "email": { + "type": "string", + "title": "Email", + "description": "Why the email cannot be used, empty when it can or none was given", + "default": "" + }, + "username": { + "type": "string", + "title": "Username", + "description": "Why the username cannot be taken, empty when it can or none was given", + "default": "" + } + }, + "type": "object", + "title": "AccountAvailabilityResponse", + "description": "Why creating an account with these values would be refused, empty where it would not." + }, "AccountGitPending": { "properties": { "pr_url": { @@ -35543,17 +36530,55 @@ "description": "The registered org the account belongs to, which its sessions carry as org_id. Empty makes it a root account, bound to your org (GET /system/organisation), or to none while no org is yours. The binding grants nothing itself: an org-bound view also needs the org among those its groups grant.", "default": "" }, + "org_display_name": { + "type": "string", + "title": "Org Display Name", + "description": "The display name of the org the account is bound to, which for a root account is your org, else that org's name when it has none. Empty while it is bound to none.", + "default": "" + }, "external": { "type": "boolean", "title": "External", "description": "True when the account authenticates through an identity provider" }, + "admin": { + "type": "boolean", + "title": "Admin", + "description": "True when a system-wide group gives the account the admin role, so it has full access to every org. The account's own read reports false while password_change_required is set.", + "default": false + }, "oidc_id": { "type": "string", "title": "Oidc Id", "description": "OIDC provider name last used to log this account in, empty if none", "default": "" }, + "oidc_type": { + "type": "string", + "title": "Oidc Type", + "description": "The type of the provider oidc_id names, empty when it names no registered provider", + "default": "" + }, + "email_verified": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Email Verified", + "description": "Whether the email is vouched for, so a first IdP sign-in with it links to this account: true when an admin set it or a trusted identity provider verified it, false when the account owner set it or the provider did not vouch, null when it was stored before this was recorded" + }, + "identities": { + "items": { + "$ref": "#/components/schemas/LinkedIdentityResponse" + }, + "type": "array", + "title": "Identities", + "description": "IdP sign-ins linked to this account, each reaching it without a password" + }, "password_change_required": { "type": "boolean", "title": "Password Change Required", @@ -38882,9 +39907,9 @@ }, "name": { "type": "string", + "minLength": 1, "title": "Name", - "description": "Display name", - "default": "" + "description": "Display name" }, "org": { "type": "string", @@ -38896,10 +39921,11 @@ "type": "object", "required": [ "username", - "password" + "password", + "name" ], "title": "CreateAccountRequest", - "description": "What a console sends to create an account.\n\nOnly the credentials are required. The setup wizard creates the first user\nfrom a form that collects no contact details, so a required field here is a\ndeployment that cannot get into its own console." + "description": "What a console sends to create an account: the credentials and a display name, with the contact fields optional." }, "CreateArtifactRequest": { "properties": { @@ -39085,6 +40111,12 @@ "title": "Type", "description": "Provider type: generic, google, entra_id, okta" }, + "org": { + "type": "string", + "title": "Org", + "description": "The org whose provider this is: a registered org's name, or empty for a platform provider. Its sign-ins land in that org as viewers and link only to that org's accounts. An admin of that org manages it.", + "default": "" + }, "enabled": { "type": "boolean", "title": "Enabled", @@ -39144,6 +40176,14 @@ }, "groups": { "$ref": "#/components/schemas/GroupResolutionRequest" + }, + "trusted_email_domains": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Trusted Email Domains", + "description": "Email domains this provider vouches for, such as corp.com. A first sign-in whose verified email is in one of them links to the one account holding that email: at once for an account an identity provider owns, after the account's password for a local one. Stored lowercased. Empty links nothing." } }, "type": "object", @@ -41157,6 +42197,14 @@ "type": "array", "title": "Members" }, + "linked_members": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Linked Members", + "description": "Accounts that hold the group through an IdP sign-in its link matches, beside the stored members. Read-only: writing members never sets them." + }, "scope": { "type": "string", "title": "Scope" @@ -42996,6 +44044,55 @@ "title": "LinkStatusModel", "description": "A link, with how the content in the file set compares to the artefact." }, + "LinkedIdentityResponse": { + "properties": { + "key": { + "type": "string", + "title": "Key", + "description": "The sign-in's key, which unlinking names" + }, + "provider": { + "type": "string", + "title": "Provider", + "description": "The OIDC provider it signs in through" + }, + "provider_type": { + "type": "string", + "title": "Provider Type", + "description": "The provider's type (google, entra_id, okta or generic), empty once it is no longer registered", + "default": "" + }, + "subject": { + "type": "string", + "title": "Subject", + "description": "The IdP subject (sub)" + }, + "email": { + "type": "string", + "title": "Email", + "description": "The email its IdP last asserted", + "default": "" + }, + "linked_at": { + "type": "string", + "title": "Linked At", + "default": "" + }, + "last_login_at": { + "type": "string", + "title": "Last Login At", + "default": "" + } + }, + "type": "object", + "required": [ + "key", + "provider", + "subject" + ], + "title": "LinkedIdentityResponse", + "description": "An IdP sign-in linked to an account, which reaches it without a password." + }, "LogEntryModel": { "properties": { "sha": { @@ -43178,7 +44275,7 @@ "username": { "type": "string", "title": "Username", - "description": "Account name (admin, operator, viewer)" + "description": "Account name, or the email of a local account" }, "password": { "type": "string", @@ -43893,6 +44990,11 @@ "title": "Type", "default": "generic" }, + "org": { + "type": "string", + "title": "Org", + "default": "" + }, "enabled": { "type": "boolean", "title": "Enabled", @@ -43936,6 +45038,13 @@ "groups": { "$ref": "#/components/schemas/GroupResolutionConfig" }, + "trusted_email_domains": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Trusted Email Domains" + }, "created_at": { "type": "string", "title": "Created At", @@ -44223,6 +45332,27 @@ "title": "OidcCallbackResponse", "description": "Engine token minted after a successful IdP callback." }, + "OidcLinkRequest": { + "properties": { + "password": { + "type": "string", + "title": "Password", + "description": "The local account's password" + }, + "ticket": { + "type": "string", + "title": "Ticket", + "description": "The link_ticket a link_required callback answered with" + } + }, + "type": "object", + "required": [ + "password", + "ticket" + ], + "title": "OidcLinkRequest", + "description": "Body for linking a held IdP sign-in to its local account with that account's password." + }, "OidcLoginResponse": { "properties": { "authorization_url": { @@ -44242,6 +45372,34 @@ "title": "OidcLoginResponse", "description": "JSON body for GET .../login when ``redirect=false``." }, + "OidcReauthRequest": { + "properties": { + "kind": { + "$ref": "#/components/schemas/ReauthKind", + "description": "What the target names", + "default": "account" + }, + "return_to": { + "type": "string", + "title": "Return To", + "description": "Where the callback sends the browser, with the grant in the URL fragment (#reauth_grant=...&expires_in=...) or the refusal's code (#error=&provider=...). A relative path, or an absolute URL on this API's origin or a CORS-allowed origin." + }, + "target": { + "type": "string", + "maxLength": 128, + "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$", + "title": "Target", + "description": "The account, group, role, sign-in provider or API key you are about to change" + } + }, + "type": "object", + "required": [ + "return_to", + "target" + ], + "title": "OidcReauthRequest", + "description": "The account or group you are about to change, and where the sign-in hands its grant back." + }, "Operation_TaskInfo_Any_": { "properties": { "name": { @@ -47132,6 +48290,11 @@ "type": "string", "title": "Type" }, + "org": { + "type": "string", + "title": "Org", + "description": "The org whose provider this is: a registered org's name, or empty for a platform provider. Its sign-ins land in that org as viewers and link only to that org's accounts. An admin of that org manages it." + }, "enabled": { "type": "boolean", "title": "Enabled" @@ -47171,6 +48334,14 @@ "groups": { "$ref": "#/components/schemas/GroupResolutionResponse" }, + "trusted_email_domains": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Trusted Email Domains", + "description": "Email domains this provider vouches for, such as corp.com. A first sign-in whose verified email is in one of them links to the one account holding that email: at once for an account an identity provider owns, after the account's password for a local one. Stored lowercased. Empty links nothing." + }, "created_at": { "type": "string", "title": "Created At" @@ -47208,6 +48379,7 @@ "required": [ "name", "type", + "org", "enabled", "display_name", "issuer", @@ -47217,6 +48389,7 @@ "client_secret_path", "scopes", "groups", + "trusted_email_domains", "created_at", "last_sync_at", "last_sync_status", @@ -47705,6 +48878,65 @@ "config_write" ] }, + "ReauthKind": { + "type": "string", + "enum": [ + "account", + "api_key", + "group", + "provider", + "role" + ] + }, + "ReauthRequest": { + "properties": { + "kind": { + "$ref": "#/components/schemas/ReauthKind", + "description": "What the target names", + "default": "account" + }, + "password": { + "type": "string", + "title": "Password", + "description": "Your own password" + }, + "target": { + "type": "string", + "maxLength": 128, + "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$", + "title": "Target", + "description": "The account, group, role, sign-in provider or API key you are about to change" + } + }, + "type": "object", + "required": [ + "password", + "target" + ], + "title": "ReauthRequest", + "description": "Your own password, and the account you are about to edit." + }, + "ReauthResponse": { + "properties": { + "grant": { + "type": "string", + "title": "Grant", + "description": "Send it as the X-DFE-Reauth header on every edit of that account" + }, + "expires_in": { + "type": "integer", + "title": "Expires In", + "description": "Seconds the grant stays valid" + } + }, + "type": "object", + "required": [ + "grant", + "expires_in" + ], + "title": "ReauthResponse", + "description": "A grant for editing one account." + }, "RelinkResult": { "properties": { "changed": { @@ -55400,6 +56632,18 @@ }, "UpdateProviderRequest": { "properties": { + "org": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Org", + "description": "Move the provider to another org. The org whose provider this is: a registered org's name, or empty for a platform provider. Its sign-ins land in that org as viewers and link only to that org's accounts. An admin of that org manages it." + }, "enabled": { "anyOf": [ { @@ -55509,6 +56753,21 @@ } ], "description": "Group resolution config" + }, + "trusted_email_domains": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Trusted Email Domains", + "description": "Replace the trusted email domains. Email domains this provider vouches for, such as corp.com. A first sign-in whose verified email is in one of them links to the one account holding that email: at once for an account an identity provider owns, after the account's password for a local one. Stored lowercased. Empty links nothing." } }, "type": "object", diff --git a/scripts/route-plan.toml b/scripts/route-plan.toml index d14397fa8..6c2f3a8b2 100644 --- a/scripts/route-plan.toml +++ b/scripts/route-plan.toml @@ -41,6 +41,7 @@ routes = [ { old = "GET /api/v1/apps/{service}/{instance}/values", status = "decide", note = "apps-depth" }, { old = "GET /api/v1/auth/accounts", new = "GET /api/v1/identity/accounts", status = "moved" }, { old = "POST /api/v1/auth/accounts", new = "PUT /api/v1/identity/accounts/{account}", status = "merged", note = "apply-creates" }, + { old = "GET /api/v1/auth/accounts/availability", new = "PUT /api/v1/identity/accounts/{account}", status = "merged", note = "validate-dry-run" }, { old = "GET /api/v1/auth/accounts/me", status = "decide", note = "accounts-me" }, { old = "PUT /api/v1/auth/accounts/me", status = "decide", note = "accounts-me" }, { old = "POST /api/v1/auth/accounts/reset-password", status = "decide", note = "accounts-me" }, @@ -50,6 +51,7 @@ routes = [ { old = "GET /api/v1/auth/accounts/{username}/attributes", new = "GET /api/v1/identity/accounts/{account}/attributes", status = "moved" }, { old = "PUT /api/v1/auth/accounts/{username}/attributes", new = "PUT /api/v1/identity/accounts/{account}/attributes", status = "moved" }, { old = "GET /api/v1/auth/accounts/{username}/git-status", new = "GET /api/v1/identity/accounts/{account}/git-status", verb = "git-status", status = "moved" }, + { old = "DELETE /api/v1/auth/accounts/{username}/identities/{key}", new = "DELETE /api/v1/identity/accounts/{account}/identities/{identity}", status = "moved" }, { old = "POST /api/v1/auth/accounts/{username}/reset-password", new = "POST /api/v1/identity/accounts/{account}/reset-password", status = "moved" }, { old = "POST /api/v1/auth/accounts/{username}/rotate-password", new = "POST /api/v1/identity/accounts/{account}/rotate-password", status = "moved" }, { old = "GET /api/v1/auth/accounts/{username}/sensitive-attributes", new = "GET /api/v1/identity/accounts/{account}/sensitive-attributes", status = "moved" }, @@ -79,9 +81,12 @@ routes = [ { old = "POST /api/v1/auth/oidc-providers/{name}/sync", new = "POST /api/v1/identity/oidc-providers/{provider}/sync", status = "moved" }, { old = "GET /api/v1/auth/oidc-providers/{name}/test", new = "GET /api/v1/identity/oidc-providers/{provider}/test", verb = "test", status = "moved" }, { old = "GET /api/v1/auth/oidc-providers/{name}/verify-login", new = "GET /api/v1/identity/oidc-providers/{provider}/verify-login", verb = "verify-login", status = "moved" }, + { old = "POST /api/v1/auth/oidc/link", status = "frozen", note = "protocol" }, + { old = "POST /api/v1/auth/oidc/reauth", status = "frozen", note = "protocol" }, { old = "GET /api/v1/auth/oidc/{provider}/callback", status = "frozen", note = "protocol" }, { old = "GET /api/v1/auth/oidc/{provider}/login", status = "frozen", note = "protocol" }, { old = "GET /api/v1/auth/permissions", status = "frozen", note = "protocol" }, + { old = "POST /api/v1/auth/reauth", status = "frozen", note = "protocol" }, { old = "POST /api/v1/auth/refresh", status = "frozen", note = "protocol" }, { old = "GET /api/v1/auth/roles", new = "GET /api/v1/identity/roles", status = "moved" }, { old = "POST /api/v1/auth/roles", new = "PUT /api/v1/identity/roles/{role}", status = "merged", note = "apply-creates" }, diff --git a/src/dfe_engine/api/app.py b/src/dfe_engine/api/app.py index 646f674a1..e027ca577 100644 --- a/src/dfe_engine/api/app.py +++ b/src/dfe_engine/api/app.py @@ -598,7 +598,16 @@ def reconcile_service_roles_now() -> ReconcileResult: app.state.org_lifecycle = OrgLifecycleManager( registry=app.state.org_registry, hyperdx_client=hdx_client, + group_store=app.state.group_store, ) + # Seeded orgs skip the lifecycle, so every org's admin and viewer groups are made here too. + from dfe_engine.orgs.role_groups import ensure_org_role_groups + + for org in app.state.org_registry.list(): + try: + ensure_org_role_groups(group_store=app.state.group_store, org=org.name) + except (OSError, ValueError) as exc: # a missing group must never break startup + logger.warning("org role groups not created", org=org.name, error=str(exc)) # Bootstrap JIT provisioner from dfe_engine.auth.jit import JitProvisioner @@ -611,6 +620,8 @@ def reconcile_service_roles_now() -> ReconcileResult: # admin stays out of an IdP's reach. admin_name=settings.auth.local.admin_name, source_provider_bindings=settings.auth.source_provider_bindings, + home_org=app.state.org_registry.home_name_known, + provider_registry=app.state.oidc_provider_registry, ) # Bootstrap task manager for async background tasks diff --git a/src/dfe_engine/api/deps.py b/src/dfe_engine/api/deps.py index dd642930f..ec3be7403 100644 --- a/src/dfe_engine/api/deps.py +++ b/src/dfe_engine/api/deps.py @@ -14,7 +14,7 @@ from datetime import timedelta from typing import TYPE_CHECKING, Annotated, Any, NamedTuple -from fastapi import Depends, Request, status +from fastapi import Depends, Header, Request, status from fastapi.dependencies.models import Dependant from fastapi.routing import APIRoute, iter_route_contexts from scalo.api import ProblemError, permission @@ -33,6 +33,7 @@ audit_permission_denied, ) from dfe_engine.auth.groups import Group, GroupStore +from dfe_engine.auth.identity_links import linked_person, linked_through from dfe_engine.auth.jit import ( API_KEY_SUBJECT_PREFIX, JitAccountUnavailableError, @@ -40,12 +41,14 @@ JitNoRoleError, JitSubjectUnusableError, ) -from dfe_engine.auth.membership import groups_held, groups_held_by -from dfe_engine.auth.models import held_grants, is_platform_role, platform_caller +from dfe_engine.auth.membership import groups_held_by +from dfe_engine.auth.models import ORG_ADMIN_ROLE, held_grants, is_platform_role, platform_caller +from dfe_engine.auth.reauth import REAUTH_HEADER, ReauthKind, grant_allows, grant_target from dfe_engine.auth.roles import RoleConfig from dfe_engine.auth.sessions import session_ended from dfe_engine.gitcrud.retention import effective_settings from dfe_engine.http_errors import describe_http_error, failure_reference +from dfe_engine.orgs.role_groups import org_role_groups_held from dfe_engine.orgs.tenancy import Tenancy from dfe_engine.orgs.tenant_scope import org_tenant_ids, resolve_orgs from dfe_engine.secrets import DfeSecrets, build_secret_mirror, build_secrets @@ -467,6 +470,9 @@ def _grants_of(groups: Iterable[Group]) -> GroupResolution: claimed = group.org_markers org_ids.update(claimed) for role in group.roles: + if (role == ORG_ADMIN_ROLE) and (not (scope_org)): + # Bound at system scope it would administer every org, so it grants nothing there. + continue roles.add(role) grant = ScopedGrant(role=role, scope=scope, org_ids=claimed) if grant not in seen_grants: @@ -508,6 +514,14 @@ def bound_account(request: Request, user_id: str) -> Any: return account_for_session_subject(account_store, user_id) +def is_own_account(*, request: Request, user: AuthContext, username: str) -> bool: + """Whether *username* is the caller's own account, whichever subject its session carries.""" + if username == user.user_id: + return True + bound = bound_account(request, user.user_id) + return (bound is not None) and (bound.username == username) + + def get_role_config(request: Request) -> RoleConfig: """The role definitions ``authorize()`` reads: the live copy role writes refresh, else the shipped ones.""" return live_role_config(request) or RoleConfig.load_builtin() @@ -539,7 +553,7 @@ def resolve_live_grants_for_user( The account is the one :func:`account_for_session_subject` binds, so a subject that binds none, an API-key subject among them, resolves to nothing. The resolution's - ``groups`` are the ones the account holds (:func:`groups_held`). *groups* is every + ``groups`` are the ones the account holds (:func:`groups_held`) less any its org may not (:func:`org_role_groups_held`). *groups* is every stored group when the caller has listed them for this request. Otherwise they are listed here, once. """ @@ -554,18 +568,20 @@ def resolve_live_grants_for_user( account.source_provider, listed, bindings=provider_bindings(request), + identities=account.identities, + ) + # Fail closed: however an org account came to hold a group, its grants stay inside its org. + held = org_role_groups_held( + account_org=account.org, groups=held, home_org=bound_org(account_org="", request=request) ) return _grants_of(held) -def resolve_live_groups_for_user(request: Request, user_id: str) -> list[str]: - """The groups the bound account holds (:func:`groups_held`), none when it binds none.""" - account = bound_account(request, user_id) - if account is None: - return [] - group_store: GroupStore | None = getattr(request.app.state, "group_store", None) - groups = group_store.list() if group_store is not None else [] - return groups_held(account, groups, bindings=provider_bindings(request)) +def _person_behind(*, record: Any, store: Any) -> Any: + """The account *record* stands for: itself, or the one a link record points at while that account still lists the sign-in.""" + if not (record.is_link_record): + return record + return linked_person(record=record, store=store) def account_for_session_subject(store: Any, user_id: str): @@ -578,13 +594,16 @@ def account_for_session_subject(store: Any, user_id: str): alone, so ``Bob`` never binds the local ``bob``. An API-key subject binds no account. Several subjects sanitise to one stem, and a subject can be another's stem, so an account that records another subject is not this - session's whichever lookup found it. + session's whichever lookup found it. A link record binds the account it points + at, one hop, and nothing once that account no longer lists the sign-in. """ if user_id.startswith(API_KEY_SUBJECT_PREFIX): return None account = store.get(user_id) if account is not None: - return None if account.subject and account.subject != user_id else account + if account.subject and account.subject != user_id: + return None + return _person_behind(record=account, store=store) from dfe_engine.auth.jit import JitProvisioner stem = JitProvisioner.sanitise_username(user_id) @@ -595,7 +614,7 @@ def account_for_session_subject(store: Any, user_id: str): return None if shadow.subject and shadow.subject != user_id: return None - return shadow + return _person_behind(record=shadow, store=store) def require_local_account_enabled(request: Request, user_id: str) -> Any: @@ -638,6 +657,19 @@ def refuse_denied_account(account: Any) -> None: ) +def throttled(request: Request, wait: int) -> ProblemError: + """The 429 a sign-in or password check answers while its caller must wait, counted.""" + metrics = getattr(request.app.state, "api_metrics", None) or ApiMetrics() + route = str(getattr(request.scope.get("route"), "path", "")) or "unknown" + metrics.sign_in_throttled(route) + return ProblemError( + 429, + f"Too many failed attempts; try again in {wait} seconds", + code="too_many_attempts", + headers={"Retry-After": str(wait)}, + ) + + async def get_current_user(request: Request) -> AuthContext: """Authenticate the request via one of four paths (checked in order). @@ -723,9 +755,11 @@ async def get_current_user(request: Request) -> AuthContext: # The token path's resolution, so a member an operator added by hand holds the group here too. live = resolve_live_grants_for_user(request, oidc_subject, groups=listed) logger.debug("OIDC auth", user_id=oidc_subject, groups=live.groups, roles=live.roles) + # A linked sign-in's session is its account's, as a token minted for it says. + linked = bound is not None and linked_through(account=bound, subject=oidc_subject) return AuthContext( org_id=bound_org(account_org=bound.org, request=request) if bound is not None else "", - user_id=oidc_subject, + user_id=bound.session_subject if linked else oidc_subject, email=oidc_email, roles=live.roles, grants=live.grants, @@ -759,12 +793,23 @@ async def get_current_user(request: Request) -> AuthContext: }.get(reason, "Invalid API key") raise ProblemError(status.HTTP_401_UNAUTHORIZED, message, code="unauthorized") group_store = request.app.state.group_store - resolution = _resolve_group_grants(key_meta.groups, group_store) + key_groups = key_meta.groups + home = bound_org(account_org="", request=request) + if (key_meta.org) and (key_meta.org != home): + # An org-bound key holds only its org's admin or viewer groups, by name, as an org account does. + allowed = { + group.name + for group in org_role_groups_held( + account_org=key_meta.org, groups=group_store.list(), home_org=home + ) + } + key_groups = [name for name in key_groups if name in allowed] + resolution = _resolve_group_grants(key_groups, group_store) roles, org_ids = resolution.roles, resolution.org_ids logger.debug( "API key auth", key_name=key_meta.name, - groups=key_meta.groups, + groups=key_groups, roles=roles, ) return AuthContext( @@ -772,7 +817,7 @@ async def get_current_user(request: Request) -> AuthContext: user_id=f"{API_KEY_SUBJECT_PREFIX}{key_meta.name}", roles=roles, grants=resolution.grants, - groups=key_meta.groups, + groups=key_groups, org_ids=org_ids, request_id=request_id, client_ip=client_ip, @@ -970,6 +1015,32 @@ def allowed_at_system_or_own_org(request: Request, user: AuthContext, action: st return is_action_allowed(request, user, action) or bool(held_orgs(request, user, action)) +def reaches_org(*, action: str, org: str, request: Request, user: AuthContext) -> bool: + """Whether the caller may take *action* on what *org* owns: across every org, or in *org* when it is an org other than yours. + + Empty *org*, or your org's name, is the platform's own, which only a caller acting across every org reaches. + """ + if not (request.app.state.settings.auth.enabled): + return True + if reads_every_org(request, user, action): + return True + if (not (org)) or (org == bound_org(account_org="", request=request)): + return False + return org in {held.name for held in held_orgs(request, user, action)} + + +def refuse_unreachable_org( + *, action: str, noun: str, org: str, request: Request, user: AuthContext +) -> None: + """Refuse 403 when the caller may not take *action* on the *noun* of *org* (:func:`reaches_org`).""" + if reaches_org(action=action, org=org, request=request, user=user): + return + target = f"{noun} of org {org!r}" if org else f"the platform's {noun}" + reason = f"no role grants {action!r} over {target}" + audit_permission_denied(user.user_id, action, user.roles, reason) + raise AuthorizationError(f"Action '{action}' denied: {reason}") + + def reads_every_org(request: Request, user: AuthContext, action: str) -> bool: """Whether a grant that may read across orgs (``platform_grants``) allows ``action``. @@ -1237,6 +1308,51 @@ async def _check( return _check +def refuse_without_grant(*, reauth: str, request: Request, target: str, user: AuthContext) -> None: + """Refuse 403 ``reauth_required`` unless *reauth* is the caller's live grant for *target*. + + An API-key session carries none and needs none: nobody is there to re-enter a password. + """ + settings = request.app.state.settings + if (not (settings.auth.enabled)) or (user.user_id.startswith(API_KEY_SUBJECT_PREFIX)): + return + authority = jwt_authority_for(settings) + if (reauth) and ( + grant_allows(authority=authority, caller=user.user_id, target=target, token=reauth) + ): + return + raise ProblemError(403, "Re-enter your password to make this change", code="reauth_required") + + +ReauthGrant = Annotated[ + str, + Header(alias=REAUTH_HEADER, description="The grant POST /auth/reauth returned for this change"), +] + + +def require_reauth(*, kind: ReauthKind, param: str): + """FastAPI dependency factory: the caller's re-auth grant for the *kind* the path parameter *param* names (:func:`refuse_without_grant`).""" + + async def _check( + request: Request, + reauth: ReauthGrant = "", + user: AuthContext = Depends(get_current_user), + ) -> None: + target = grant_target(kind=kind, name=str(request.path_params.get(param, ""))) + refuse_without_grant(reauth=reauth, request=request, target=target, user=user) + + return _check + + +require_account_reauth = require_reauth(kind="account", param="username") +require_api_key_reauth = require_reauth(kind="api_key", param="short_token") +require_group_reauth = require_reauth(kind="group", param="name") +require_provider_reauth = require_reauth(kind="provider", param="name") +require_role_reauth = require_reauth(kind="role", param="name") +require_scim_group_reauth = require_reauth(kind="group", param="group_id") +require_scim_user_reauth = require_reauth(kind="account", param="user_id") + + def require_own_org_action(action: str): """FastAPI dependency factory: ``action`` held at system scope or at one of the caller's orgs. diff --git a/src/dfe_engine/api/v1/account_groups.py b/src/dfe_engine/api/v1/account_groups.py index be5b99b76..cd92d50e7 100644 --- a/src/dfe_engine/api/v1/account_groups.py +++ b/src/dfe_engine/api/v1/account_groups.py @@ -42,14 +42,18 @@ from dfe_engine.api.conventions import apply_search from dfe_engine.api.deps import ( CurrentUser, + ReauthGrant, bound_account, + bound_org, check_action, groups_granting, is_action_allowed, live_role_config, provider_bindings, reads_every_org, + refuse_without_grant, require_action, + require_group_reauth, require_platform_action, ) from dfe_engine.auth import AuthorizationError, RoleConfig, Scope @@ -61,11 +65,14 @@ source_id_holder, validate_group_scope, ) -from dfe_engine.auth.models import ungrantable_roles +from dfe_engine.auth.membership import groups_held_by +from dfe_engine.auth.models import ORG_ADMIN_ROLE, ungrantable_roles from dfe_engine.auth.rbac_scopes import scopes_dict +from dfe_engine.auth.reauth import grant_target from dfe_engine.auth.scim_mapping import SCIM_SOURCE_PROVIDER from dfe_engine.governance.ch import request_ch_rbac_reconcile from dfe_engine.names import StoreName +from dfe_engine.orgs.role_groups import org_role_breach from dfe_engine.yaml_utils import YAMLError router = APIRouter(prefix="/groups", tags=["Groups"]) @@ -136,6 +143,11 @@ class GroupResponse(BaseModel): description: str roles: list[str] members: list[str] + linked_members: list[str] = Field( + default_factory=list, + description="Accounts that hold the group through an IdP sign-in its link matches, " + "beside the stored members. Read-only: writing members never sets them.", + ) scope: str source_id: str source_provider: str @@ -209,6 +221,17 @@ def _visible_group(request: Request, user, name: str) -> Group: return group +def _refuse_org_admin_at_system_scope(*, name: str, roles: Iterable[str], scope: str) -> None: + """Refuse 422 ``org_admin_org_only`` when the system group *name* would grant ``org_admin``, which binds only at an org's scope.""" + if (ORG_ADMIN_ROLE in roles) and (not (scope.startswith("org:"))): + raise ProblemError( + 422, + f"Role {ORG_ADMIN_ROLE!r} is bound only at an org's scope, so system group " + f"{name!r} may not grant it", + code="org_admin_org_only", + ) + + def _refuse_link_below_system_scope(request: Request, user) -> None: """Refuse a link change from a caller without group:write system-wide. @@ -229,9 +252,10 @@ def _refuse_link_below_system_scope(request: Request, user) -> None: raise AuthorizationError(reason) -def _response(group: Group) -> GroupResponse: +def _response(group: Group, *, linked_members: Iterable[str] = ()) -> GroupResponse: return GroupResponse( description=group.description, + linked_members=[member for member in linked_members if member not in group.members], members=group.members, name=group.name, roles=group.roles, @@ -403,6 +427,77 @@ def check_group_changes( ) +def _org_role_message(*, account_org: str, group: str, username: str) -> str: + """The refusal naming *username*, its org and the group it may not hold.""" + return ( + f"Account {username!r} belongs to org {account_org!r}, and an org account holds " + f"only its own org's admin or viewer group, so group {group!r} is refused" + ) + + +def _link_holders(*, groups: Iterable[Group], request: Request) -> dict[str, list[str]]: + """The accounts holding each linked group in *groups* through an IdP sign-in its link matches, by group name, read in one pass over the accounts.""" + unlisted = [group.model_copy(update={"members": []}) for group in groups if group.source_id] + if not (unlisted): + return {} + bindings = provider_bindings(request) + holders = {group.name: [] for group in unlisted} + for account in request.app.state.account_store.scan(): + if (account.is_link_record) or (account.is_soft_deleted): + continue + held = groups_held_by( + account.username, + account.groups, + account.source_provider, + unlisted, + bindings=bindings, + identities=account.identities, + ) + for group in held: + holders[group.name].append(account.username) + return holders + + +def org_link_holders(*, group: Group, request: Request) -> list[str]: + """The accounts that would hold *group*, as it would be stored, through an IdP sign-in its link matches.""" + return _link_holders(groups=[group], request=request).get(group.name, []) + + +def org_role_refusal(*, group: Group, members: Iterable[str], request: Request) -> str | None: + """Why *group*, as it would be stored, may not be held by one of *members*, else None.""" + store = request.app.state.account_store + home = bound_org(account_org="", request=request) + for username in sorted(set(members)): + account = store.get(username) + if account is None: + continue + breach = org_role_breach(account_org=account.org, groups=[group], home_org=home) + if breach is not None: + return _org_role_message(account_org=account.org, group=breach, username=username) + return None + + +def refuse_org_role_breach( + *, account_org: str, groups: Iterable[Group], request: Request, username: str +) -> None: + """Refuse 422 ``org_role_only`` when an account of an org other than yours would hold *groups* outside that org's admin and viewer roles.""" + home = bound_org(account_org="", request=request) + breach = org_role_breach(account_org=account_org, groups=groups, home_org=home) + if breach is not None: + raise ProblemError( + 422, + _org_role_message(account_org=account_org, group=breach, username=username), + code="org_role_only", + ) + + +def refuse_org_role_members(*, group: Group, members: Iterable[str], request: Request) -> None: + """Refuse 422 ``org_role_only`` when *group*, as it would be stored, may not be held by one of *members*.""" + refusal = org_role_refusal(group=group, members=members, request=request) + if refusal is not None: + raise ProblemError(422, refusal, code="org_role_only") + + def _refuse_last_admin_member_removals( request: Request, *, @@ -431,7 +526,20 @@ def _refuse_last_admin_member_removals( # -- Endpoints ------------------------------------------------ -@router.post("", response_model=GroupResponse, status_code=201) +async def require_new_group_reauth( + body: CreateGroupRequest, request: Request, user: CurrentUser, reauth: ReauthGrant = "" +) -> None: + """FastAPI dependency: the caller's re-auth grant for the group the body creates.""" + target = grant_target(kind="group", name=body.name) + refuse_without_grant(reauth=reauth, request=request, target=target, user=user) + + +@router.post( + "", + response_model=GroupResponse, + status_code=201, + dependencies=[Depends(require_new_group_reauth)], +) async def create_group( body: CreateGroupRequest, user: CurrentUser, @@ -449,6 +557,7 @@ async def create_group( target = Group(name=body.name, scope=body.scope) check_action(request, user, scopes_dict["group_write"], scope=scope_of(target)) + _refuse_org_admin_at_system_scope(name=body.name, roles=body.roles, scope=body.scope) if body.source_id or body.source_provider: _refuse_link_below_system_scope(request, user) check_role_assignment(request, user, body.roles, scope_of(target)) @@ -458,7 +567,6 @@ async def create_group( # With no registry to check against, no org is known to exist. if org and (org_registry is None or org_registry.get(org) is None): raise ProblemError(422, f"Org '{org}' not found", code="invalid_scope") - changes_source_id, changes_source_provider = _link_changes( before=None, source_id=body.source_id, source_provider=body.source_provider ) @@ -470,6 +578,19 @@ async def create_group( source_id=body.source_id, source_provider=body.source_provider, ) + # After the link checks: a Group cannot hold a source_id without its provider. + stored = Group( + name=body.name, + roles=body.roles, + scope=body.scope, + source_id=body.source_id, + source_provider=body.source_provider, + ) + refuse_org_role_members( + group=stored, + members=[*body.members, *org_link_holders(group=stored, request=request)], + request=request, + ) store: GroupStore = request.app.state.group_store account_store: AccountStore = request.app.state.account_store # Names are unique across every org, so a caller that cannot see every group learns only this. @@ -536,7 +657,8 @@ async def list_groups( member = _member_name(request, user) held = _held(request, user) visible = [g for g in store.list() if _visible(request, user, g, member, held)] - rows = [_response(g).model_dump() for g in visible] + linked = _link_holders(groups=visible, request=request) + rows = [_response(g, linked_members=linked.get(g.name, [])).model_dump() for g in visible] rows = apply_search(rows, search, ["name", "description"]) rows = sort_by_order(rows, query.order_by) summaries = [GroupResponse.model_validate(row) for row in rows] @@ -550,10 +672,12 @@ async def get_group( request: Request, ): """Get a single group by name (404 when not visible to the caller).""" - return _response(_visible_group(request, user, name)) + group = _visible_group(request, user, name) + linked = _link_holders(groups=[group], request=request) + return _response(group, linked_members=linked.get(group.name, [])) -@router.put("/{name}", response_model=GroupResponse) +@router.put("/{name}", response_model=GroupResponse, dependencies=[Depends(require_group_reauth)]) async def update_group( name: str, body: UpdateGroupRequest, @@ -569,6 +693,8 @@ async def update_group( account_store: AccountStore = request.app.state.account_store existing = _visible_group(request, user, name) check_action(request, user, scopes_dict["group_write"], scope=scope_of(existing)) + if body.roles is not None: + _refuse_org_admin_at_system_scope(name=name, roles=body.roles, scope=existing.scope) changes_members = body.members is not None and set(body.members) != set(existing.members) source_id = existing.source_id if body.source_id is None else body.source_id source_provider = ( @@ -594,6 +720,22 @@ async def update_group( ) if changes_source_id: _refuse_identifier_collision(groups=store.list(), name="", source_id=source_id, target=name) + if (body.roles is not None) or (changes_members) or (changes_link): + stored = existing.model_copy( + update={ + "roles": body.roles if body.roles is not None else existing.roles, + "source_id": source_id, + "source_provider": source_provider, + } + ) + # A members-only change leaves who signs in through the link as it was. + linked = ( + org_link_holders(group=stored, request=request) + if (body.roles is not None) or (changes_link) + else [] + ) + members = body.members if body.members is not None else existing.members + refuse_org_role_members(group=stored, members=[*members, *linked], request=request) update_fields: dict[str, object] = {} details: dict[str, object] = {} if body.roles is not None: @@ -645,7 +787,12 @@ async def update_group( return _response(group) -@router.post("/{name}/members", response_model=GroupResponse, status_code=200) +@router.post( + "/{name}/members", + response_model=GroupResponse, + status_code=200, + dependencies=[Depends(require_group_reauth)], +) async def add_member( name: str, body: AddMemberRequest, @@ -664,6 +811,7 @@ async def add_member( if body.username not in existing.members: # The new member takes every role the group carries. check_role_assignment(request, user, existing.roles, scope_of(existing)) + refuse_org_role_members(group=existing, members=[body.username], request=request) store.add_member(name, body.username) sync_account_groups_for_membership_change( account_store, @@ -677,7 +825,12 @@ async def add_member( return _response(group) -@router.delete("/{name}/members/{username}", response_model=GroupResponse, status_code=200) +@router.delete( + "/{name}/members/{username}", + response_model=GroupResponse, + status_code=200, + dependencies=[Depends(require_group_reauth)], +) async def remove_member( name: str, username: str, @@ -712,7 +865,7 @@ async def remove_member( return _response(group) -@router.delete("/{name}", status_code=204) +@router.delete("/{name}", status_code=204, dependencies=[Depends(require_group_reauth)]) async def delete_group( name: str, user: CurrentUser, @@ -770,7 +923,10 @@ async def get_group_attributes( @router.put( "/{name}/attributes", - dependencies=[Depends(require_action(scopes_dict["group_attributes_write"]))], + dependencies=[ + Depends(require_action(scopes_dict["group_attributes_write"])), + Depends(require_group_reauth), + ], ) async def put_group_attributes( name: str, @@ -814,7 +970,10 @@ async def get_group_sensitive_attributes( @router.put( "/{name}/sensitive-attributes", - dependencies=[Depends(require_action(scopes_dict["group_attributes_write_sensitive"]))], + dependencies=[ + Depends(require_action(scopes_dict["group_attributes_write_sensitive"])), + Depends(require_group_reauth), + ], ) async def put_group_sensitive_attributes( name: str, diff --git a/src/dfe_engine/api/v1/accounts.py b/src/dfe_engine/api/v1/accounts.py index a88ab5016..0eaf6f7aa 100644 --- a/src/dfe_engine/api/v1/accounts.py +++ b/src/dfe_engine/api/v1/accounts.py @@ -24,6 +24,8 @@ """ import functools +from collections.abc import Iterable, Mapping +from dataclasses import dataclass from typing import Annotated, Any from fastapi import APIRouter, Depends, Query, Request @@ -42,39 +44,57 @@ from dfe_engine.api.conventions import apply_search from dfe_engine.api.deps import ( CurrentUser, + ReauthGrant, Settings, _get_client_ip, account_for_session_subject, bound_org, + is_own_account, provider_bindings, + reaches_org, + reads_every_org, refuse_unknown_orgs, + refuse_unreachable_org, + refuse_without_grant, + registered_orgs, + require_account_reauth, require_action, + require_own_org_action, require_platform_action, secrets_store, + throttled, ) -from dfe_engine.api.v1.account_groups import check_group_changes -from dfe_engine.api.v1.auth import persist_session_end, throttled +from dfe_engine.api.v1.account_groups import check_group_changes, refuse_org_role_breach +from dfe_engine.api.v1.auth import persist_session_end from dfe_engine.auth import account_durability, breakglass from dfe_engine.auth.account_durability import AccountGitState from dfe_engine.auth.accounts import ( BCRYPT_MAX_PASSWORD_BYTES, Account, AccountExistsError, + delete_link_records, matches_digest, refuse_unhashable_password, ) +from dfe_engine.auth.admin_retirement import account_holds_system_admin from dfe_engine.auth.attributes import check_attribute_depth -from dfe_engine.auth.audit import audit_account_change, audit_login_denied +from dfe_engine.auth.audit import ( + audit_account_change, + audit_identity_unlinked, + audit_login_denied, +) from dfe_engine.auth.bootstrap import ( MIN_ADMIN_PASSWORD_LENGTH, admin_account_name, default_credentials_in_use, ) from dfe_engine.auth.groups import Group +from dfe_engine.auth.identity_links import link_candidates, linked_identity, without_identity from dfe_engine.auth.login_throttle import LoginThrottle from dfe_engine.auth.membership import forget_member, groups_held, groups_held_after from dfe_engine.auth.rbac_scopes import scopes_dict -from dfe_engine.names import InvalidNameError, StoreName +from dfe_engine.names import VALID_NAME, InvalidNameError, StoreName +from dfe_engine.orgs.role_groups import usable_org_admins router = APIRouter(prefix="/accounts", tags=["Accounts"]) @@ -198,12 +218,7 @@ async def _persist_password( class CreateAccountRequest(BaseModel): - """What a console sends to create an account. - - Only the credentials are required. The setup wizard creates the first user - from a form that collects no contact details, so a required field here is a - deployment that cannot get into its own console. - """ + """What a console sends to create an account: the credentials and a display name, with the contact fields optional.""" username: StoreName = Field(description="Unique account name") password: str = Field( @@ -217,9 +232,16 @@ class CreateAccountRequest(BaseModel): email: str = Field(default="", description="Contact email") groups: list[str] = Field(default_factory=list, description="Group memberships") phone: str = Field(default="", description="Contact phone") - name: str = Field(default="", description="Display name") + name: str = Field(min_length=1, description="Display name") org: str = Field(default="", description=_ORG_DESCRIPTION) + @field_validator("name") + @classmethod + def _not_blank(cls, value: str) -> str: + if not (value.strip()): + raise ValueError("must not be blank") + return value.strip() + @field_validator("password") @classmethod def _within_the_hash_limit(cls, value: str) -> str: @@ -324,6 +346,22 @@ class RotatePasswordResponse(BaseModel): secret_path: str = Field(description="Where in the secret store the new password went") +class LinkedIdentityResponse(BaseModel): + """An IdP sign-in linked to an account, which reaches it without a password.""" + + key: str = Field(description="The sign-in's key, which unlinking names") + provider: str = Field(description="The OIDC provider it signs in through") + provider_type: str = Field( + default="", + description="The provider's type (google, entra_id, okta or generic), empty once it " + "is no longer registered", + ) + subject: str = Field(description="The IdP subject (sub)") + email: str = Field(default="", description="The email its IdP last asserted") + linked_at: str = "" + last_login_at: str = "" + + class AccountResponse(BaseModel): """Account detail -- password_hash is NEVER included.""" @@ -341,13 +379,41 @@ class AccountResponse(BaseModel): phone: str = "" name: str = "" org: str = Field(default="", description=_ORG_DESCRIPTION) + org_display_name: str = Field( + default="", + description="The display name of the org the account is bound to, which for a root " + "account is your org, else that org's name when it has none. Empty while it is " + "bound to none.", + ) external: bool = Field( description="True when the account authenticates through an identity provider", ) + admin: bool = Field( + default=False, + description="True when a system-wide group gives the account the admin role, so it " + "has full access to every org. The account's own read reports false while " + "password_change_required is set.", + ) oidc_id: str = Field( default="", description="OIDC provider name last used to log this account in, empty if none", ) + oidc_type: str = Field( + default="", + description="The type of the provider oidc_id names, empty when it names no " + "registered provider", + ) + email_verified: bool | None = Field( + default=None, + description="Whether the email is vouched for, so a first IdP sign-in with it links " + "to this account: true when an admin set it or a trusted identity provider verified " + "it, false when the account owner set it or the provider did not vouch, null when it " + "was stored before this was recorded", + ) + identities: list[LinkedIdentityResponse] = Field( + default_factory=list, + description="IdP sign-ins linked to this account, each reaching it without a password", + ) password_change_required: bool = Field( default=False, description="True until the account replaces an issued password. The account's " @@ -357,6 +423,18 @@ class AccountResponse(BaseModel): updated_at: str +class AccountAvailabilityResponse(BaseModel): + """Why creating an account with these values would be refused, empty where it would not.""" + + email: str = Field( + default="", description="Why the email cannot be used, empty when it can or none was given" + ) + username: str = Field( + default="", + description="Why the username cannot be taken, empty when it can or none was given", + ) + + class AttributesRequest(BaseModel): """Full-replace body for an account's attribute blob (non-sensitive or sensitive).""" @@ -368,14 +446,36 @@ def _bounded_depth(cls, value: dict[str, Any]) -> dict[str, Any]: return check_attribute_depth(value) -def _account_response(request: Request, account: Account, groups: list[Group]) -> AccountResponse: - """Map a stored account to the public response (never includes password_hash). +@dataclass(frozen=True, slots=True) +class _Lookups: + """The registered orgs' display names and OIDC providers' types, each by name.""" + + org_display_names: Mapping[str, str] + provider_types: Mapping[str, str] + + +def _lookups(request: Request) -> _Lookups: + """The org display names and OIDC provider types as registered now.""" + registry = getattr(request.app.state, "oidc_provider_registry", None) + providers = registry.list() if registry is not None else [] + return _Lookups( + org_display_names={org.name: org.display_name for org in registered_orgs(request)}, + provider_types={name: provider.type for name, provider in providers}, + ) + + +def _account_response( + *, + account: Account, + groups: list[Group], + lookups: _Lookups, + request: Request, +) -> AccountResponse: + """Map a stored account to the public response, which never includes password_hash. - Args: - request: The request, for the provider bindings the groups resolve under. - account: The stored account. - groups: Every stored group, listed once per request. + *groups* and *lookups* are each read once per request. """ + bound = bound_org(account_org=account.org, request=request) return AccountResponse( username=account.username, enabled=account.enabled, @@ -387,8 +487,23 @@ def _account_response(request: Request, account: Account, groups: list[Group]) - phone=account.phone, name=account.name, org=account.org, + org_display_name=(lookups.org_display_names.get(bound)) or (bound), external=account.external, + admin=account_holds_system_admin( + account=account, bindings=provider_bindings(request), groups=groups + ), oidc_id=account.oidc_id, + oidc_type=lookups.provider_types.get(account.oidc_id, ""), + email_verified=account.email_verified, + identities=[ + LinkedIdentityResponse.model_validate( + { + **identity.model_dump(exclude={"groups"}), + "provider_type": lookups.provider_types.get(identity.provider, ""), + } + ) + for identity in account.identities + ], password_change_required=account.password_change_required, created_at=account.created_at, updated_at=account.updated_at, @@ -396,27 +511,104 @@ def _account_response(request: Request, account: Account, groups: list[Group]) - def _contact_updates( - body: UpdateAccountRequest | UpdateOwnAccountRequest, + body: UpdateAccountRequest | UpdateOwnAccountRequest, existing: Account, *, vouched: bool ) -> dict[str, object]: - """Partial contact-field updates. Omitted values are left unchanged.""" + """Partial contact-field updates. Omitted values are left unchanged, and a new email is vouched for only when an admin sets it.""" fields: dict[str, object] = {} if body.email is not None: fields["email"] = body.email + if (body.email is not None) and (body.email.strip() != existing.email.strip()): + fields["email_verified"] = vouched if body.phone is not None: fields["phone"] = body.phone if body.name is not None: + if not (body.name.strip()) and existing.name.strip(): + raise ProblemError(422, "An account's name cannot be cleared", code="name_required") fields["name"] = body.name return fields def _require_account(store: Any, username: str) -> Account: - """Return the account, or 404 when it is missing or soft-deleted.""" + """Return the account, or 404 when it is missing, soft-deleted or only links a sign-in to another.""" account = store.get(username) - if account is None or account.is_soft_deleted: + if (account is None) or (account.is_soft_deleted) or (account.is_link_record): raise ProblemError(404, f"Account '{username}' not found", code="not_found") return account +def _require_reachable(*, action: str, request: Request, user: Any, username: str) -> Account: + """The account *username*, 404 when it is missing or the caller may not take *action* on it, so another org's names stay hidden.""" + account = _require_account(request.app.state.account_store, username) + if not (reaches_org(action=action, org=account.org, request=request, user=user)): + raise ProblemError(404, f"Account '{username}' not found", code="not_found") + return account + + +def _usable_org_admin( + *, account: Account | None, groups: list[Any], held: Iterable[str] | None, request: Request +) -> bool: + """Whether *account* can sign in holding its own org's admins group, an org other than yours.""" + if (account is None) or (not (account.org)) or (account.session_denied() is not None): + return False + if account.org == bound_org(account_org="", request=request): + return False + if held is None: + held = groups_held(account=account, bindings=provider_bindings(request), groups=groups) + return f"{account.org}-admins" in held + + +def _refuse_last_org_admin( + *, + after: Account | None, + before: Account, + held_after: Iterable[str] | None, + request: Request, + user: Any, +) -> None: + """Refuse 409 ``last_org_admin`` when a write leaves *before*'s org with no usable admin, unless the caller acts across every org.""" + if reads_every_org(request, user, scopes_dict["account_write"]): + return + groups = request.app.state.group_store.list() + if not (_usable_org_admin(account=before, groups=groups, held=None, request=request)): + return + stays = (after is not None) and (after.org == before.org) + if (stays) and ( + _usable_org_admin(account=after, groups=groups, held=held_after, request=request) + ): + return + admins = usable_org_admins( + accounts=request.app.state.account_store.scan(), + bindings=provider_bindings(request), + groups=groups, + org=before.org, + ) + if any(admin != before.username for admin in admins): + return + raise ProblemError( + 409, + f"Cannot leave org {before.org!r} without an admin: {before.username!r} is its last", + code="last_org_admin", + ) + + +_EMAIL_TAKEN_MESSAGE = "Another account already uses this email" + + +def _email_taken(*, email: str, request: Request, username: str) -> bool: + """Whether an account other than *username* that a sign-in could link to by *email* holds it.""" + store = request.app.state.account_store + holders = link_candidates( + accounts=store.scan(), email=email, protected=store.protected.usernames + ) + return any(holder.username != username for holder in holders) + + +def _refuse_taken_email(*, email: str, request: Request, username: str) -> None: + """Refuse *email* when another account a sign-in could link to by it holds it.""" + if _email_taken(email=email, request=request, username=username): + raise ProblemError(409, _EMAIL_TAKEN_MESSAGE, code="email_taken") + + def _require_own_account(store: Any, user_id: str) -> Account: """The account the session is bound to, found the way authentication found it. @@ -501,11 +693,21 @@ async def _reset_stored_password( # -- Endpoints ------------------------------------------------ +async def require_new_account_reauth( + body: CreateAccountRequest, request: Request, user: CurrentUser, reauth: ReauthGrant = "" +) -> None: + """FastAPI dependency: the caller's re-auth grant for the account the body creates.""" + refuse_without_grant(reauth=reauth, request=request, target=body.username, user=user) + + @router.post( "", response_model=AccountResponse, status_code=201, - dependencies=[Depends(require_action(scopes_dict["account_write"]))], + dependencies=[ + Depends(require_own_org_action(scopes_dict["account_write"])), + Depends(require_new_account_reauth), + ], ) async def create_account( body: CreateAccountRequest, @@ -513,15 +715,24 @@ async def create_account( request: Request, settings: Settings, ): - """Create a new local user account (admin only).""" + """Create a new local user account: an admin of an org other than yours creates it in that org only.""" from dfe_engine.auth.accounts import AccountStore from dfe_engine.auth.membership import sync_group_members_for_account_groups_change + refuse_unreachable_org( + action=scopes_dict["account_write"], + noun="accounts", + org=body.org, + request=request, + user=user, + ) store: AccountStore = request.app.state.account_store group_store = request.app.state.group_store conflict = ProblemError(409, f"Account '{body.username}' already exists", code="conflict") if store.get(body.username) is not None: raise conflict + if body.email.strip(): + _refuse_taken_email(email=body.email, request=request, username=body.username) refuse_unknown_orgs(request, [body.org]) groups = group_store.list() created = Account(groups=body.groups, password_hash="", username=body.username) @@ -533,6 +744,12 @@ async def create_account( removed=(), ) check_group_changes(after=held_after, before=(), groups=groups, request=request, user=user) + refuse_org_role_breach( + account_org=body.org, + groups=[group for group in groups if group.name in set(held_after)], + request=request, + username=body.username, + ) # The create decides: another replica can take the name after the lookup above. # It hashes the password, so it runs off the event loop. try: @@ -543,6 +760,7 @@ async def create_account( body.password, groups=body.groups, email=body.email, + email_verified=True if body.email.strip() else None, phone=body.phone, name=body.name, org=body.org, @@ -568,19 +786,26 @@ async def create_account( audit_account_change( user.user_id, account.username, "created", {"groups": body.groups, "org": body.org} ) - return _account_response(request, account, group_store.list()) + return _account_response( + account=account, + groups=group_store.list(), + lookups=_lookups(request), + request=request, + ) AccountsList = Annotated[ ListQuery, - Depends(list_query(order_by=("username", "created_at", "updated_at"), tiebreak="username")), + Depends( + list_query(order_by=("username", "created_at", "updated_at", "org"), tiebreak="username") + ), ] @router.get( "", response_model=Page[AccountResponse], - dependencies=[Depends(require_platform_action(scopes_dict["account_read"]))], + dependencies=[Depends(require_own_org_action(scopes_dict["account_read"]))], ) async def list_accounts( user: CurrentUser, @@ -605,11 +830,18 @@ async def list_accounts( description="Include the local admin and break-glass recovery accounts.", ), ): - """List accounts (admin only), paginated. No password hashes returned.""" + """List the accounts the caller administers, paginated: every account across orgs, else its orgs' own. No password hashes returned.""" from dfe_engine.auth.accounts import AccountStore store: AccountStore = request.app.state.account_store - accounts = [account for account in store.list() if not account.is_soft_deleted] + action = scopes_dict["account_read"] + accounts = [ + account + for account in store.list() + if (not (account.is_soft_deleted)) + and (not (account.is_link_record)) + and (reaches_org(action=action, org=account.org, request=request, user=user)) + ] if not include_core: accounts = [ account for account in accounts if not store.protected.is_protected(account.username) @@ -624,7 +856,13 @@ async def list_accounts( account for account in accounts if org in (account.org, (account.org) or (home)) ] groups = request.app.state.group_store.list() - rows = [_account_response(request, a, groups).model_dump() for a in accounts] + lookups = _lookups(request) + rows = [ + _account_response( + account=account, groups=groups, lookups=lookups, request=request + ).model_dump() + for account in accounts + ] rows = apply_search(rows, search, ["username", "name", "email"]) rows = sort_by_order(rows, query.order_by) summaries = [AccountResponse.model_validate(row) for row in rows] @@ -641,6 +879,28 @@ async def list_accounts( ) +@router.get( + "/availability", + response_model=AccountAvailabilityResponse, + dependencies=[Depends(require_own_org_action(scopes_dict["account_write"]))], +) +async def get_account_availability( + request: Request, + email: str = Query("", description="An email a new account would hold"), + username: str = Query("", description="A name a new account would take"), +): + """Whether a new account could take *username* and hold *email*, judged as account create judges them.""" + store = request.app.state.account_store + response = AccountAvailabilityResponse() + if username and not (VALID_NAME.match(username)): + response.username = f"Invalid account name: {username!r}" + elif username and (taken := store.taken_name(username)) is not None: + response.username = f"Account '{taken}' already exists" + if email.strip() and _email_taken(email=email, request=request, username=username): + response.email = _EMAIL_TAKEN_MESSAGE + return response + + @router.get("/me", response_model=AccountResponse) async def get_current_user_account( user: CurrentUser, @@ -655,9 +915,15 @@ async def get_current_user_account( store: AccountStore = request.app.state.account_store account = _require_own_account(store, user.user_id) - response = _account_response(request, account, request.app.state.group_store.list()) + response = _account_response( + account=account, + groups=request.app.state.group_store.list(), + lookups=_lookups(request), + request=request, + ) if account.password_change_required: response.groups = [] + response.admin = False return response @@ -678,7 +944,9 @@ async def update_current_user_account( store: AccountStore = request.app.state.account_store existing = _require_own_account(store, user.user_id) - fields = _contact_updates(body) + fields = _contact_updates(body, existing, vouched=False) + if "email_verified" in fields: + _refuse_taken_email(email=body.email or "", request=request, username=existing.username) account = ( store.update(existing.username, allow_protected=False, **fields) if fields else existing ) @@ -691,13 +959,18 @@ async def update_current_user_account( actor=user.user_id, ) audit_account_change(user.user_id, account.username, "updated", {"fields": sorted(fields)}) - return _account_response(request, account, request.app.state.group_store.list()) + return _account_response( + account=account, + groups=request.app.state.group_store.list(), + lookups=_lookups(request), + request=request, + ) @router.get( "/{username}", response_model=AccountResponse, - dependencies=[Depends(require_platform_action(scopes_dict["account_read"]))], + dependencies=[Depends(require_own_org_action(scopes_dict["account_read"]))], ) async def get_account( username: str, @@ -706,19 +979,26 @@ async def get_account( ): """Get a single account by username (admin only). - Soft-deleted (anonymized) accounts answer 404 the same as a missing name. + Soft-deleted (anonymized) accounts, and those the caller does not administer, answer 404 the same as a missing name. """ - from dfe_engine.auth.accounts import AccountStore - - store: AccountStore = request.app.state.account_store - account = _require_account(store, username) - return _account_response(request, account, request.app.state.group_store.list()) + account = _require_reachable( + action=scopes_dict["account_read"], request=request, user=user, username=username + ) + return _account_response( + account=account, + groups=request.app.state.group_store.list(), + lookups=_lookups(request), + request=request, + ) @router.put( "/{username}", response_model=AccountResponse, - dependencies=[Depends(require_action(scopes_dict["account_write"]))], + dependencies=[ + Depends(require_own_org_action(scopes_dict["account_write"])), + Depends(require_account_reauth), + ], responses={ 403: { "description": "self_deactivate: an account cannot disable or block itself", @@ -750,8 +1030,14 @@ async def update_account( store: AccountStore = request.app.state.account_store group_store = request.app.state.group_store - existing = _require_account(store, username) - if username == user.user_id and (body.enabled is False or body.blocked is True): + action = scopes_dict["account_write"] + existing = _require_reachable(action=action, request=request, user=user, username=username) + if (body.org is not None) and (body.org != existing.org): + refuse_unreachable_org( + action=action, noun="accounts", org=body.org, request=request, user=user + ) + deactivates = (body.enabled is False) or (body.blocked is True) + if deactivates and is_own_account(request=request, user=user, username=username): raise ProblemError(403, "Cannot deactivate your own account", code="self_deactivate") bindings = provider_bindings(request) if admin_retirement.locks_out_last_admin( @@ -768,6 +1054,7 @@ async def update_account( "with the system admin role", code="last_admin", ) + held_after = None if body.groups is not None: groups = group_store.list() listed = {group.name for group in groups if username in group.members} @@ -798,7 +1085,37 @@ async def update_account( "it is the last usable account with the system admin role", code="last_admin", ) - update_fields: dict[str, object] = _contact_updates(body) + if (body.groups is not None) or (body.org is not None): + stored_groups = group_store.list() + held = ( + held_after + if held_after is not None + else groups_held(account=existing, bindings=bindings, groups=stored_groups) + ) + refuse_org_role_breach( + account_org=body.org if body.org is not None else existing.org, + groups=[group for group in stored_groups if group.name in set(held)], + request=request, + username=username, + ) + after = existing.model_copy( + update={ + field: value + for field, value in ( + ("blocked", body.blocked), + ("enabled", body.enabled), + ("groups", body.groups), + ("org", body.org), + ) + if value is not None + } + ) + _refuse_last_org_admin( + after=after, before=existing, held_after=held_after, request=request, user=user + ) + update_fields: dict[str, object] = _contact_updates(body, existing, vouched=True) + if "email_verified" in update_fields: + _refuse_taken_email(email=body.email or "", request=request, username=username) if body.groups is not None: update_fields["groups"] = body.groups if body.enabled is not None: @@ -837,7 +1154,12 @@ async def update_account( if name in update_fields: details[name] = update_fields[name] audit_account_change(user.user_id, account.username, "updated", details) - return _account_response(request, account, group_store.list()) + return _account_response( + account=account, + groups=group_store.list(), + lookups=_lookups(request), + request=request, + ) # Declared, since the path alone names the same action as the admin reset on /{username}. @@ -909,7 +1231,8 @@ async def reset_current_user_password( status_code=200, response_model=ResetPasswordResponse, dependencies=[ - Depends(require_action(scopes_dict["accounts_reset_password"])), + Depends(require_own_org_action(scopes_dict["accounts_reset_password"])), + Depends(require_account_reauth), ], ) async def reset_password( @@ -928,6 +1251,12 @@ async def reset_password( straight away (dev/solo) or is a pending review PR / CLI merge (production+team), or is a no-op file share. """ + _require_reachable( + action=scopes_dict["accounts_reset_password"], + request=request, + user=user, + username=username, + ) result = await _reset_stored_password( request, settings, @@ -945,6 +1274,7 @@ async def reset_password( response_model=RotatePasswordResponse, dependencies=[ Depends(require_action(scopes_dict["accounts_reset_password"])), + Depends(require_account_reauth), ], ) async def rotate_password( @@ -1052,7 +1382,10 @@ async def account_git_status( @router.delete( "/{username}", status_code=204, - dependencies=[Depends(require_action(scopes_dict["account_write"]))], + dependencies=[ + Depends(require_own_org_action(scopes_dict["account_write"])), + Depends(require_account_reauth), + ], responses={ 403: { "description": "self_delete: an account cannot delete itself", @@ -1079,9 +1412,12 @@ async def delete_account( store: AccountStore = request.app.state.account_store group_store = request.app.state.group_store - existing = _require_account(store, username) - if username == user.user_id: + existing = _require_reachable( + action=scopes_dict["account_write"], request=request, user=user, username=username + ) + if is_own_account(request=request, user=user, username=username): raise ProblemError(403, "Cannot delete your own account", code="self_delete") + _refuse_last_org_admin(after=None, before=existing, held_after=None, request=request, user=user) # Deleting an account takes it out of every group it holds, so it needs their roles. groups = group_store.list() bindings = provider_bindings(request) @@ -1099,10 +1435,76 @@ async def delete_account( ) # The store refuses the local admin and breakglass, the accounts the deploy repo carries. store.delete(username) + delete_link_records(store, existing) forget_member(group_store, username) audit_account_change(user.user_id, username, "deleted") +@router.delete( + "/{username}/identities/{key}", + status_code=204, + dependencies=[ + Depends(require_own_org_action(scopes_dict["account_write"])), + Depends(require_account_reauth), + ], + responses={ + 404: {"description": "not_found: no such account, or it lists no sign-in under key"}, + 409: { + "description": "last_admin: the sign-in gives the last usable account its " + "system admin role" + }, + }, +) +async def unlink_identity(username: str, key: str, user: CurrentUser, request: Request): + """Unlink an IdP sign-in from an account (admin only). + + The sign-in's record becomes an account of its own, which its next sign-in judges on its own groups. Every session of the account ends, so one opened through the sign-in does not outlive the link. Taking away the groups the sign-in linked needs the roles they carry, as removing a group does. + """ + from dfe_engine.auth import admin_retirement + + store = request.app.state.account_store + group_store = request.app.state.group_store + existing = _require_reachable( + action=scopes_dict["account_write"], request=request, user=user, username=username + ) + if linked_identity(account=existing, key=key) is None: + raise ProblemError( + 404, f"Account {username!r} has no linked sign-in {key!r}", code="not_found" + ) + remaining = without_identity(identities=existing.identities, key=key) + groups = group_store.list() + bindings = provider_bindings(request) + held_after = groups_held( + account=existing.model_copy(update={"identities": remaining}), + bindings=bindings, + groups=groups, + ) + check_group_changes( + after=held_after, + before=groups_held(account=existing, bindings=bindings, groups=groups), + groups=groups, + request=request, + user=user, + ) + if admin_retirement.locks_out_last_admin_by_group_loss( + existing, store, group_store, bindings=bindings, held_after=held_after + ): + raise ProblemError( + 409, + f"Cannot unlink {key!r} from {username!r}: it gives the last usable account " + "its system admin role", + code="last_admin", + ) + # The record goes first, so a failure after it leaves the sign-in unlinked rather than re-linked at its next login. + record = store.get(key) + if (record is not None) and (record.linked_to == username): + store.update(key, linked_to="") + store.update(username, identities=remaining) + account = store.end_sessions(username) + await persist_session_end(request, account, actor=user.user_id) + audit_identity_unlinked(account=username, admin_id=user.user_id, key=key) + + # -- Attributes ----------------------------------------------- # # Non-sensitive attributes ride inline on the Account model, so they are read @@ -1130,7 +1532,10 @@ async def get_account_attributes( @router.put( "/{username}/attributes", - dependencies=[Depends(require_action(scopes_dict["account_attributes_write"]))], + dependencies=[ + Depends(require_action(scopes_dict["account_attributes_write"])), + Depends(require_account_reauth), + ], ) async def put_account_attributes( username: str, @@ -1174,7 +1579,10 @@ async def get_account_sensitive_attributes( @router.put( "/{username}/sensitive-attributes", - dependencies=[Depends(require_action(scopes_dict["account_attributes_write_sensitive"]))], + dependencies=[ + Depends(require_action(scopes_dict["account_attributes_write_sensitive"])), + Depends(require_account_reauth), + ], ) async def put_account_sensitive_attributes( username: str, diff --git a/src/dfe_engine/api/v1/api_keys.py b/src/dfe_engine/api/v1/api_keys.py index 33da27336..61ab2b115 100644 --- a/src/dfe_engine/api/v1/api_keys.py +++ b/src/dfe_engine/api/v1/api_keys.py @@ -32,16 +32,27 @@ from scalo.api import ListQuery, Page, ProblemError, list_query, paginate, sort_by_order from dfe_engine.api.conventions import apply_search -from dfe_engine.api.deps import CurrentUser, refuse_unknown_orgs, require_platform_action +from dfe_engine.api.deps import ( + CurrentUser, + ReauthGrant, + bound_org, + refuse_unknown_orgs, + refuse_without_grant, + require_api_key_reauth, + require_platform_action, +) from dfe_engine.api.v1.account_groups import check_role_assignment, scope_of from dfe_engine.auth.audit import audit_api_key_change from dfe_engine.auth.membership import groups_named from dfe_engine.auth.rbac_scopes import scopes_dict +from dfe_engine.auth.reauth import grant_target from dfe_engine.names import StoreName +from dfe_engine.orgs.role_groups import org_role_breach if TYPE_CHECKING: from dfe_engine.auth.api_keys import APIKey + router = APIRouter(prefix="/api-keys", tags=["API Keys"]) @@ -112,11 +123,22 @@ def _response_fields(key_meta: APIKey) -> dict: # -- Endpoints ------------------------------------------------ +async def require_new_api_key_reauth( + body: CreateAPIKeyRequest, request: Request, user: CurrentUser, reauth: ReauthGrant = "" +) -> None: + """FastAPI dependency: the caller's re-auth grant for the API key the body creates.""" + target = grant_target(kind="api_key", name=body.name) + refuse_without_grant(reauth=reauth, request=request, target=target, user=user) + + @router.post( "", response_model=APIKeyCreatedResponse, status_code=201, - dependencies=[Depends(require_platform_action(scopes_dict["api_key_write"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["api_key_write"])), + Depends(require_new_api_key_reauth), + ], ) async def create_api_key( body: CreateAPIKeyRequest, @@ -125,7 +147,7 @@ async def create_api_key( ): """Create a new API key. Returns the full key exactly once. - 422 ``unknown_org`` when ``org`` names no registered org. + 422 ``unknown_org`` when ``org`` names no registered org, ``org_role_only`` when a key bound to an org other than yours names a group outside that org's admin and viewer roles. """ from dfe_engine.auth.api_keys import APIKeyStore @@ -133,9 +155,20 @@ async def create_api_key( if store.get(body.name) is not None: raise ProblemError(409, f"API key '{body.name}' already exists", code="conflict") # The key's session takes every role its groups carry, so minting it hands them out. - for group in groups_named(body.groups, request.app.state.group_store.list()): + named = groups_named(body.groups, request.app.state.group_store.list()) + for group in named: check_role_assignment(request, user, group.roles, scope_of(group)) refuse_unknown_orgs(request, [body.org]) + breach = org_role_breach( + account_org=body.org, groups=named, home_org=bound_org(account_org="", request=request) + ) + if breach is not None: + raise ProblemError( + 422, + f"API key {body.name!r} is bound to org {body.org!r}, and an org key holds only " + f"its own org's admin or viewer group, so group {breach!r} is refused", + code="org_role_only", + ) expires_at = body.expires_at ttl_days = request.app.state.settings.auth.api_key_default_ttl_days if expires_at is None and ttl_days > 0: @@ -191,7 +224,10 @@ async def list_api_keys( @router.delete( "/{short_token}", status_code=204, - dependencies=[Depends(require_platform_action(scopes_dict["api_key_delete"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["api_key_delete"])), + Depends(require_api_key_reauth), + ], ) async def revoke_api_key( short_token: str, diff --git a/src/dfe_engine/api/v1/auth.py b/src/dfe_engine/api/v1/auth.py index b02d32016..deac94235 100644 --- a/src/dfe_engine/api/v1/auth.py +++ b/src/dfe_engine/api/v1/auth.py @@ -20,6 +20,7 @@ from dfe_engine.api.deps import ( CurrentUser, + ReauthGrant, Settings, _get_client_ip, bound_account, @@ -27,12 +28,13 @@ check_action, create_access_token, get_role_config, + jwt_authority_for, refuse_denied_account, + refuse_without_grant, resolve_live_grants_for_user, - resolve_live_groups_for_user, session_accounts, + throttled, ) -from dfe_engine.api.metrics import ApiMetrics from dfe_engine.api.password_change import PASSWORD_CHANGE_CLAIM from dfe_engine.api.v1.hyperdx import hyperdx_identity from dfe_engine.api.v1.oidc_login import TOKEN_COOKIE, token_cookie_secure @@ -50,6 +52,13 @@ from dfe_engine.auth.login_throttle import LoginThrottle from dfe_engine.auth.models import AuthenticationError, ScopedGrant, held_grants from dfe_engine.auth.rbac_scopes import scopes_dict +from dfe_engine.auth.reauth import ( + REAUTH_HEADER, + REAUTH_LIFETIME, + ReauthKind, + grant_target, + mint_reauth_grant, +) from dfe_engine.auth.roles import RoleConfig from dfe_engine.auth.sessions import ( SESSION_CLAIM, @@ -60,11 +69,31 @@ token_lifetime, ) from dfe_engine.auth.setup_status import SetupStatus, evaluate_initial_setup +from dfe_engine.names import StoreName from dfe_engine.settings import DFESettings router = APIRouter(prefix="/auth", tags=["Auth"]) +class ReauthRequest(BaseModel): + """Your own password, and the account you are about to edit.""" + + kind: ReauthKind = Field("account", description="What the target names") + password: str = Field(description="Your own password") + target: StoreName = Field( + description="The account, group, role, sign-in provider or API key you are about to change" + ) + + +class ReauthResponse(BaseModel): + """A grant for editing one account.""" + + grant: str = Field( + description=f"Send it as the {REAUTH_HEADER} header on every edit of that account" + ) + expires_in: int = Field(description="Seconds the grant stays valid") + + def request_time() -> int: """The request's one reading of the clock, in whole epoch seconds.""" return int(time.time()) @@ -79,7 +108,7 @@ def request_time() -> int: class LoginRequest(BaseModel): """Body for a local login.""" - username: str = Field(description="Account name (admin, operator, viewer)") + username: str = Field(description="Account name, or the email of a local account") password: str = Field(description="Plaintext password") @@ -221,19 +250,6 @@ async def persist_session_end(request: Request, account: Account, *, actor: str) await run_blocking(account_durability.publish_session_end, gc, account, actor=actor) -def throttled(request: Request, wait: int) -> ProblemError: - """The 429 a sign-in or password check answers while its caller must wait, counted.""" - metrics = getattr(request.app.state, "api_metrics", None) or ApiMetrics() - route = str(getattr(request.scope.get("route"), "path", "")) or "unknown" - metrics.sign_in_throttled(route) - return ProblemError( - 429, - f"Too many failed attempts; try again in {wait} seconds", - code="too_many_attempts", - headers={"Retry-After": str(wait)}, - ) - - def _mint( data: dict, account: Account | None, @@ -294,15 +310,17 @@ async def login(body: LoginRequest, request: Request, settings: Settings): provider: LocalAuthProvider = request.app.state.auth_provider throttle: LoginThrottle = request.app.state.login_throttle client_ip = _get_client_ip(request) + # An email resolves first, so it shares the account name's throttle. + username = await run_blocking(provider.account_name, body.username) - wait = throttle.retry_after(body.username, client_ip) + wait = throttle.retry_after(username, client_ip) if wait: - audit_login_denied(body.username, "jwt", client_ip, "throttled") + audit_login_denied(username, "jwt", client_ip, "throttled") raise throttled(request, wait) # The break-glass account bypasses the IdP, so every attempt is audited. breakglass_off = False - if body.username == breakglass.USERNAME: + if username == breakglass.USERNAME: gc = getattr(request.app.state, "gitcrud", None) breakglass_off = not breakglass.is_enabled(gc) audit_breakglass_login(client_ip, not breakglass_off, "disabled" if breakglass_off else "") @@ -310,17 +328,17 @@ async def login(body: LoginRequest, request: Request, settings: Settings): try: auth_ctx = await run_blocking( provider.authenticate, - body.username, + username, body.password, request_id=request.headers.get("X-Request-ID"), client_ip=client_ip, user_agent=request.headers.get("User-Agent"), ) except AuthenticationError as exc: - throttle.failed(body.username, client_ip) + throttle.failed(username, client_ip) # Audited here rather than in the app-wide 401 handler, which also answers # expired tokens on ordinary requests - those are already audited in deps.py. - audit_login_denied(body.username, "jwt", client_ip, str(exc)) + audit_login_denied(username, "jwt", client_ip, str(exc)) raise if breakglass_off: # Only after the password passed, so a guesser gets the generic 401 and a failed @@ -334,22 +352,24 @@ async def login(body: LoginRequest, request: Request, settings: Settings): f"{where.directory}/{breakglass.NAME}{where.suffix} in the deploy repo.", code="breakglass_disabled", ) - throttle.succeeded(body.username) + throttle.succeeded(username) + + # The bound account's groups decide, as on every request: the provider sees members only, never linked sign-ins or the org-role rule. + live = resolve_live_grants_for_user(request, auth_ctx.user_id) + roles = live.roles # The password is exchanged for a token here, so this is the login the # audit trail counts - not the per-request token check in get_current_user. - audit_login_success(auth_ctx.user_id, "jwt", client_ip, auth_ctx.roles) + audit_login_success(auth_ctx.user_id, "jwt", client_ip, roles) change_required = _password_change_required(request, auth_ctx.user_id) - # The provider resolves role names only. The claim needs the scope each is bound at. - live = resolve_live_grants_for_user(request, auth_ctx.user_id) data = _token_data( auth_ctx.user_id, bound_org(account_org=auth_ctx.org_id, request=request), - auth_ctx.roles, + roles, live.grants, - auth_ctx.groups, - auth_ctx.org_ids, + live.groups, + live.org_ids, change_required=change_required, role_config=get_role_config(request), ) @@ -434,7 +454,7 @@ async def refresh_token(user: CurrentUser, request: Request, settings: Settings, user.org_id, live.roles, live.grants, - resolve_live_groups_for_user(request, user.user_id), + live.groups, live.org_ids, change_required=change_required, role_config=get_role_config(request), @@ -530,7 +550,21 @@ def get_setup_status(request: Request) -> SetupStatus: return evaluate_initial_setup(request) -@router.post("/setup/retire-admin", response_model=SetupStatus, dependencies=[WRITE_TURN]) +async def require_retire_reauth( + request: Request, settings: Settings, user: CurrentUser, reauth: ReauthGrant = "" +) -> None: + """FastAPI dependency: another caller's re-auth grant for the bootstrap admin it retires. The admin retiring itself needs none.""" + admin_name = admin_account_name(settings.auth.local.admin_name) + if user.user_id != admin_name: + check_action(request, user, scopes_dict["account_write"]) + refuse_without_grant(reauth=reauth, request=request, target=admin_name, user=user) + + +@router.post( + "/setup/retire-admin", + response_model=SetupStatus, + dependencies=[WRITE_TURN, Depends(require_retire_reauth)], +) def retire_bootstrap_admin( user: CurrentUser, request: Request, @@ -589,3 +623,37 @@ def retire_bootstrap_admin( ) audit_account_change(user.user_id, admin_name, "retired the bootstrap admin") return evaluate_initial_setup(request) + + +@router.post("/reauth", response_model=ReauthResponse) +async def reauth(body: ReauthRequest, user: CurrentUser, request: Request) -> ReauthResponse: + """Re-enter your password to earn a grant for editing one account, which every edit of it needs. + + 403 ``invalid_password`` on a wrong password, counted against the sign-in throttle. 409 ``reauth_via_idp`` for a caller with no local password, who re-signs in at its identity provider instead. + """ + client_ip = _get_client_ip(request) + account = bound_account(request, user.user_id) + if (account is None) or (account.external) or (not (account.password_hash)): + raise ProblemError( + 409, + "You sign in through an identity provider: confirm it is you there instead", + code="reauth_via_idp", + ) + throttle = request.app.state.login_throttle + wait = throttle.retry_after(account.username, client_ip) + if wait: + audit_login_denied(account.username, "reauth", client_ip, "throttled") + raise throttled(request, wait) + store = request.app.state.account_store + verified = await run_blocking(store.verify_account_password, account, body.password) + if not (verified): + throttle.failed(account.username, client_ip) + audit_login_denied(account.username, "reauth", client_ip, "invalid_password") + raise ProblemError(403, "Invalid password", code="invalid_password") + throttle.succeeded(account.username) + grant = mint_reauth_grant( + authority=jwt_authority_for(request.app.state.settings), + caller=user.user_id, + target=grant_target(kind=body.kind, name=body.target), + ) + return ReauthResponse(expires_in=int(REAUTH_LIFETIME.total_seconds()), grant=grant) diff --git a/src/dfe_engine/api/v1/oidc_login.py b/src/dfe_engine/api/v1/oidc_login.py index db37b365a..9c30e590b 100644 --- a/src/dfe_engine/api/v1/oidc_login.py +++ b/src/dfe_engine/api/v1/oidc_login.py @@ -12,6 +12,7 @@ GET /api/v1/auth/oidc/{provider}/login?redirect=false -> JSON {authorization_url} GET /api/v1/auth/oidc/{provider}/login?return_to= -> callback hands the browser back there GET /api/v1/auth/oidc/{provider}/callback -> exchange code, RE-MINT engine token +POST /api/v1/auth/oidc/link -> link a held sign-in to its local account A browser client (the console) passes ``return_to`` on login. The callback then 303s to it with the engine token in the URL fragment, which never leaves the @@ -33,37 +34,61 @@ import time from datetime import timedelta from typing import TYPE_CHECKING, Literal, NoReturn -from urllib.parse import urlencode, urlsplit +from urllib.parse import parse_qs, urlencode, urlsplit from fastapi import APIRouter, Query, Request from fastapi.responses import JSONResponse, RedirectResponse -from pydantic import BaseModel, Field +from jwt.exceptions import InvalidTokenError +from pydantic import BaseModel, Field, ValidationError from scalo.api import ProblemError from scalo.concurrency import run_blocking from scalo.logger import logger from dfe_engine.api.deps import ( + CurrentUser, Settings, _get_client_ip, + bound_account, get_role_config, jwt_authority_for, require_local_account_enabled, resolve_live_grants_for_user, + throttled, ) from dfe_engine.auth import hyperdx_role from dfe_engine.auth.audit import audit_jit_failed, audit_login_denied, audit_login_success +from dfe_engine.auth.identity_links import ( + LinkTicket, + asserted_groups, + linked_through, + mint_link_ticket, + read_link_ticket, + trusted_email, +) from dfe_engine.auth.jit import ( JitAccountUnavailableError, + JitEmailHeldError, + JitEmailUntrustedError, JitIdentityCollisionError, + JitLinkRequiredError, JitNoRoleError, JitSubjectUnusableError, ) +from dfe_engine.auth.reauth import ( + REAUTH_KINDS, + REAUTH_LIFETIME, + ReauthKind, + grant_target, + mint_reauth_grant, +) from dfe_engine.auth.sessions import session_claims, token_lifetime from dfe_engine.http_errors import describe_http_error +from dfe_engine.names import StoreName from dfe_engine.settings import DFESettings, is_dev_posture if TYPE_CHECKING: - from dfe_engine.auth.oidc.rp import OidcRelyingParty + from dfe_engine.auth.accounts import Account + from dfe_engine.auth.oidc.rp import NormalizedIdentity, OidcRelyingParty router = APIRouter(prefix="/auth/oidc", tags=["OIDC Login"]) @@ -83,6 +108,15 @@ def token_cookie_secure(settings: DFESettings) -> bool: # Session key holding the validated return_to between login and callback. _RETURN_TO_SESSION_KEY = "oidc_return_to" +# Session key holding a re-auth sign-in between its start and the callback. +_REAUTH_SESSION_KEY = "oidc_reauth" + +# How long a re-auth sign-in may spend at the IdP. +_REAUTH_SIGN_IN_SECONDS = 600 + +# How far the IdP's clock may run behind the engine's when ``auth_time`` is judged. +_AUTH_TIME_SKEW_SECONDS = 30 + def _origin(url: str) -> str: parts = urlsplit(url) @@ -141,6 +175,27 @@ class OidcCallbackResponse(BaseModel): groups: list[str] = Field(default_factory=list, description="Resolved group identifiers") +class OidcReauthRequest(BaseModel): + """The account or group you are about to change, and where the sign-in hands its grant back.""" + + kind: ReauthKind = Field("account", description="What the target names") + return_to: str = Field( + description="Where the callback sends the browser, with the grant in the URL fragment " + "(#reauth_grant=...&expires_in=...) or the refusal's code (#error=&provider=...). " + "A relative path, or an absolute URL on this API's origin or a CORS-allowed origin." + ) + target: StoreName = Field( + description="The account, group, role, sign-in provider or API key you are about to change" + ) + + +class OidcLinkRequest(BaseModel): + """Body for linking a held IdP sign-in to its local account with that account's password.""" + + password: str = Field(description="The local account's password") + ticket: str = Field(description="The link_ticket a link_required callback answered with") + + def _registered_state(request: Request, provider: str) -> bool | None: """Whether the provider registry holds *provider* enabled, or None when there is no registry. @@ -289,8 +344,15 @@ def _hand_back_refusal(return_to: str, provider: str, exc: ProblemError) -> Redi 303: { "description": "Login started with return_to: redirect there with the engine " "token in the URL fragment, or with the refusal's code " - "(#error=&provider=...) when the login is refused." - } + "(#error=&provider=...) when the login is refused. A sign-in that " + "links to a local account comes back with " + "#error=link_required&link_ticket=...&account=...&provider=... instead." + }, + 409: { + "description": "link_required: the sign-in's trusted email matches a local " + "account. The body's link_ticket and that account's password go to POST " + "/auth/oidc/link, and account names it." + }, }, ) async def oidc_callback( @@ -303,9 +365,27 @@ async def oidc_callback( refusal answers JSON with its status, as any API error does. """ # Spent before the provider check, so a 404 leaves no return_to behind either. - return_to = request.session.pop(_RETURN_TO_SESSION_KEY, None) + pending = request.session.get(_REAUTH_SESSION_KEY) + # Only the re-auth's own authorize request answers it: a login open in another tab stays a login. + reauthing = (pending is not None) and ( + pending.get("state") == request.query_params.get("state") + ) + if reauthing: + request.session.pop(_REAUTH_SESSION_KEY, None) + return_to = pending.get("return_to") + else: + return_to = request.session.pop(_RETURN_TO_SESSION_KEY, None) rp = await _rp_or_404(request, provider) try: + if reauthing: + return await _complete_reauth( + pending=pending, + provider=provider, + request=request, + return_to=return_to, + rp=rp, + settings=settings, + ) return await _complete_login(provider, request, settings, rp, return_to) except ProblemError as exc: if not return_to: @@ -350,12 +430,29 @@ async def _complete_login( email=identity.email, name=identity.name, keep_stored_groups=identity.groups_unresolved, + email_verified=_trusted_email( + identity=identity, provider=provider, request=request + ), + ) + except JitLinkRequiredError as exc: + return _link_required( + exc=exc, + identity=identity, + provider=provider, + request=request, + return_to=return_to, + settings=settings, ) except (JitIdentityCollisionError, JitSubjectUnusableError) as exc: # Ordered before the catch-all: a refused identity is a 401, not a 503. audit_login_denied(identity.subject, "oidc", _get_client_ip(request), exc.reason) raise ProblemError(401, str(exc), code="unauthorized") from exc - except (JitAccountUnavailableError, JitNoRoleError) as exc: + except ( + JitAccountUnavailableError, + JitEmailHeldError, + JitEmailUntrustedError, + JitNoRoleError, + ) as exc: audit_login_denied(identity.subject, "oidc", _get_client_ip(request), exc.reason) raise ProblemError(401, str(exc), code=exc.reason) from exc except Exception as exc: @@ -368,12 +465,144 @@ async def _complete_login( 503, "The login could not be recorded. Try again.", code="service_unavailable" ) from exc - account = require_local_account_enabled(request, identity.subject) - # Groups the directory never answered for are the account's stored ones, not none. - groups = account.groups if identity.groups_unresolved and account else identity.groups + return _signed_in( + email=identity.email, + groups=identity.groups, + groups_unresolved=identity.groups_unresolved, + provider=provider, + request=request, + return_to=return_to, + settings=settings, + subject=identity.subject, + ) + + +async def _complete_reauth( + *, + pending: dict, + provider: str, + request: Request, + return_to: str | None, + rp: OidcRelyingParty, + settings: DFESettings, +) -> JSONResponse | RedirectResponse: + """Hand back a grant for a re-auth sign-in that is the caller's own and fresh. A refusal raises ProblemError.""" + caller = str(pending.get("caller") or "") + started = int(pending.get("started") or 0) + client_ip = _get_client_ip(request) + if int(time.time()) - started > _REAUTH_SIGN_IN_SECONDS: + audit_login_denied(caller, "reauth", client_ip, "reauth_expired") + raise ProblemError(403, "The sign-in took too long. Try again.", code="reauth_expired") + try: + identity = await rp.handle_callback(provider, request) + except Exception as exc: + failure = describe_http_error(exc) + logger.warning("OIDC re-auth callback failed", provider=provider, **failure) + reason = str(failure.get("code") or failure["error_type"]) + audit_login_denied(caller, "reauth", client_ip, reason) + raise ProblemError( + 403, "The sign-in failed; the engine log has the reason", code="reauth_failed" + ) from exc + account = require_local_account_enabled(request, caller) + if (account is None) or ((provider, identity.subject) not in _sign_ins(account=account)): + audit_login_denied(caller, "reauth", client_ip, "reauth_other_person") + raise ProblemError(403, "That sign-in is not yours", code="reauth_other_person") + if (identity.auth_time is None) or (identity.auth_time < started - _AUTH_TIME_SKEW_SECONDS): + audit_login_denied(caller, "reauth", client_ip, "reauth_not_fresh") + raise ProblemError( + 403, + "Your identity provider did not ask for your credentials again", + code="reauth_not_fresh", + ) + kind = next((known for known in REAUTH_KINDS if known == pending.get("kind")), None) + if kind is None: + raise ProblemError(403, "The sign-in failed. Try again.", code="reauth_failed") + target = grant_target(kind=kind, name=str(pending.get("target") or "")) + grant = mint_reauth_grant(authority=jwt_authority_for(settings), caller=caller, target=target) + expires_in = int(REAUTH_LIFETIME.total_seconds()) + if not (return_to): + return JSONResponse({"expires_in": expires_in, "grant": grant}) + fields = {"expires_in": str(expires_in), "reauth_grant": grant} + return RedirectResponse(_hand_back_url(return_to, fields), status_code=303) + + +def _link_required( + *, + exc: JitLinkRequiredError, + identity: NormalizedIdentity, + provider: str, + request: Request, + return_to: str | None, + settings: DFESettings, +) -> RedirectResponse: + """Hold a sign-in that links to a local account until that account's password, handing back its ticket. + + A browser login goes back to ``return_to`` with the ticket in the URL fragment beside ``error=link_required``, so a console that cannot link shows a refusal. Otherwise the 409 carries it. + """ + link = LinkTicket( + account=exc.account, + email=identity.email, + groups=identity.groups, + groups_unresolved=identity.groups_unresolved, + name=identity.name, + provider=provider, + subject=identity.subject, + ) + ticket = mint_link_ticket(authority=jwt_authority_for(settings), ticket=link) + audit_login_denied(identity.subject, "oidc", _get_client_ip(request), exc.reason) + if not (return_to): + raise ProblemError(409, str(exc), code=exc.reason, account=exc.account, link_ticket=ticket) + fields = { + "account": exc.account, + "error": exc.reason, + "link_ticket": ticket, + "provider": provider, + } + return RedirectResponse(_hand_back_url(return_to, fields), status_code=303) + + +def _sign_ins(*, account: Account) -> set[tuple[str, str]]: + """The ``(provider, subject)`` sign-ins that reach *account*: its own and each one linked to it.""" + held = {(identity.provider, identity.subject) for identity in account.identities} + if (account.oidc_id) and (account.subject): + held.add((account.oidc_id, account.subject)) + return held + + +def _trusted_email(*, identity: NormalizedIdentity, provider: str, request: Request) -> bool: + """Whether the IdP vouched for the sign-in's email and the provider is trusted for its domain.""" + registry = getattr(request.app.state, "oidc_provider_registry", None) + config = registry.get(provider) if registry is not None else None + domains = config.trusted_email_domains if config is not None else [] + return trusted_email( + email=identity.email, email_verified=identity.email_verified, trusted_domains=domains + ) + + +def _signed_in( + *, + email: str, + groups: list[str], + groups_unresolved: bool, + provider: str, + request: Request, + return_to: str | None, + settings: DFESettings, + subject: str, +) -> JSONResponse | RedirectResponse: + """Mint the engine token for the admitted IdP *subject* and answer with it. + + A sign-in linked to an account is that account's session, so the token's ``sub`` is the account's, which binds it back to the account on every request. + """ + account = require_local_account_enabled(request, subject) + linked = account is not None and linked_through(account=account, subject=subject) + session_subject = account.session_subject if linked else subject + # Groups the directory never answered for are the stored assertion, not none. + if groups_unresolved and account is not None: + groups = asserted_groups(account=account, subject=subject) # From the group files rather than the IdP token, for the claim and the audit. - live = resolve_live_grants_for_user(request, identity.subject) + live = resolve_live_grants_for_user(request, subject) roles = live.roles # RE-MINT: the engine's own ES384 identity token is the ONLY token downstream @@ -387,8 +616,8 @@ async def _complete_login( ) token = jwt_authority_for(settings).sign( { - "sub": identity.subject, - "email": identity.email, + "sub": session_subject, + "email": email, "groups": groups, # dfe-hyperdx gates changing what a team sees on this one value. hyperdx_role.CLAIM: hyperdx_role.role_claim(live.grants, get_role_config(request)), @@ -401,18 +630,18 @@ async def _complete_login( logger.info( "OIDC login re-minted engine token", provider=provider, - subject=identity.subject, + subject=subject, group_count=len(groups), ) # The IdP code is exchanged for an engine token here, so this is the login # the audit trail counts - not the per-request token check in get_current_user. - audit_login_success(identity.subject, "oidc", _get_client_ip(request), roles) + audit_login_success(session_subject, "oidc", _get_client_ip(request), roles) payload = OidcCallbackResponse( access_token=token, - subject=identity.subject, - email=identity.email, + subject=subject, + email=email, groups=groups, ) response: JSONResponse | RedirectResponse @@ -430,3 +659,136 @@ async def _complete_login( max_age=lifetime, ) return response + + +@router.post( + "/link", + response_model=OidcCallbackResponse, + responses={ + 401: { + "description": "link_ticket_invalid (expired or not this engine's), a wrong " + "password, link_stale (the account or the sign-in changed since the ticket), " + "or the account is disabled, blocked or would hold no role" + }, + 404: {"description": "The ticket's provider is no longer registered and enabled"}, + 429: { + "description": "Too many failed attempts for this account or from this " + "address; Retry-After gives the seconds to wait" + }, + }, +) +async def oidc_link( + body: OidcLinkRequest, request: Request, settings: Settings +) -> JSONResponse | RedirectResponse: + """Link the sign-in a ``link_required`` callback held to its local account, on that account's password, and sign it in. + + Wrong passwords count against the account's sign-in throttle (``auth.login_throttle``), as a password login's do. The answer is the callback's, and from then on the sign-in reaches the account without a password. + """ + client_ip = _get_client_ip(request) + try: + ticket = read_link_ticket(authority=jwt_authority_for(settings), token=body.ticket) + except (InvalidTokenError, ValidationError) as exc: + audit_login_denied("unknown", "oidc", client_ip, "link_ticket_invalid") + raise ProblemError( + 401, + "The link has expired or is not valid. Sign in through your identity provider again.", + code="link_ticket_invalid", + ) from exc + if not (_registered_state(request, ticket.provider)): + raise _not_found(ticket.provider) + domains = request.app.state.oidc_provider_registry.get(ticket.provider).trusted_email_domains + if not (trusted_email(email=ticket.email, email_verified=True, trusted_domains=domains)): + # Trust withdrawn since the ticket was issued. + audit_login_denied(ticket.subject, "oidc", client_ip, "link_stale") + raise ProblemError(401, "The link is no longer allowed. Sign in again.", code="link_stale") + + throttle = request.app.state.login_throttle + wait = throttle.retry_after(ticket.account, client_ip) + if wait: + audit_login_denied(ticket.account, "oidc", client_ip, "throttled") + raise throttled(request, wait) + store = request.app.state.account_store + account = store.get(ticket.account) + verified = await run_blocking(store.verify_account_password, account, body.password) + if (not (verified)) or (account is None) or (account.external): + throttle.failed(ticket.account, client_ip) + audit_login_denied(ticket.account, "oidc", client_ip, "invalid_password") + raise ProblemError(401, "Invalid password", code="unauthorized") + throttle.succeeded(ticket.account) + + jit = getattr(request.app.state, "jit_provisioner", None) + if jit is None: + raise _not_found(ticket.provider) + try: + jit.complete_link(ticket=ticket) + except (JitIdentityCollisionError, JitSubjectUnusableError) as exc: + audit_login_denied(ticket.subject, "oidc", client_ip, exc.reason) + code = exc.reason if exc.reason == "link_stale" else "unauthorized" + raise ProblemError(401, str(exc), code=code) from exc + except (JitAccountUnavailableError, JitNoRoleError) as exc: + audit_login_denied(ticket.subject, "oidc", client_ip, exc.reason) + raise ProblemError(401, str(exc), code=exc.reason) from exc + except Exception as exc: + logger.error("Account link failed", user_id=ticket.subject, **describe_http_error(exc)) + audit_jit_failed(ticket.subject, exc) + raise ProblemError( + 503, "The link could not be recorded. Try again.", code="service_unavailable" + ) from exc + + return _signed_in( + email=ticket.email, + groups=ticket.groups, + groups_unresolved=ticket.groups_unresolved, + provider=ticket.provider, + request=request, + return_to=None, + settings=settings, + subject=ticket.subject, + ) + + +@router.post( + "/reauth", + response_model=OidcLoginResponse, + response_model_exclude_none=True, + responses={ + 409: { + "description": "reauth_via_password: the caller has no identity-provider sign-in, " + "so it confirms with its password at POST /auth/reauth" + } + }, +) +async def oidc_reauth( + body: OidcReauthRequest, request: Request, settings: Settings, user: CurrentUser +) -> OidcLoginResponse: + """Start a fresh sign-in at your own identity provider, which earns a grant for changing one account or group. + + The IdP is asked to take your credentials again (``prompt=login``, ``max_age=0``), and the callback answers with the grant instead of a session. + """ + account = bound_account(request, user.user_id) + held = _sign_ins(account=account) if account is not None else set() + if not (held): + raise ProblemError( + 409, + "You have no identity-provider sign-in: confirm it is you with your password", + code="reauth_via_password", + ) + own = (account.oidc_id, account.subject) + provider = own[0] if own in held else sorted(held)[0][0] + rp = await _rp_or_404(request, provider) + return_to = validate_return_to( + body.return_to, _origin(str(request.base_url)), settings.api.cors_origins + ) + redirect_uri = str(request.url_for("oidc_callback", provider=provider)) + url = await rp.login_authorization_url( + provider, request, redirect_uri, max_age=0, prompt="login" + ) + request.session[_REAUTH_SESSION_KEY] = { + "caller": user.user_id, + "kind": body.kind, + "return_to": return_to, + "started": int(time.time()), + "state": parse_qs(urlsplit(url).query).get("state", [""])[0], + "target": body.target, + } + return OidcLoginResponse(authorization_url=url) diff --git a/src/dfe_engine/api/v1/oidc_providers.py b/src/dfe_engine/api/v1/oidc_providers.py index bbd6c7c28..c5fcf508c 100644 --- a/src/dfe_engine/api/v1/oidc_providers.py +++ b/src/dfe_engine/api/v1/oidc_providers.py @@ -46,17 +46,33 @@ from scalo.logger import logger from dfe_engine.api.conventions import apply_search -from dfe_engine.api.deps import CurrentUser, provider_bindings, require_action, secrets_store +from dfe_engine.api.deps import ( + CurrentUser, + ReauthGrant, + provider_bindings, + reaches_org, + reads_every_org, + refuse_unknown_orgs, + refuse_unreachable_org, + refuse_without_grant, + require_action, + require_own_org_action, + require_provider_reauth, + secrets_store, +) from dfe_engine.auth.audit import audit_resource_change +from dfe_engine.auth.identity_links import unlink_provider from dfe_engine.auth.oidc.credential_env import ( env_var_resolves, is_env_var_name, provider_secret_path, ) from dfe_engine.auth.oidc.field_rules import FieldProblem, field_problems -from dfe_engine.auth.oidc.models import SyncStatus +from dfe_engine.auth.oidc.models import SyncStatus, checked_email_domains from dfe_engine.auth.oidc.sync import SyncOutcome from dfe_engine.auth.rbac_scopes import scopes_dict +from dfe_engine.auth.reauth import grant_target +from dfe_engine.auth.scim_mapping import SCIM_SOURCE_PROVIDER from dfe_engine.governance.ch import request_ch_rbac_reconcile from dfe_engine.http_errors import ( describe_http_error, @@ -65,9 +81,12 @@ referenced, ) from dfe_engine.names import StoreName +from dfe_engine.orgs.role_groups import usable_org_admins if TYPE_CHECKING: from dfe_engine.auth.oidc.models import GroupResolutionConfig, OIDCProvider + from dfe_engine.auth.oidc.registry import OIDCProviderRegistry + router = APIRouter(prefix="/oidc-providers", tags=["OIDC Providers"]) @@ -93,6 +112,19 @@ # An RFC 6749 section 3.3 scope-token: printable ASCII except space, double quote and backslash. _SCOPE_TOKEN = re.compile(r"[\x21\x23-\x5B\x5D-\x7E]+\Z") +_ORG_HELP = ( + "The org whose provider this is: a registered org's name, or empty for a platform " + "provider. Its sign-ins land in that org as viewers and link only to that org's " + "accounts. An admin of that org manages it." +) + +_TRUSTED_EMAIL_DOMAINS_HELP = ( + "Email domains this provider vouches for, such as corp.com. A first sign-in whose " + "verified email is in one of them links to the one account holding that email: " + "at once for an account an identity provider owns, after the account's password " + "for a local one. Stored lowercased. Empty links nothing." +) + _SCOPES_HELP = ( "OAuth scopes requested at login, one scope per entry; must include openid. One " "space-separated string is accepted too, and a blank one is no override. Omit for " @@ -227,6 +259,7 @@ class CreateProviderRequest(BaseModel): type: Literal["generic", "google", "entra_id", "okta"] = Field( description="Provider type: generic, google, entra_id, okta" ) + org: str = Field(default="", description=_ORG_HELP) enabled: bool = Field(default=True, description="Whether the provider serves logins") display_name: str = Field(default="", description="Human-readable label") issuer: str = Field(default="", description="OIDC issuer URL") @@ -247,12 +280,20 @@ class CreateProviderRequest(BaseModel): ) scopes: list[str] | None = Field(default=None, description=_SCOPES_HELP) groups: GroupResolutionRequest = Field(default_factory=GroupResolutionRequest) + trusted_email_domains: list[str] = Field( + default_factory=list, description=_TRUSTED_EMAIL_DOMAINS_HELP + ) @field_validator("client_id_env", "client_secret_env") @classmethod def _env_name_only(cls, value: str) -> str: return _reject_non_env_name(value) + @field_validator("trusted_email_domains") + @classmethod + def _bare_domains(cls, value: list[str]) -> list[str]: + return checked_email_domains(domains=value) + @field_validator("scopes", mode="before") @classmethod def _scopes_as_list(cls, value: object) -> object: @@ -267,6 +308,7 @@ def _scopes_shape(cls, value: list[str] | None) -> list[str] | None: class UpdateProviderRequest(BaseModel): """Body for updating a provider, where an omitted field keeps its value.""" + org: str | None = Field(None, description=f"Move the provider to another org. {_ORG_HELP}") enabled: bool | None = Field(None, description="Enable or disable the provider") display_name: str | None = Field(None, description="Human-readable label") issuer: str | None = Field( @@ -289,12 +331,20 @@ class UpdateProviderRequest(BaseModel): "one leaves the scopes as they are.", ) groups: GroupResolutionRequest | None = Field(None, description="Group resolution config") + trusted_email_domains: list[str] | None = Field( + None, description=f"Replace the trusted email domains. {_TRUSTED_EMAIL_DOMAINS_HELP}" + ) @field_validator("client_id_env", "client_secret_env") @classmethod def _env_name_only(cls, value: str | None) -> str | None: return value if value is None else _reject_non_env_name(value) + @field_validator("trusted_email_domains") + @classmethod + def _bare_domains(cls, value: list[str] | None) -> list[str] | None: + return value if value is None else checked_email_domains(domains=value) + @field_validator("scopes", mode="before") @classmethod def _scopes_as_list(cls, value: object) -> object: @@ -330,6 +380,7 @@ class ProviderResponse(BaseModel): name: str type: str + org: str = Field(description=_ORG_HELP) enabled: bool display_name: str issuer: str @@ -339,6 +390,7 @@ class ProviderResponse(BaseModel): client_secret_path: str scopes: list[str] = Field(description="OAuth scopes requested at login") groups: GroupResolutionResponse + trusted_email_domains: list[str] = Field(description=_TRUSTED_EMAIL_DOMAINS_HELP) created_at: str last_sync_at: str last_sync_status: SyncStatus = Field( @@ -450,12 +502,163 @@ class LoginConfigResponse(BaseModel): # -- Helpers -------------------------------------------------- +_GROUP_ENV_FIELDS = ( + "api_token_env", + "client_secret_env", + "service_account_json_env", + "tenant_id_env", +) + + +def _env_sources( + *, + client_id_env: str | None, + client_secret_env: str | None, + groups: GroupResolutionRequest | GroupResolutionConfig | None, +) -> dict[str, str]: + """Every env var name a provider body or stored provider names, by field.""" + named = {"client_id_env": client_id_env or "", "client_secret_env": client_secret_env or ""} + if groups is not None: + for field in _GROUP_ENV_FIELDS: + named[f"groups.{field}"] = getattr(groups, field) or "" + return named + + +def _refuse_env_sources( + *, named: dict[str, str], request: Request, stored: dict[str, str], user: Any +) -> None: + """Refuse 422 ``env_source_refused`` when a caller who does not act across every org names an env var the provider does not already hold, since the engine would read its own environment for it.""" + if reads_every_org(request, user, scopes_dict["oidc_write"]): + return + for field, env in sorted(named.items()): + if (env) and (env != stored.get(field, "")): + raise ProblemError( + 422, + f"{field} names env var {env!r}, which only an admin of every org may set: " + "send the credential's value instead", + code="env_source_refused", + ) + + +def _refuse_repointed_env_sources( + *, body: UpdateProviderRequest, current: OIDCProvider, request: Request, user: Any +) -> None: + """Refuse 422 ``env_source_held`` when a caller who does not act across every org moves where a provider sends credentials while it still reads one from an env var an admin of every org set.""" + if reads_every_org(request, user, scopes_dict["oidc_write"]): + return + stored = _env_sources( + client_id_env=current.client_id_env, + client_secret_env=current.client_secret_env, + groups=current.groups, + ) + # None is a field the body leaves out, which keeps its stored env var. Empty clears it. + sent = {"client_id_env": body.client_id_env, "client_secret_env": body.client_secret_env} + if body.groups is not None: + sent.update((f"groups.{field}", getattr(body.groups, field)) for field in _GROUP_ENV_FIELDS) + held = [field for field, env in stored.items() if (env) and (sent.get(field) != "")] + moved = (body.issuer is not None) and (body.issuer != current.issuer) + if body.groups is not None: + moved = (moved) or any( + getattr(body.groups, field) != getattr(current.groups, field) + for field in ("domain", "okta_domain", "tenant_id") + ) + if (held) and (moved): + raise ProblemError( + 422, + f"The provider reads {held[0]} from an env var an admin of every org set, so its " + "issuer and directory may not change: clear the env var sources first", + code="env_source_held", + ) + + +def _refuse_stranded_sign_ins(*, name: str, org: str, request: Request) -> None: + """Refuse 422 ``provider_in_use`` when moving provider *name* to *org* would leave accounts it signs in unreachable, since strict pairing would refuse their next sign-in.""" + home = (request.app.state.org_registry.home_name_known()) or "" + reached = {org} if org else {"", home} + for account in request.app.state.account_store.scan(): + stamped = name in { + account.oidc_id, + account.source_provider, + *(identity.provider for identity in account.identities), + } + if (stamped) and (account.org not in reached): + raise ProblemError( + 422, + f"Provider {name!r} signs in accounts the move would leave unreachable: " + "move or remove them first", + code="provider_in_use", + ) + + +def _refuse_reserved_name(*, name: str, org: str, request: Request) -> None: + """Refuse 422 ``provider_name_reserved`` for an org's provider named after a stamp sign-ins arrive under from outside that org.""" + if not (org): + return + bindings = provider_bindings(request) + reserved = { + request.app.state.settings.auth.proxy_provider, + SCIM_SOURCE_PROVIDER, + *bindings, + *bindings.values(), + } + stamped = any( + (account.org != org) + and ( + name + in { + account.oidc_id, + account.source_provider, + *(identity.provider for identity in account.identities), + } + ) + for account in request.app.state.account_store.scan() + ) + linked = any(group.source_provider == name for group in request.app.state.group_store.list()) + if (name in reserved) or (stamped) or (linked): + raise ProblemError( + 422, + f"Provider name {name!r} is reserved: sign-ins already arrive under it from " + f"outside org {org!r}", + code="provider_name_reserved", + ) + + +def _refuse_domain_of_another_org( + *, domains: list[str], name: str, org: str, registry: OIDCProviderRegistry +) -> None: + """Refuse 422 ``domain_taken`` when a provider of another org already trusts one of *domains*, since a domain belongs to one org.""" + wanted = set(domains) + for other_name, other in registry.list(): + clash = sorted(wanted & set(other.trusted_email_domains)) + if (other_name != name) and (other.org != org) and (clash): + raise ProblemError( + 422, + f"Email domain {clash[0]!r} is trusted by another organisation's provider, " + "and a domain belongs to one organisation", + code="domain_taken", + ) + + +def _require_reachable_provider( + *, action: str, name: str, request: Request, user: Any +) -> OIDCProvider: + """The provider *name*, 404 when it is missing or the caller may not take *action* on its org, so another org's providers stay hidden.""" + provider = _get_registry(request).get(name) + reachable = (provider is not None) and ( + reaches_org(action=action, org=provider.org, request=request, user=user) + ) + if (provider is None) or (not (reachable)): + raise ProblemError(404, f"OIDC provider '{name}' not found", code="not_found") + return provider + + def _provider_to_response(name: str, provider: OIDCProvider) -> ProviderResponse: """Convert an OIDCProvider model to a ProviderResponse.""" p = provider return ProviderResponse( name=name, type=p.type, + org=p.org, enabled=p.enabled, display_name=p.display_name, issuer=p.issuer, @@ -480,6 +683,7 @@ def _provider_to_response(name: str, provider: OIDCProvider) -> ProviderResponse api_token_path=p.groups.api_token_path, okta_domain=p.groups.okta_domain, ), + trusted_email_domains=p.trusted_email_domains, created_at=p.created_at, last_sync_at=p.last_sync_at, last_sync_status=p.last_sync_status, @@ -487,10 +691,8 @@ def _provider_to_response(name: str, provider: OIDCProvider) -> ProviderResponse ) -def _get_registry(request: Request): +def _get_registry(request: Request) -> OIDCProviderRegistry: """Return OIDCProviderRegistry from app state.""" - from dfe_engine.auth.oidc.registry import OIDCProviderRegistry - registry: OIDCProviderRegistry = request.app.state.oidc_provider_registry return registry @@ -663,11 +865,22 @@ async def _refresh_rp(request: Request) -> None: # -- Endpoints ------------------------------------------------ +async def require_new_provider_reauth( + body: CreateProviderRequest, request: Request, user: CurrentUser, reauth: ReauthGrant = "" +) -> None: + """FastAPI dependency: the caller's re-auth grant for the sign-in provider the body creates.""" + target = grant_target(kind="provider", name=body.name) + refuse_without_grant(reauth=reauth, request=request, target=target, user=user) + + @router.post( "", response_model=ProviderResponse, status_code=201, - dependencies=[Depends(require_action(scopes_dict["oidc_write"]))], + dependencies=[ + Depends(require_own_org_action(scopes_dict["oidc_write"])), + Depends(require_new_provider_reauth), + ], ) async def create_provider( body: CreateProviderRequest, @@ -680,9 +893,31 @@ async def create_provider( """ from dfe_engine.auth.oidc.models import OIDCProvider + refuse_unreachable_org( + action=scopes_dict["oidc_write"], + noun="OIDC providers", + org=body.org, + request=request, + user=user, + ) + refuse_unknown_orgs(request, [body.org]) registry = _get_registry(request) if registry.get(body.name) is not None: raise ProblemError(409, f"OIDC provider '{body.name}' already exists", code="conflict") + _refuse_domain_of_another_org( + domains=body.trusted_email_domains, name=body.name, org=body.org, registry=registry + ) + _refuse_reserved_name(name=body.name, org=body.org, request=request) + _refuse_env_sources( + named=_env_sources( + client_id_env=body.client_id_env, + client_secret_env=body.client_secret_env, + groups=body.groups, + ), + request=request, + stored={}, + user=user, + ) client_secret_path = ( provider_secret_path(field="client_secret", provider_name=body.name) @@ -692,6 +927,7 @@ async def create_provider( group_paths = _group_secret_paths(groups=body.groups, name=body.name) fields: dict[str, Any] = { "type": body.type, + "org": body.org, "enabled": body.enabled, "display_name": body.display_name, "issuer": body.issuer, @@ -702,6 +938,7 @@ async def create_provider( # Empty takes the provider type's default scopes. "scopes": " ".join(body.scopes) if body.scopes is not None else "", "groups": _group_config(groups=body.groups, kept=group_paths, provider_type=body.type), + "trusted_email_domains": body.trusted_email_domains, "created_at": datetime.now(UTC).isoformat(), } # The rules run before the model's validators, so a pair both refuse answers 422 on its field. @@ -748,7 +985,7 @@ async def create_provider( @router.get( "", response_model=Page[ProviderResponse], - dependencies=[Depends(require_action(scopes_dict["oidc_read"]))], + dependencies=[Depends(require_own_org_action(scopes_dict["oidc_read"]))], ) async def list_providers( user: CurrentUser, @@ -756,9 +993,14 @@ async def list_providers( query: ProvidersList, search: str | None = Query(None, description="Search in provider name/display name"), ): - """List OIDC providers (admin only), paginated.""" + """List the OIDC providers the caller manages, paginated: every one across orgs, else its orgs' own.""" registry = _get_registry(request) - rows = [_provider_to_response(name, p).model_dump() for name, p in registry.list()] + action = scopes_dict["oidc_read"] + rows = [ + _provider_to_response(name, p).model_dump() + for name, p in registry.list() + if reaches_org(action=action, org=p.org, request=request, user=user) + ] rows = apply_search(rows, search, ["name", "display_name"]) rows = sort_by_order(rows, query.order_by) summaries = [ProviderResponse.model_validate(row) for row in rows] @@ -768,25 +1010,27 @@ async def list_providers( @router.get( "/{name}", response_model=ProviderResponse, - dependencies=[Depends(require_action(scopes_dict["oidc_read"]))], + dependencies=[Depends(require_own_org_action(scopes_dict["oidc_read"]))], ) async def get_provider( name: str, user: CurrentUser, request: Request, ): - """Get a single OIDC provider by name (admin only).""" - registry = _get_registry(request) - provider = registry.get(name) - if provider is None: - raise ProblemError(404, f"OIDC provider '{name}' not found", code="not_found") + """Get a single OIDC provider by name, 404 for one of an org the caller does not manage.""" + provider = _require_reachable_provider( + action=scopes_dict["oidc_read"], name=name, request=request, user=user + ) return _provider_to_response(name, provider) @router.put( "/{name}", response_model=ProviderResponse, - dependencies=[Depends(require_action(scopes_dict["oidc_write"]))], + dependencies=[ + Depends(require_own_org_action(scopes_dict["oidc_write"])), + Depends(require_provider_reauth), + ], ) async def update_provider( name: str, @@ -796,16 +1040,47 @@ async def update_provider( ): """Update an OIDC provider configuration (admin only). - A secret the body omits, value and env var name alike, keeps what the provider already holds, so an update that only flips ``enabled`` does not strand a stored credential. An empty env var name clears the name and keeps the stored copy. A secret the body names an env var for and sends no value for moves onto that env var and its stored copy is deleted once the update is saved, unless the name is the one already held with nothing stored. A move onto an env var the engine does not set is refused (``env_var_not_set``). Any update that touches more than ``enabled`` or ``display_name`` must leave the provider passing the field rules. Both are checked before a secret is written or deleted. + A secret the body omits, value and env var name alike, keeps what the provider already holds, so an update that only flips ``enabled`` does not strand a stored credential. An empty env var name clears the name and keeps the stored copy. A secret the body names an env var for and sends no value for moves onto that env var and its stored copy is deleted once the update is saved, unless the name is the one already held with nothing stored. A move onto an env var the engine does not set is refused (``env_var_not_set``). Any update that touches more than ``enabled``, ``display_name`` and ``trusted_email_domains`` must leave the provider passing the field rules. Both are checked before a secret is written or deleted. """ + action = scopes_dict["oidc_write"] registry = _get_registry(request) - current = registry.get(name) - if current is None: - raise ProblemError(404, f"OIDC provider '{name}' not found", code="not_found") + current = _require_reachable_provider(action=action, name=name, request=request, user=user) + org = current.org if body.org is None else body.org + if org != current.org: + refuse_unreachable_org( + action=action, noun="OIDC providers", org=org, request=request, user=user + ) + refuse_unknown_orgs(request, [org]) + _refuse_reserved_name(name=name, org=org, request=request) + _refuse_stranded_sign_ins(name=name, org=org, request=request) + _refuse_env_sources( + named=_env_sources( + client_id_env=body.client_id_env, + client_secret_env=body.client_secret_env, + groups=body.groups, + ), + request=request, + stored=_env_sources( + client_id_env=current.client_id_env, + client_secret_env=current.client_secret_env, + groups=current.groups, + ), + user=user, + ) + _refuse_repointed_env_sources(body=body, current=current, request=request, user=user) + if (body.trusted_email_domains is not None) or (org != current.org): + domains = ( + current.trusted_email_domains + if body.trusted_email_domains is None + else body.trusted_email_domains + ) + _refuse_domain_of_another_org(domains=domains, name=name, org=org, registry=registry) stale_paths = [] env_problems = [] update_fields: dict[str, object] = {} + if body.org is not None: + update_fields["org"] = body.org if body.enabled is not None: update_fields["enabled"] = body.enabled if body.display_name is not None: @@ -820,6 +1095,8 @@ async def update_provider( update_fields["client_secret_env"] = body.client_secret_env if body.scopes is not None: update_fields["scopes"] = " ".join(body.scopes) + if body.trusted_email_domains is not None: + update_fields["trusted_email_domains"] = body.trusted_email_domains if body.client_secret: update_fields["client_secret_path"] = provider_secret_path( field="client_secret", provider_name=name @@ -864,7 +1141,9 @@ async def update_provider( ) rule_problems = [] - if body.model_dump(exclude={"display_name", "enabled"}, exclude_none=True): + if body.model_dump( + exclude={"display_name", "enabled", "org", "trusted_email_domains"}, exclude_none=True + ): candidate = current.model_copy(update=update_fields) problems = field_problems( provider=candidate, sent_group_fields=_sent_group_fields(groups=body.groups) @@ -896,7 +1175,10 @@ async def update_provider( @router.delete( "/{name}", response_model=DetachResponse, - dependencies=[Depends(require_action(scopes_dict["oidc_delete"]))], + dependencies=[ + Depends(require_own_org_action(scopes_dict["oidc_delete"])), + Depends(require_provider_reauth), + ], ) async def delete_provider( name: str, @@ -909,17 +1191,18 @@ async def delete_provider( still set to the deleted provider name. Accounts owned by the provider (``source_provider``) or last logged in through it (``oidc_id``) are soft-deleted: disabled and renamed to ``{uuid}-deleted`` with contact fields - cleared. The provider's stored credentials ARE removed: nothing is left that - can authenticate as a detached provider. + cleared. A sign-in linked through it to another account is unlinked and that + account's sessions end, but the account stays. The provider's stored credentials + ARE removed: nothing is left that can authenticate as a detached provider. """ from dfe_engine.auth.accounts import soft_delete_account from dfe_engine.auth.groups import GroupStore from dfe_engine.auth.protected_accounts import ProtectedAccountError registry = _get_registry(request) - provider = registry.get(name) - if provider is None: - raise ProblemError(404, f"OIDC provider '{name}' not found", code="not_found") + provider = _require_reachable_provider( + action=scopes_dict["oidc_delete"], name=name, request=request, user=user + ) # Find groups that reference this provider group_store: GroupStore = request.app.state.group_store @@ -935,14 +1218,34 @@ async def delete_provider( ) ) - # Soft-delete accounts tied to this provider before the YAML is gone. + # Soft-delete accounts tied to this provider before the YAML is gone. An org's provider reaches only that org's. account_store = request.app.state.account_store + org = provider.org + owned = [ + account + for account in account_store.list() + if ((account.source_provider == name) or (account.oidc_id == name)) + and (account.enabled) + and (not (account.is_link_record)) + and ((not (org)) or (account.org == org)) + ] + if (org) and (not (reads_every_org(request, user, scopes_dict["oidc_delete"]))): + admins = usable_org_admins( + accounts=account_store.list(), + bindings=provider_bindings(request), + groups=group_store.list(), + org=org, + ) + if (admins) and (set(admins) <= {account.username for account in owned}): + raise ProblemError( + 409, + f"Cannot delete provider {name!r}: every admin of org {org!r} signs in through it", + code="last_org_admin", + ) + # A sign-in linked through it leaves its account, which the provider does not own. + unlink_provider(org=org, provider=name, store=account_store) disabled_accounts: list[DisabledAccountInfo] = [] - for account in account_store.list(): - if account.source_provider != name and account.oidc_id != name: - continue - if not account.enabled: - continue + for account in owned: previous = account.username try: updated = soft_delete_account(account_store, previous) @@ -974,7 +1277,10 @@ async def delete_provider( @router.post( "/{name}/sync", response_model=SyncResponse, - dependencies=[Depends(require_action(scopes_dict["oidc_write"]))], + dependencies=[ + Depends(require_action(scopes_dict["oidc_write"])), + Depends(require_provider_reauth), + ], ) async def sync_provider_groups( name: str, @@ -1017,7 +1323,7 @@ async def sync_provider_groups( "/{name}/test", response_model=TestResponse, openapi_extra=scalo_extra(verb="test"), - dependencies=[Depends(require_action(scopes_dict["oidc_read"]))], + dependencies=[Depends(require_own_org_action(scopes_dict["oidc_read"]))], ) async def test_provider( name: str, @@ -1027,10 +1333,9 @@ async def test_provider( """Test connectivity to an OIDC provider (admin only).""" from dfe_engine.auth.oidc.adapters import get_adapter - registry = _get_registry(request) - provider = registry.get(name) - if provider is None: - raise ProblemError(404, f"OIDC provider '{name}' not found", code="not_found") + provider = _require_reachable_provider( + action=scopes_dict["oidc_read"], name=name, request=request, user=user + ) adapter = get_adapter(provider, secrets=getattr(request.app.state, "dfe_secrets", None)) success, message = await adapter.test_connection() @@ -1041,7 +1346,7 @@ async def test_provider( "/{name}/verify-login", response_model=LoginConfigResponse, openapi_extra=scalo_extra(verb="verify-login"), - dependencies=[Depends(require_action(scopes_dict["oidc_read"]))], + dependencies=[Depends(require_own_org_action(scopes_dict["oidc_read"]))], ) async def verify_login_config( name: str, @@ -1055,10 +1360,9 @@ async def verify_login_config( generic providers. Checks: the client_id resolves, the client_secret resolves, and the issuer's discovery document is reachable and well-formed. """ - registry = _get_registry(request) - provider = registry.get(name) - if provider is None: - raise ProblemError(404, f"OIDC provider '{name}' not found", code="not_found") + provider = _require_reachable_provider( + action=scopes_dict["oidc_read"], name=name, request=request, user=user + ) from dfe_engine.auth.oidc.credential_env import credential_check diff --git a/src/dfe_engine/api/v1/queries.py b/src/dfe_engine/api/v1/queries.py index 75d1e7d3d..6776b2167 100644 --- a/src/dfe_engine/api/v1/queries.py +++ b/src/dfe_engine/api/v1/queries.py @@ -27,9 +27,11 @@ from dfe_engine.api.deps import ( CurrentUser, Settings, + check_action, granted_bound_org, live_role_config, require_action, + require_own_org_action, ) from dfe_engine.api.errors import backend_failure from dfe_engine.auth.rbac_scopes import scopes_dict @@ -167,7 +169,7 @@ def get_view( @router.post( "/views/{label:path}/execute", response_model=QueryResponse, - dependencies=[Depends(require_action(scopes_dict["query_execute"]))], + dependencies=[Depends(require_own_org_action(scopes_dict["query_execute"]))], ) def execute_view( label: str, @@ -181,7 +183,8 @@ def execute_view( The ``org_id`` parameter is always injected from the authenticated user's context -- it cannot be overridden by the client. It is the org the session's account is bound to, and a view taking it runs only when the caller's - groups grant that org or it reads every org (``granted_bound_org``). + groups grant that org or it reads every org (``granted_bound_org``). Any other + view needs ``query:execute`` at system scope. """ from dfe_engine.query.executor import ViewExecutionError, ViewRequestError @@ -191,6 +194,8 @@ def execute_view( raise ProblemError(404, f"View '{label}' not found", code="not_found") if view_def.tenant_isolated: granted_bound_org(request, user, scopes_dict["query_execute"]) + else: + check_action(request, user, scopes_dict["query_execute"]) try: result = executor.execute( label=label, diff --git a/src/dfe_engine/api/v1/roles.py b/src/dfe_engine/api/v1/roles.py index e29a2aa9d..b3ac90889 100644 --- a/src/dfe_engine/api/v1/roles.py +++ b/src/dfe_engine/api/v1/roles.py @@ -27,11 +27,19 @@ from scalo.api import ListParams, Page, ProblemError, paginate from dfe_engine.api.conventions import apply_search -from dfe_engine.api.deps import CurrentUser, live_role_config, require_action +from dfe_engine.api.deps import ( + CurrentUser, + ReauthGrant, + live_role_config, + refuse_without_grant, + require_action, + require_role_reauth, +) from dfe_engine.auth import AuthContext, AuthorizationError, RoleConfig, Scope from dfe_engine.auth.audit import audit_permission_denied, audit_role_change from dfe_engine.auth.models import ungrantable_permissions from dfe_engine.auth.rbac_scopes import casbin_scope_catalog, scopes_dict +from dfe_engine.auth.reauth import grant_target from dfe_engine.auth.role_store import Role, RoleStore from dfe_engine.auth.roles import scoped_role_refusal from dfe_engine.governance.ch import request_ch_rbac_reconcile @@ -39,6 +47,7 @@ RoleResourceTypeQuery = Literal["core", "custom"] + router = APIRouter(prefix="/roles", tags=["Roles"]) @@ -185,11 +194,22 @@ async def list_casbin_scopes( ) +async def require_new_role_reauth( + body: CreateRoleRequest, request: Request, user: CurrentUser, reauth: ReauthGrant = "" +) -> None: + """FastAPI dependency: the caller's re-auth grant for the role the body creates.""" + target = grant_target(kind="role", name=body.name) + refuse_without_grant(reauth=reauth, request=request, target=target, user=user) + + @router.post( "", response_model=RoleResponse, status_code=201, - dependencies=[Depends(require_action(scopes_dict["role_write"]))], + dependencies=[ + Depends(require_action(scopes_dict["role_write"])), + Depends(require_new_role_reauth), + ], ) async def create_role( body: CreateRoleRequest, @@ -265,7 +285,10 @@ async def get_role( @router.put( "/{name}", response_model=RoleResponse, - dependencies=[Depends(require_action(scopes_dict["role_write"]))], + dependencies=[ + Depends(require_action(scopes_dict["role_write"])), + Depends(require_role_reauth), + ], ) async def update_role( name: str, @@ -302,7 +325,10 @@ async def update_role( @router.delete( "/{name}", status_code=204, - dependencies=[Depends(require_action(scopes_dict["role_delete"]))], + dependencies=[ + Depends(require_action(scopes_dict["role_delete"])), + Depends(require_role_reauth), + ], ) async def delete_role( name: str, diff --git a/src/dfe_engine/api/v1/scim.py b/src/dfe_engine/api/v1/scim.py index 500dfd4d5..9e337bb3b 100644 --- a/src/dfe_engine/api/v1/scim.py +++ b/src/dfe_engine/api/v1/scim.py @@ -60,10 +60,31 @@ User as ScimUser, ) -from dfe_engine.api.deps import CurrentUser, provider_bindings, require_platform_action +from dfe_engine.api.deps import ( + CurrentUser, + ReauthGrant, + is_own_account, + provider_bindings, + refuse_without_grant, + require_platform_action, + require_scim_group_reauth, + require_scim_user_reauth, +) from dfe_engine.api.password_floor import FLOOR_MESSAGE, below_floor, count_floor_refusal -from dfe_engine.api.v1.account_groups import check_group_changes, check_role_assignment, scope_of -from dfe_engine.auth.accounts import AccountExistsError, discard_created +from dfe_engine.api.v1.account_groups import ( + check_group_changes, + check_role_assignment, + org_link_holders, + org_role_refusal, + scope_of, +) +from dfe_engine.auth.accounts import ( + Account, + AccountExistsError, + AccountStore, + delete_link_records, + discard_created, +) from dfe_engine.auth.audit import audit_account_change, audit_group_change from dfe_engine.auth.groups import ( Group, @@ -73,6 +94,7 @@ ) from dfe_engine.auth.membership import forget_member, groups_held, linked_providers from dfe_engine.auth.rbac_scopes import scopes_dict +from dfe_engine.auth.reauth import grant_target from dfe_engine.auth.scim_mapping import ( account_to_scim_user, generate_provisioning_password, @@ -172,6 +194,12 @@ async def _parse_body(request: Request): return None +async def _named_in_body(*, field: str, request: Request) -> str: + """The *field* a SCIM create body names, or empty when the body names none.""" + body = await _parse_body(request) + return str(body.get(field) or "") if isinstance(body, dict) else "" + + def _filter_terms(raw: str) -> dict[str, str] | None: """Map each ``eq`` term of an ``and`` filter to its value, or None for any other form.""" terms: dict[str, str] = {} @@ -226,6 +254,12 @@ def _ascii_ieq(name: str, value: str) -> bool: } +def _stored_user(*, store: AccountStore, user_id: str) -> Account | None: + """The account stored as *user_id*, or None for a link record, which belongs to the account it links to.""" + account = store.get(user_id) + return None if (account is None) or (account.is_link_record) else account + + def _page_params(request: Request) -> tuple[int, int]: """Return 1-based ``(start_index, count)`` from query params (SCIM defaults).""" try: @@ -308,6 +342,23 @@ def _scim_last_admin_member_removals( # -- /Users --------------------------------------------------- +async def require_new_scim_group_reauth( + request: Request, user: CurrentUser, reauth: ReauthGrant = "" +) -> None: + """FastAPI dependency: the caller's re-auth grant for the group a SCIM create names.""" + name = await _named_in_body(field="displayName", request=request) + target = grant_target(kind="group", name=name) + refuse_without_grant(reauth=reauth, request=request, target=target, user=user) + + +async def require_new_scim_user_reauth( + request: Request, user: CurrentUser, reauth: ReauthGrant = "" +) -> None: + """FastAPI dependency: the caller's re-auth grant for the account a SCIM create names.""" + name = await _named_in_body(field="userName", request=request) + refuse_without_grant(reauth=reauth, request=request, target=name, user=user) + + @router.get( "/Users", dependencies=[Depends(require_platform_action(scopes_dict["account_read"]))], @@ -316,7 +367,8 @@ async def list_users(user: CurrentUser, request: Request) -> Response: """List users (SCIM ListResponse). Supports ``userName eq``, ``externalId eq`` + paging.""" store = request.app.state.account_store group_store = request.app.state.group_store - accounts = _filtered(request, store.list(), _USER_FILTERS) + users = [account for account in store.list() if not (account.is_link_record)] + accounts = _filtered(request, users, _USER_FILTERS) if isinstance(accounts, JSONResponse): return accounts @@ -355,7 +407,7 @@ async def get_user(user_id: str, user: CurrentUser, request: Request) -> Respons """Fetch a single user by id (username).""" store = request.app.state.account_store group_store = request.app.state.group_store - account = store.get(user_id) + account = _stored_user(store=store, user_id=user_id) if account is None: return scim_error(404, f"User '{user_id}' not found") groups = groups_held(account, group_store.list(), bindings=provider_bindings(request)) @@ -367,7 +419,10 @@ async def get_user(user_id: str, user: CurrentUser, request: Request) -> Respons @router.post( "/Users", - dependencies=[Depends(require_platform_action(scopes_dict["account_write"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["account_write"])), + Depends(require_new_scim_user_reauth), + ], ) async def create_user(user: CurrentUser, request: Request) -> Response: """Provision a user. IdP-owned. Local password is randomised when omitted. @@ -427,7 +482,10 @@ async def create_user(user: CurrentUser, request: Request) -> Response: @router.put( "/Users/{user_id}", - dependencies=[Depends(require_platform_action(scopes_dict["account_write"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["account_write"])), + Depends(require_scim_user_reauth), + ], ) async def replace_user(user_id: str, user: CurrentUser, request: Request) -> Response: """Replace a user's writable attributes (SCIM PUT).""" @@ -438,7 +496,7 @@ async def replace_user(user_id: str, user: CurrentUser, request: Request) -> Res return scim_error(400, "Malformed JSON body", "invalidSyntax") store = request.app.state.account_store group_store = request.app.state.group_store - existing = store.get(user_id) + existing = _stored_user(store=store, user_id=user_id) if existing is None: return scim_error(404, f"User '{user_id}' not found") try: @@ -483,7 +541,10 @@ async def replace_user(user_id: str, user: CurrentUser, request: Request) -> Res @router.patch( "/Users/{user_id}", - dependencies=[Depends(require_platform_action(scopes_dict["account_write"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["account_write"])), + Depends(require_scim_user_reauth), + ], ) async def patch_user(user_id: str, user: CurrentUser, request: Request) -> Response: """Apply a PatchOp - primarily the ``active`` toggle IdPs use to deprovision.""" @@ -494,7 +555,7 @@ async def patch_user(user_id: str, user: CurrentUser, request: Request) -> Respo return scim_error(400, "Malformed JSON body", "invalidSyntax") store = request.app.state.account_store group_store = request.app.state.group_store - existing = store.get(user_id) + existing = _stored_user(store=store, user_id=user_id) if existing is None: return scim_error(404, f"User '{user_id}' not found") try: @@ -547,7 +608,10 @@ async def patch_user(user_id: str, user: CurrentUser, request: Request) -> Respo @router.delete( "/Users/{user_id}", - dependencies=[Depends(require_platform_action(scopes_dict["account_write"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["account_write"])), + Depends(require_scim_user_reauth), + ], ) async def delete_user(user_id: str, user: CurrentUser, request: Request) -> Response: """Delete a user (SCIM 204).""" @@ -555,10 +619,10 @@ async def delete_user(user_id: str, user: CurrentUser, request: Request) -> Resp store = request.app.state.account_store group_store = request.app.state.group_store - existing = store.get(user_id) + existing = _stored_user(store=store, user_id=user_id) if existing is None: return scim_error(404, f"User '{user_id}' not found") - if user_id == user.user_id: + if is_own_account(request=request, user=user, username=user_id): return scim_error(403, "Cannot delete your own account") # Deleting a user takes it out of every group it holds, so it needs their roles. groups = group_store.list() @@ -577,6 +641,7 @@ async def delete_user(user_id: str, user: CurrentUser, request: Request) -> Resp ), ) store.delete(user_id) + delete_link_records(store, existing) forget_member(group_store, user_id) audit_account_change(user.user_id, user_id, "deleted", _audit_details(groups=held)) return Response(status_code=204) @@ -636,7 +701,10 @@ async def get_group(group_id: str, user: CurrentUser, request: Request) -> Respo @router.post( "/Groups", - dependencies=[Depends(require_platform_action(scopes_dict["group_write"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["group_write"])), + Depends(require_new_scim_group_reauth), + ], ) async def create_group(user: CurrentUser, request: Request) -> Response: """Provision a group with its member set (member Account.groups kept in sync).""" @@ -669,6 +737,9 @@ async def create_group(user: CurrentUser, request: Request) -> Response: ) if collision is not None: return collision + refusal = org_role_refusal(group=Group(name=name), members=members, request=request) + if refusal is not None: + return scim_error(400, refusal, "invalidValue") # create() decides, not get(): get() reports a stored group that does not load as absent. try: group = store.create(name, roles=[], description="", members=members) @@ -687,7 +758,10 @@ async def create_group(user: CurrentUser, request: Request) -> Response: @router.put( "/Groups/{group_id}", - dependencies=[Depends(require_platform_action(scopes_dict["group_write"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["group_write"])), + Depends(require_scim_group_reauth), + ], ) async def replace_group(group_id: str, user: CurrentUser, request: Request) -> Response: """Replace a group's member set (SCIM PUT).""" @@ -739,6 +813,13 @@ async def replace_group(group_id: str, user: CurrentUser, request: Request) -> R provider = existing.source_provider if fields["source_id"] and not provider: provider = fields["source_provider"] + stored = existing.model_copy( + update={"source_id": fields["source_id"], "source_provider": provider} + ) + linked = org_link_holders(group=stored, request=request) if moves_link else [] + refusal = org_role_refusal(group=stored, members=[*(new - old), *linked], request=request) + if refusal is not None: + return scim_error(400, refusal, "invalidValue") store.update( group_id, members=new_members, @@ -760,7 +841,10 @@ async def replace_group(group_id: str, user: CurrentUser, request: Request) -> R @router.patch( "/Groups/{group_id}", - dependencies=[Depends(require_platform_action(scopes_dict["group_write"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["group_write"])), + Depends(require_scim_group_reauth), + ], ) async def patch_group(group_id: str, user: CurrentUser, request: Request) -> Response: """Apply a PatchOp on group membership (add/remove/replace members).""" @@ -789,6 +873,9 @@ async def patch_group(group_id: str, user: CurrentUser, request: Request) -> Res # Checked before anything is written, so a refusal leaves the membership as it was. if added or removed: check_role_assignment(request, user, group.roles, scope_of(group)) + refusal = org_role_refusal(group=group, members=added, request=request) + if refusal is not None: + return scim_error(400, refusal, "invalidValue") # Recovery credentials before last-admin: a drop of admin/breakglass is 403, not 409. store.protected.check_members_replaced(group_id, group.members, members) last_admin = _scim_last_admin_member_removals(request, group_name=group_id, removed=removed) @@ -809,7 +896,10 @@ async def patch_group(group_id: str, user: CurrentUser, request: Request) -> Res @router.delete( "/Groups/{group_id}", - dependencies=[Depends(require_platform_action(scopes_dict["group_delete"]))], + dependencies=[ + Depends(require_platform_action(scopes_dict["group_delete"])), + Depends(require_scim_group_reauth), + ], ) async def delete_group(group_id: str, user: CurrentUser, request: Request) -> Response: """Delete a group. Members are detached first so the store permits removal.""" diff --git a/src/dfe_engine/auth/accounts.py b/src/dfe_engine/auth/accounts.py index 8291c4bea..0a926ced7 100644 --- a/src/dfe_engine/auth/accounts.py +++ b/src/dfe_engine/auth/accounts.py @@ -90,6 +90,22 @@ class AccountExistsError(ValueError): """An account is already stored under the name, including one created a moment ago.""" +class LinkedIdentity(BaseModel): + """An IdP sign-in linked to an account, with what its IdP last asserted.""" + + key: str + """The link record's account name: the sign-in's JIT stem.""" + provider: str + """The OIDC provider the sign-in comes through.""" + subject: str + """The IdP ``sub`` claim.""" + email: str = "" + groups: list[str] = Field(default_factory=list) + """The identifiers the IdP last asserted, which link groups under ``provider``.""" + linked_at: str = "" + last_login_at: str = "" + + class Account(BaseModel): """A local user account.""" @@ -133,7 +149,7 @@ class Account(BaseModel): attributes: dict[str, Any] = Field(default_factory=dict) """Free-form NON-sensitive attributes (nested JSON, KVP is the floor). - Stored inline on the account and round-trips through both backends. Never put + Stored inline on the account and round-trips through the store. Never put secrets here - a broad account read returns this blob. Sensitive attributes live in the separate keyed store (:mod:`dfe_engine.auth.attributes`).""" password_change_required: bool = False @@ -161,12 +177,31 @@ class Account(BaseModel): Written when the account is renamed to ``{uuid}-deleted``. Empty on an account that has never been soft-deleted.""" + email_verified: bool | None = None + """Whether ``email`` is vouched for, so a first IdP sign-in may link here by it. + + True: an admin set it, or an IdP trusted for its domain asserted it verified. False: the + account owner set it, or the IdP did not vouch. None: written before the field existed.""" + linked_to: str = "" + """Set on a link record: the account its IdP sign-in belongs to. A link record holds no groups and is never listed.""" + identities: list[LinkedIdentity] = Field(default_factory=list) + """The IdP sign-ins linked to this account.""" + + @property + def is_link_record(self) -> bool: + """Whether this record only points an IdP sign-in at another account.""" + return bool(self.linked_to) @property def is_soft_deleted(self) -> bool: """Whether this account was anonymized by soft-delete and should read as gone.""" return bool(self.previous_username) or self.username.endswith("-deleted") + @property + def session_subject(self) -> str: + """The ``sub`` a session token for this account carries, which the per-request lookup binds back to it.""" + return self.subject or self.username + def session_marker(self) -> str: """The value a session token minted for this account now carries. @@ -202,6 +237,8 @@ class AccountStore: def __init__(self, accounts_dir: Path, *, admin_name: str = "") -> None: self._dir = Path(accounts_dir) self._dir.mkdir(parents=True, exist_ok=True) + # Link records sit apart, so the accounts directory holds only people. Made on the first one. + self._links = self._dir / "links" self.protected = resolve_floor(admin_name) self._ignores_case = _ignores_case(self._dir) _dummy_hash() @@ -221,6 +258,7 @@ def create( name: str = "", org: str = "", change_required: bool = False, + email_verified: bool | None = None, ) -> Account: """Create a new account. @@ -234,6 +272,7 @@ def create( org: The registered org the account belongs to, empty for none. change_required: The password is issued, not the owner's own, so the owner must replace it before the API serves them. + email_verified: Whether *email* is vouched for (:attr:`Account.email_verified`). Returns: The newly created Account. @@ -248,8 +287,8 @@ def create( if not VALID_NAME.match(username): raise InvalidNameError(f"Invalid account name: {username!r}") path = self._path(username) - if (twin := case_twin(self._dir, username)) is not None: - raise AccountExistsError(f"Account already exists: {twin}") + if (taken := self.taken_name(username)) is not None: + raise AccountExistsError(f"Account already exists: {taken}") account = _new_account( username, password, @@ -259,6 +298,7 @@ def create( name=name, org=org, change_required=change_required, + email_verified=email_verified, ) try: self._write_new(path, account) @@ -266,6 +306,19 @@ def create( raise AccountExistsError(f"Account already exists: {username}") from exc return account + def taken_name(self, username: str) -> str | None: + """The stored account or link record a new account named *username* clashes with, matched ignoring case. An invalid name clashes with none.""" + if not VALID_NAME.match(username): + return None + for directory in (self._dir, self._links): + if (twin := case_twin(directory, username)) is not None: + return twin + # case_twin reports only another case, so the exact name is looked up in both directories. + name = self._path(username).name + if ((self._dir / name).exists()) or ((self._links / name).exists()): + return username + return None + def put(self, account: Account, *, allow_protected: bool = False) -> Account: """Upsert a complete account (used to restore from the durable deploy repo). @@ -334,7 +387,8 @@ def scan(self) -> Iterator[Account]: Yields: Each stored Account, ordered by filename. """ - for path in sorted(self._dir.glob("*.yaml")): + paths = [*self._dir.glob("*.yaml"), *self._links.glob("*.yaml")] + for path in sorted(paths, key=_file_name): try: yield self._read(path) except FileNotFoundError: @@ -345,7 +399,7 @@ def update(self, username: str, *, allow_protected: bool = False, **fields: obje Permitted fields: ``enabled``, ``blocked``, ``disabled_at``, ``blocked_at``, ``groups``, ``email``, ``phone``, ``name``, ``org``, plus - the external-identity stamps. Updating ``username`` or ``password_hash`` + the external-identity stamps and links. Updating ``username`` or ``password_hash`` directly is not permitted (use :meth:`reset_password` to change the password). Re-enabling or unblocking always clears the matching ``*_at`` field. Disabling or blocking always writes a new stamp. @@ -510,19 +564,27 @@ def _path(self, username: str) -> Path: """ return self._dir / f"{store_key(username)}.yaml" + def _home(self, *, account: Account) -> Path: + """The file *account* belongs in: under links/ for a link record, beside the people otherwise.""" + directory = self._links if account.is_link_record else self._dir + return directory / f"{store_key(account.username)}.yaml" + def _stored(self, username: str) -> Path | None: - """The file holding the account stored under exactly *username*, or None. + """The file holding the account stored under exactly *username*, a person's or a link record's, or None. Raises: KeyError: No account can hold *username*, so it is looked up nowhere. """ - path = self._path(username) - if not path.exists(): - return None - # A case-blind filesystem opens bob.yaml for Bob, so the entry's own name must match. - if self._ignores_case and path.name not in os.listdir(self._dir): - return None - return path + name = self._path(username).name + for directory in (self._dir, self._links): + path = directory / name + if not (path.exists()): + continue + # A case-blind filesystem opens bob.yaml for Bob, so the entry's own name must match. + if self._ignores_case and name not in os.listdir(directory): + continue + return path + return None def _read(self, path: Path) -> Account: """Load an Account from a YAML file. @@ -536,9 +598,13 @@ def _read(self, path: Path) -> Account: return Account.model_validate(data) def _write(self, path: Path, account: Account) -> None: - """Persist an Account to YAML, omitting the username field.""" + """Persist an Account to YAML, omitting the username field, moving it from *path* when it became or stopped being a link record.""" + home = self._home(account=account) + home.parent.mkdir(exist_ok=True) data = account.model_dump(exclude={"username"}) - yaml_dump(data, path) + yaml_dump(data, home) + if home != path: + path.unlink(missing_ok=True) def _write_new(self, path: Path, account: Account) -> None: """Persist a new Account to *path*, which the filesystem refuses if any file holds it. @@ -564,7 +630,7 @@ def _write_new(self, path: Path, account: Account) -> None: # Fields update() may change. username and password_hash are excluded (the -# password changes only via reset_password). Shared by both store backends. +# password changes only via reset_password). _UPDATABLE_FIELDS = ( "enabled", "blocked", @@ -581,6 +647,9 @@ def _write_new(self, path: Path, account: Account) -> None: "phone", "name", "org", + "email_verified", + "linked_to", + "identities", ) @@ -589,6 +658,11 @@ def _write_new(self, path: Path, account: Account) -> None: # ------------------------------------------------------------------ +def _file_name(path: Path) -> str: + """The sort key that orders account files by name across both directories.""" + return path.name + + def discard_created(store: AccountStore, created: Account) -> None: """Remove *created*, an account the caller's own create stored and could not finish. @@ -615,6 +689,14 @@ def discard_created(store: AccountStore, created: Account) -> None: ) +def delete_link_records(store: AccountStore, account: Account) -> None: + """Delete the link record of each sign-in linked to *account*, so none outlives it.""" + for identity in account.identities: + record = store.get(identity.key) + if (record is not None) and (record.linked_to == account.username): + store.delete(identity.key) + + def anonymized_soft_delete_username() -> str: """A one-use account name: a UUID with ``-deleted`` as the trailing marker. @@ -627,8 +709,9 @@ def anonymized_soft_delete_username() -> str: def soft_delete_account(store: AccountStore, username: str) -> Account: """Disable *username* and rename it to an anonymized ``{uuid}-deleted`` id. - Clears contact and subject fields so the record no longer identifies the - person. Ownership stamps (``source_provider``, ``oidc_id``) stay for audit. + Clears contact and subject fields and the linked sign-ins, whose link records + are deleted, so the record no longer identifies the person. Ownership stamps + (``source_provider``, ``oidc_id``) stay for audit. Raises: KeyError: No account is stored under *username*. @@ -653,6 +736,7 @@ def soft_delete_account(store: AccountStore, username: str) -> Account: "name": "", "subject": "", "attributes": {}, + "identities": [], **_session_end(existing), "updated_at": _now(), } @@ -660,6 +744,7 @@ def soft_delete_account(store: AccountStore, username: str) -> Account: store.put(rewritten) # Old key must go. The account now lives only under the anonymized name. store.delete(username) + delete_link_records(store, existing) return rewritten @@ -748,6 +833,7 @@ def _new_account( name: str, org: str, change_required: bool, + email_verified: bool | None, ) -> Account: """The record both stores write for a new account.""" now = _now() @@ -758,6 +844,7 @@ def _new_account( enabled=True, groups=groups or [], email=email, + email_verified=email_verified, phone=phone, name=name, org=org, diff --git a/src/dfe_engine/auth/audit.py b/src/dfe_engine/auth/audit.py index 5d95ef87e..68fbcbad1 100644 --- a/src/dfe_engine/auth/audit.py +++ b/src/dfe_engine/auth/audit.py @@ -320,7 +320,7 @@ def audit_jit_login_refused(user_id: str, source_provider: str, reason: str) -> source_provider: OIDC provider name that asserted it. reason: ``protected_account``, ``local_account``, ``provider_mismatch``, ``subject_mismatch``, ``api_key_subject``, ``account_disabled``, - ``account_blocked`` or ``no_role_granted``. + ``account_blocked``, ``no_role_granted`` or ``link_stale``. """ logger.warning( "auth.jit.login_refused", @@ -365,6 +365,32 @@ def audit_jit_failed(user_id: str, exc: BaseException) -> None: logger.warning("auth.jit.provision_failed", user_id=user_id, **describe_http_error(exc)) +def audit_identity_link_skipped(*, reason: str, source_provider: str, user_id: str) -> None: + """Emit a warning when a first IdP sign-in matched accounts by email but was not linked to any, so it got its own account.""" + logger.warning( + "auth.identity.link_skipped", + reason=reason, + source_provider=source_provider, + user_id=user_id, + ) + + +def audit_identity_linked(*, account: str, method: str, source_provider: str, user_id: str) -> None: + """Emit an event when an IdP sign-in is linked to an account, ``method`` being ``verified_email`` or ``password``.""" + logger.info( + "auth.identity.linked", + account=account, + method=method, + source_provider=source_provider, + user_id=user_id, + ) + + +def audit_identity_unlinked(*, account: str, admin_id: str, key: str) -> None: + """Emit an event when an admin unlinks an IdP sign-in, leaving its record a standalone account.""" + logger.info("auth.identity.unlinked", account=account, admin_id=admin_id, key=key) + + def audit_resource_change( admin_id: str, resource_type: str, diff --git a/src/dfe_engine/auth/identity_links.py b/src/dfe_engine/auth/identity_links.py new file mode 100644 index 000000000..c38fdd230 --- /dev/null +++ b/src/dfe_engine/auth/identity_links.py @@ -0,0 +1,154 @@ +# Project: dfe-engine +# File: auth/identity_links.py +# Purpose: Which account an IdP sign-in links to by email, and the ticket a password link redeems +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""Which account an IdP sign-in links to by its verified email, and the ticket a password link redeems.""" + +from collections.abc import Collection, Iterable +from datetime import timedelta + +from pydantic import BaseModel, Field + +from dfe_engine.auth.accounts import Account, AccountStore, LinkedIdentity +from dfe_engine.auth.jwt_authority import JwtAuthority + +LINK_TICKET_AUDIENCE = "dfe-engine-account-link" +"""The ``aud`` a link ticket carries, which no session token does, so the bearer path refuses it.""" + +LINK_TICKET_LIFETIME = timedelta(minutes=10) + + +class LinkTicket(BaseModel): + """The IdP sign-in a local account's password links, as the callback saw it.""" + + account: str + """The account the sign-in's email matched.""" + email: str + groups: list[str] = Field(default_factory=list) + groups_unresolved: bool = False + name: str = "" + provider: str + subject: str + """The IdP ``sub`` claim.""" + + +def asserted_groups(*, account: Account, subject: str) -> list[str]: + """The identifiers the IdP last asserted for *subject*: its linked entry's on *account*, else *account*'s own list.""" + entry = next((identity for identity in account.identities if identity.subject == subject), None) + return list(entry.groups) if entry is not None else list(account.groups) + + +def email_holders( + *, accounts: Iterable[Account], email: str, protected: Collection[str] +) -> list[Account]: + """The accounts holding *email*, ignoring case, vouched for or not. A link record, a soft-deleted account and a recovery credential never do.""" + wanted = email.strip().casefold() + if not (wanted): + return [] + return [ + account + for account in accounts + if account.email.strip().casefold() == wanted + and not (account.is_link_record) + and not (account.is_soft_deleted) + and account.username not in protected + ] + + +def link_candidates( + *, accounts: Iterable[Account], email: str, protected: Collection[str] +) -> list[Account]: + """The accounts an IdP sign-in vouched for *email* may link to. + + An account qualifies when it holds *email* (:func:`email_holders`) vouched for: an admin + set it or a trusted IdP verified it, or it is a local account's email from before the + flag existed. An email the owner set themselves never qualifies. A disabled or blocked + account still qualifies, so the login it matches is refused rather than given an + account of its own. + """ + return [ + account + for account in email_holders(accounts=accounts, email=email, protected=protected) + if (account.email_verified is True) + or ((not (account.source_provider)) and (account.email_verified is None)) + ] + + +def linked_identity(*, account: Account, key: str) -> LinkedIdentity | None: + """The sign-in *account* lists under *key*, or None.""" + return next((identity for identity in account.identities if identity.key == key), None) + + +def linked_person(*, record: Account, store: AccountStore) -> Account | None: + """The account the link record *record* points at, while it is no link record itself and still lists the record's sign-in.""" + person = store.get(record.linked_to) + if (person is None) or (person.is_link_record): + return None + entry = linked_identity(account=person, key=record.username) + return person if entry is not None and entry.subject == record.subject else None + + +def linked_through(*, account: Account, subject: str) -> bool: + """Whether *account* lists a linked sign-in for the IdP subject *subject*.""" + return any(identity.subject == subject for identity in account.identities) + + +def mint_link_ticket(*, authority: JwtAuthority, ticket: LinkTicket) -> str: + """Sign *ticket* for the link route. It carries no ``sub``, so it never names a session.""" + claims = {"aud": LINK_TICKET_AUDIENCE, **ticket.model_dump()} + return authority.sign(claims=claims, expires_delta=LINK_TICKET_LIFETIME) + + +def read_link_ticket(*, authority: JwtAuthority, token: str) -> LinkTicket: + """The ticket *token* carries, once its signature, issuer, expiry and audience check out, else ``InvalidTokenError``.""" + claims = authority.verify_for(audience=LINK_TICKET_AUDIENCE, token=token) + return LinkTicket.model_validate(claims) + + +def trusted_email(*, email: str, email_verified: bool, trusted_domains: Collection[str]) -> bool: + """Whether the IdP vouched for *email* and the provider is trusted for its domain.""" + local, at, domain = email.strip().rpartition("@") + return email_verified and bool(local and at) and domain.casefold() in trusted_domains + + +def unlink_provider(*, org: str = "", provider: str, store: AccountStore) -> list[str]: + """Unlink every sign-in through *provider*: each entry leaves its account, whose sessions end, and each link record is deleted. Returns the accounts changed. + + With *org*, only that org's accounts and records are touched, as an org's provider reaches no other. + """ + changed = [] + for account in store.list(): + if (org) and (account.org != org): + continue + if account.is_link_record: + if account.source_provider == provider: + store.delete(account.username) + continue + kept = [identity for identity in account.identities if identity.provider != provider] + if len(kept) == len(account.identities): + continue + store.update(account.username, identities=kept) + store.end_sessions(account.username) + changed.append(account.username) + return changed + + +def with_identity( + *, entry: LinkedIdentity, identities: Iterable[LinkedIdentity] +) -> list[LinkedIdentity]: + """*identities* with *entry* in place of the one under its key, or added after them.""" + listed = list(identities) + keys = [identity.key for identity in listed] + if entry.key not in keys: + return [*listed, entry] + listed[keys.index(entry.key)] = entry + return listed + + +def without_identity(*, identities: Iterable[LinkedIdentity], key: str) -> list[LinkedIdentity]: + """*identities* without the one under *key*.""" + return [identity for identity in identities if identity.key != key] diff --git a/src/dfe_engine/auth/jit.py b/src/dfe_engine/auth/jit.py index c345cde93..0912803b2 100644 --- a/src/dfe_engine/auth/jit.py +++ b/src/dfe_engine/auth/jit.py @@ -15,19 +15,23 @@ import asyncio import re -from collections.abc import Sequence +from collections.abc import Callable, Sequence from datetime import UTC, datetime -from typing import NoReturn +from typing import TYPE_CHECKING, NoReturn from scalo.logger import logger from dfe_engine.auth.accounts import ( Account, + AccountExistsError, AccountStore, + LinkedIdentity, discard_created, ) from dfe_engine.auth.audit import ( audit_account_change, + audit_identity_link_skipped, + audit_identity_linked, audit_jit_account_created, audit_jit_groups_updated, audit_jit_hdx_invited, @@ -35,11 +39,23 @@ audit_jit_team_assigned, ) from dfe_engine.auth.groups import Group, GroupStore +from dfe_engine.auth.identity_links import ( + LinkTicket, + email_holders, + link_candidates, + linked_identity, + linked_person, + with_identity, +) from dfe_engine.auth.membership import groups_held_by, linked_groups, linked_providers from dfe_engine.auth.models import AuthenticationError, Scope, ScopedGrant, platform_grants from dfe_engine.auth.protected_accounts import resolve_floor from dfe_engine.http_errors import describe_http_error from dfe_engine.names import VALID_NAME +from dfe_engine.orgs.role_groups import org_role_groups_held + +if TYPE_CHECKING: + from dfe_engine.auth.oidc.registry import OIDCProviderRegistry # Platform teams, broadest first. Only a role granted at SYSTEM scope earns one. _ROLE_TO_TEAM = { @@ -58,6 +74,17 @@ "groups. Ask a DFE administrator to link one." ) +# Says what fixes it without naming the account: the caller is unauthenticated. +_EMAIL_HELD_MESSAGE = ( + "OIDC login refused: another DFE account already uses this email. Ask a DFE " + "administrator to trust your email domain on this identity provider." +) + +_EMAIL_UNTRUSTED_MESSAGE = ( + "OIDC login refused: this identity provider did not verify an email in a domain it " + "is trusted for. Ask a DFE administrator to trust your email domain on it." +) + # A subject here takes an API key's groups (api/deps.py), so no IdP may assert one. API_KEY_SUBJECT_PREFIX = "apikey:" @@ -69,7 +96,7 @@ class JitIdentityCollisionError(AuthenticationError): user_id: The IdP-asserted subject. source_provider: The provider that asserted it. reason: ``protected_account``, ``local_account``, ``provider_mismatch``, - ``subject_mismatch`` or ``api_key_subject``. + ``subject_mismatch``, ``other_org``, ``api_key_subject`` or ``link_stale``. """ def __init__(self, user_id: str, source_provider: str, reason: str) -> None: @@ -127,6 +154,45 @@ def __init__(self, user_id: str, source_provider: str) -> None: self.reason = "no_role_granted" +class JitEmailHeldError(AuthenticationError): + """A first sign-in that cannot link while another account holds its email, so it gets no account of its own either. ``reason`` is ``email_held``.""" + + def __init__(self, user_id: str, source_provider: str) -> None: + """Record the refused subject and the provider that asserted it.""" + super().__init__(_EMAIL_HELD_MESSAGE) + self.user_id = user_id + self.source_provider = source_provider + self.reason = "email_held" + + +class JitEmailUntrustedError(AuthenticationError): + """A callback sign-in whose email the IdP did not verify, or whose domain the provider is not trusted for. ``reason`` is ``email_untrusted``.""" + + def __init__(self, user_id: str, source_provider: str) -> None: + """Record the refused subject and the provider that asserted it.""" + super().__init__(_EMAIL_UNTRUSTED_MESSAGE) + self.user_id = user_id + self.source_provider = source_provider + self.reason = "email_untrusted" + + +class JitLinkRequiredError(AuthenticationError): + """The sign-in's trusted email matches one local account, which it links to only after that account's password. + + Nothing is written. ``account`` names the matched account and ``reason`` is ``link_required``. + """ + + def __init__(self, *, account: str, source_provider: str, user_id: str) -> None: + """Record the matched account, the provider and the IdP subject.""" + super().__init__( + "Sign in with this account's password to link your identity provider to it" + ) + self.account = account + self.reason = "link_required" + self.source_provider = source_provider + self.user_id = user_id + + class JitProvisioner: """Creates and reconciles the account behind each IdP login, refusing those it may not admit.""" @@ -137,6 +203,8 @@ def __init__( hyperdx_client=None, admin_name: str = "", source_provider_bindings: dict[str, str] | None = None, + home_org: Callable[[], str | None] | None = None, + provider_registry: OIDCProviderRegistry | None = None, ) -> None: """Bind the stores, the names no IdP may assert and the deployment's provider bindings. @@ -146,6 +214,8 @@ def __init__( hyperdx_client: The client a first login's HyperDX invite goes through, if any. admin_name: The configured local admin name, protected like the default one. source_provider_bindings: ``auth.source_provider_bindings``. + home_org: Your org's name as this replica knows it, None while none is known. + provider_registry: The OIDC providers, whose org a sign-in through one lands in. """ self._accounts = account_store self._groups = group_store @@ -154,6 +224,8 @@ def __init__( # One definition of what is protected, shared with the stores that enforce it. self._protected = resolve_floor(admin_name).usernames self._bindings = dict(source_provider_bindings or {}) + self._home_org = home_org + self._providers = provider_registry @staticmethod def sanitise_username(user_id: str) -> str: @@ -173,6 +245,7 @@ def ensure_account( name: str = "", groups: Sequence[Group] | None = None, keep_stored_groups: bool = False, + email_verified: bool | None = None, ) -> Account: """Create or update shadow account. Non-fatal on HyperDX failures. @@ -187,6 +260,14 @@ def ensure_account( existing account is then judged on its stored groups, which are not rewritten, and no session of it is ended. A first login has none to keep. + ``email_verified`` says whether the IdP vouched for ``email`` and is trusted + for its domain, None where the login cannot tell (the proxy headers). A first + login with a trusted email links to the one account holding it + (:func:`~dfe_engine.auth.identity_links.link_candidates`): at once when an IdP + owns that account, after its password when it is local. A login through a + sign-in linked earlier is recorded on the account it links to, which is what + this returns. + Raises: JitIdentityCollisionError: The asserted subject is in the API-key namespace, or resolved onto a recovery credential or onto an @@ -200,6 +281,12 @@ def ensure_account( logout ends them, so no token issued for it reads or refreshes a session. With ``keep_stored_groups`` neither happens. Nothing else is written. + JitLinkRequiredError: A trusted email matches one local account. Nothing + is written. + JitEmailUntrustedError: A callback login whose email is unverified or + outside the provider's trusted domains. Nothing is written. + JitEmailHeldError: A first callback login that does not link while another + account holds its email (not one its owner set). Nothing is written. Exception: Any other error is the store failing to record the login, never a refusal of the identity. A first login leaves no account. """ @@ -210,11 +297,37 @@ def ensure_account( self._refuse_protected(safe_name, user_id, source_provider) if not VALID_NAME.match(safe_name): raise JitSubjectUnusableError(user_id) + # A callback sign-in passes False when its email is unverified or outside the provider's trusted domains. + if email_verified is False: + audit_jit_login_refused(user_id, source_provider, "email_untrusted") + raise JitEmailUntrustedError(user_id, source_provider) now = datetime.now(UTC).isoformat() wanted_email = email.strip() wanted_name = name.strip() key, existing = self._session_account(safe_name, user_id) + if (existing is not None) and (existing.is_link_record): + self._require_same_identity(existing, user_id, source_provider) + person = self._linked_person(record=existing) + if person is not None: + self._require_reached( + account=person, source_provider=source_provider, user_id=user_id + ) + return self._reconcile_linked( + email=wanted_email, + groups=groups, + keep_stored_groups=keep_stored_groups, + now=now, + oidc_groups=oidc_groups, + person=person, + record=existing, + source_provider=source_provider, + user_id=user_id, + ) + # Its account is gone or no longer lists it, so the sign-in starts again as a first login. + logger.warning("JIT removed a link record nothing lists", key=key, user_id=user_id) + self._accounts.delete(key) + existing = None if existing is not None: self._require_same_identity(existing, user_id, source_provider) self._require_available(existing, user_id, source_provider) @@ -227,7 +340,15 @@ def ensure_account( updates["groups"] = oidc_groups audit_jit_groups_updated(user_id, added, removed) listed = self._groups.list() if groups is None else groups - if not self._holds_a_role(key, oidc_groups, existing.source_provider, listed): + holds_a_role = self._holds_a_role( + key, + oidc_groups, + existing.source_provider, + listed, + identities=existing.identities, + org=existing.org, + ) + if not holds_a_role: # Groups the directory never answered for say nothing new, so no session ends on them. if not keep_stored_groups: if updates: @@ -241,13 +362,37 @@ def ensure_account( updates.update(last_login_at=now, oidc_id=source_provider, subject=user_id) if wanted_email and existing.email != wanted_email: updates["email"] = wanted_email + # A new address nobody vouched for must not keep the old one's proof. + updates["email_verified"] = bool(email_verified) + elif wanted_email and email_verified is not None: + updates["email_verified"] = email_verified if wanted_name and existing.name != wanted_name: updates["name"] = wanted_name return self._accounts.update(key, allow_protected=False, **updates) listed = self._groups.list() if groups is None else groups - # The race branch below reconciles an account under this name, so this covers it too. - if not self._holds_a_role(safe_name, oidc_groups, source_provider, listed): + if email_verified and wanted_email: + linked = self._link_on_first_login( + email=wanted_email, + listed=listed, + now=now, + oidc_groups=oidc_groups, + safe_name=safe_name, + source_provider=source_provider, + user_id=user_id, + ) + if linked is not None: + return linked + if email_verified is not None: + self._refuse_held_email( + email=wanted_email, source_provider=source_provider, user_id=user_id + ) + + org = self._provider_org(provider=source_provider) + # The race branch below reconciles an account under this name, so this covers it too. An org's provider lands it as that org's viewer. + if (not (org)) and ( + not (self._holds_a_role(safe_name, oidc_groups, source_provider, listed)) + ): self._refuse_without_role(user_id, source_provider) # First login -- create shadow account @@ -267,6 +412,21 @@ def ensure_account( # Nothing holds the name, so this is a store fault, not a race. raise self._require_same_identity(raced, user_id, source_provider) + if raced.is_link_record: + person = self._linked_person(record=raced) + if person is None: + raise + return self._reconcile_linked( + email=wanted_email, + groups=listed, + keep_stored_groups=keep_stored_groups, + now=now, + oidc_groups=oidc_groups, + person=person, + record=raced, + source_provider=source_provider, + user_id=user_id, + ) self._require_available(raced, user_id, source_provider) race_updates: dict[str, object] = { "last_login_at": now, @@ -277,6 +437,7 @@ def ensure_account( race_updates["groups"] = oidc_groups if wanted_email: race_updates["email"] = wanted_email + race_updates["email_verified"] = bool(email_verified) if wanted_name: race_updates["name"] = wanted_name return self._accounts.update(safe_name, allow_protected=False, **race_updates) @@ -287,9 +448,13 @@ def ensure_account( external=True, source_provider=source_provider, oidc_id=source_provider, + org=org, subject=user_id, last_login_at=now, + email_verified=bool(email_verified and wanted_email), ) + if org: + self._groups.add_member(f"{org}-viewers", safe_name) except Exception: # Unstamped, the account reads as a local one and refuses this identity at every login. discard_created(self._accounts, created) @@ -327,6 +492,276 @@ def ensure_account( return stamped + def complete_link( + self, *, groups: Sequence[Group] | None = None, ticket: LinkTicket + ) -> Account: + """Link the ticket's sign-in to its local account, whose password the caller has checked, and return that account. + + The account must still be the one account the ticket's email links to, and still local. A sign-in that already links to it is recorded as a login, so a repeated redemption gets the same session. Otherwise ``JitIdentityCollisionError`` (``link_stale``), and an unavailable account or one still holding no role refuses as :meth:`ensure_account` does. Nothing is written on a refusal. + """ + source_provider = ticket.provider + user_id = ticket.subject + safe_name = self.sanitise_username(user_id) + self._refuse_protected(safe_name, user_id, source_provider) + if not VALID_NAME.match(safe_name): + raise JitSubjectUnusableError(user_id) + now = datetime.now(UTC).isoformat() + listed = self._groups.list() if groups is None else groups + + _key, existing = self._session_account(safe_name, user_id) + if existing is not None: + self._require_same_identity(existing, user_id, source_provider) + person = self._linked_person(record=existing) if existing.is_link_record else None + if (person is None) or (person.username != ticket.account): + self._refuse_stale_link(source_provider=source_provider, user_id=user_id) + self._require_reached(account=person, source_provider=source_provider, user_id=user_id) + return self._reconcile_linked( + email=ticket.email, + groups=listed, + keep_stored_groups=ticket.groups_unresolved, + now=now, + oidc_groups=ticket.groups, + person=person, + record=existing, + source_provider=source_provider, + user_id=user_id, + ) + + candidates = self._link_candidates(email=ticket.email, provider=source_provider) + names = [candidate.username for candidate in candidates] + if (names != [ticket.account]) or (candidates[0].source_provider): + self._refuse_stale_link(source_provider=source_provider, user_id=user_id) + entry = LinkedIdentity( + email=ticket.email, + groups=ticket.groups, + key=safe_name, + last_login_at=now, + linked_at=now, + provider=source_provider, + subject=user_id, + ) + return self._link(entry=entry, listed=listed, method="password", person=candidates[0]) + + def _link( + self, *, entry: LinkedIdentity, listed: Sequence[Group], method: str, person: Account + ) -> Account: + """Link *entry*'s sign-in to *person*: the link record at its name, then the entry on *person*. + + Refused, with nothing written, when *person* is unavailable or would still hold no role. A record written before the entry fails is removed, and an unlisted record binds no session meanwhile. + """ + self._require_linkable(entry=entry, listed=listed, person=person) + try: + created = self._accounts.create(password="", username=entry.key) + except AccountExistsError: + # Another replica linked the same sign-in first: its session is the same account's. + raced = self._accounts.get(entry.key) + if (raced is None) or (raced.linked_to != person.username): + raise + self._require_same_identity(raced, entry.subject, entry.provider) + return self._accounts.get(person.username) or person + try: + self._accounts.update( + entry.key, + external=True, + last_login_at=entry.last_login_at, + linked_to=person.username, + oidc_id=entry.provider, + # Unlinked, the record becomes an account of its own and stays in the person's org. + org=person.org, + source_provider=entry.provider, + subject=entry.subject, + ) + current = self._accounts.get(person.username) or person + # oidc_id stays the person's own: deleting a provider soft-deletes the accounts it names. + linked = self._accounts.update( + person.username, + identities=with_identity(entry=entry, identities=current.identities), + last_login_at=entry.last_login_at, + ) + except Exception: + discard_created(self._accounts, created) + raise + audit_identity_linked( + account=person.username, + method=method, + source_provider=entry.provider, + user_id=entry.subject, + ) + return linked + + def _link_on_first_login( + self, + *, + email: str, + listed: Sequence[Group], + now: str, + oidc_groups: list[str], + safe_name: str, + source_provider: str, + user_id: str, + ) -> Account | None: + """Link a first login to the one account its trusted email matches, or None to give it its own. + + An account an IdP owns is linked at once. A local one raises ``JitLinkRequiredError`` once it is known to be available and to hold a role with this sign-in. + """ + candidates = self._link_candidates(email=email, provider=source_provider) + if not (candidates): + return None + if len(candidates) > 1: + audit_identity_link_skipped( + reason="ambiguous_email", source_provider=source_provider, user_id=user_id + ) + return None + person = candidates[0] + entry = LinkedIdentity( + email=email, + groups=oidc_groups, + key=safe_name, + last_login_at=now, + linked_at=now, + provider=source_provider, + subject=user_id, + ) + if person.source_provider: + return self._link(entry=entry, listed=listed, method="verified_email", person=person) + self._require_linkable(entry=entry, listed=listed, person=person) + raise JitLinkRequiredError( + account=person.username, source_provider=source_provider, user_id=user_id + ) + + def _link_candidates(self, *, email: str, provider: str) -> list[Account]: + """The accounts a sign-in through *provider* may link to by *email*, each one it reaches (:meth:`_reaches`).""" + candidates = link_candidates( + accounts=self._accounts.scan(), email=email, protected=self._protected + ) + return [ + candidate + for candidate in candidates + if self._reaches(account=candidate, provider=provider) + ] + + def _require_reached(self, *, account: Account, source_provider: str, user_id: str) -> None: + """Refuse ``other_org`` when a sign-in through *source_provider* may not land on *account* (:meth:`_reaches`).""" + if self._reaches(account=account, provider=source_provider): + return + audit_jit_login_refused(user_id, source_provider, "other_org") + raise JitIdentityCollisionError(user_id, source_provider, "other_org") + + def _reaches(self, *, account: Account, provider: str) -> bool: + """Whether a sign-in through *provider* may land on *account*: an org's provider on that org's accounts, a platform provider on root and your-org accounts.""" + org = self._provider_org(provider=provider) + if org: + return account.org == org + home = (self._home_org() if self._home_org is not None else None) or "" + return account.org in ("", home) + + def _provider_org(self, *, provider: str) -> str: + """The org whose provider *provider* is, empty for a platform provider or a name no provider holds.""" + found = self._providers.get(provider) if self._providers is not None else None + return found.org if found is not None else "" + + def _linked_person(self, *, record: Account) -> Account | None: + """The account the link record *record* binds, never a recovery credential.""" + person = linked_person(record=record, store=self._accounts) + if (person is None) or (person.username in self._protected): + return None + return person + + def _reconcile_linked( + self, + *, + email: str, + groups: Sequence[Group] | None, + keep_stored_groups: bool, + now: str, + oidc_groups: list[str], + person: Account, + record: Account, + source_provider: str, + user_id: str, + ) -> Account: + """Record a linked sign-in's login on the identity entry of *person*, never on *person*'s own groups. + + Refused as :meth:`ensure_account` refuses an existing account: unavailable, or left holding no role, which also ends every session of *person* unless the directory gave no answer. + """ + self._require_available(person, user_id, source_provider) + entry = linked_identity(account=person, key=record.username) + if entry is None: + raise KeyError(record.username) + asserted = list(entry.groups) if keep_stored_groups else list(oidc_groups) + current = entry.model_copy( + update={"email": email or entry.email, "groups": asserted, "last_login_at": now} + ) + identities = with_identity(entry=current, identities=person.identities) + listed = self._groups.list() if groups is None else groups + holds_a_role = self._holds_a_role( + person.username, + person.groups, + person.source_provider, + listed, + identities=identities, + org=person.org, + ) + if not (holds_a_role): + if not (keep_stored_groups): + self._accounts.update(person.username, identities=identities) + # A token issued before the refusal must neither read nor refresh a session. + self._accounts.end_sessions(person.username) + audit_account_change( + user_id, person.username, "sessions_ended", {"reason": "no_role_granted"} + ) + self._refuse_without_role(user_id, source_provider) + if set(entry.groups) != set(asserted): + added = [g for g in asserted if g not in entry.groups] + removed = [g for g in entry.groups if g not in asserted] + audit_jit_groups_updated(user_id, added, removed) + # Re-read so an unlink or another sign-in's write made during this login is kept, not overwritten. + fresh = self._accounts.get(person.username) + if (fresh is None) or (linked_identity(account=fresh, key=record.username) is None): + self._refuse_stale_link(source_provider=source_provider, user_id=user_id) + identities = with_identity(entry=current, identities=fresh.identities) + return self._accounts.update(person.username, identities=identities, last_login_at=now) + + @staticmethod + def _refuse_stale_link(*, source_provider: str, user_id: str) -> NoReturn: + """Refuse a password link whose account or sign-in name changed after its ticket was issued.""" + audit_jit_login_refused(user_id, source_provider, "link_stale") + raise JitIdentityCollisionError(user_id, source_provider, "link_stale") + + def _require_linkable( + self, *, entry: LinkedIdentity, listed: Sequence[Group], person: Account + ) -> None: + """Refuse linking *entry* to *person* while *person* is disabled or blocked, or would hold no role with it.""" + self._require_available(person, entry.subject, entry.provider) + identities = with_identity(entry=entry, identities=person.identities) + holds_a_role = self._holds_a_role( + person.username, + person.groups, + person.source_provider, + listed, + identities=identities, + org=person.org, + ) + if not (holds_a_role): + self._refuse_without_role(entry.subject, entry.provider) + + def _refuse_held_email(self, *, email: str, source_provider: str, user_id: str) -> None: + """Refuse a first sign-in whose email another account holds, unless that account's owner set the email themselves. + + A self-set email never blocks, so nobody can lock another person out of their identity provider by claiming their address. + """ + holders = [ + holder + for holder in email_holders( + accounts=self._accounts.scan(), email=email, protected=self._protected + ) + if holder.source_provider or holder.email_verified is not False + ] + if not (holders): + return + audit_jit_login_refused(user_id, source_provider, "email_held") + raise JitEmailHeldError(user_id, source_provider) + def _refuse_protected(self, safe_name: str, user_id: str, source_provider: str) -> None: """Refuse any assertion resolving onto a recovery credential. @@ -369,12 +804,14 @@ def _require_same_identity(self, existing: Account, user_id: str, source_provide Raises: JitIdentityCollisionError: The account is local, another provider's, - or another subject's. + another subject's, or outside the provider's reach (:meth:`_reaches`). """ if not self._may_adopt(existing, source_provider): reason = "provider_mismatch" if existing.source_provider else "local_account" elif existing.subject and existing.subject != user_id: reason = "subject_mismatch" + elif not (self._reaches(account=existing, provider=source_provider)): + reason = "other_org" else: return audit_jit_login_refused(user_id, source_provider, reason) @@ -408,7 +845,14 @@ def _require_available(existing: Account, user_id: str, source_provider: str) -> raise JitAccountUnavailableError(user_id, reason) def _holds_a_role( - self, username: str, oidc_groups: list[str], stamp: str, groups: Sequence[Group] + self, + username: str, + oidc_groups: list[str], + stamp: str, + groups: Sequence[Group], + *, + identities: Sequence[LinkedIdentity] = (), + org: str = "", ) -> bool: """Whether the account *username*, stamped *stamp*, holds a role after this login. @@ -417,9 +861,15 @@ def _holds_a_role( answers for. A SCIM account adopted through a binding is stamped ``scim``, not the provider signing in, so the check takes the stamp the account carries. A linked group carrying no role, as the group sync creates them, - grants nothing, so it admits nothing either. *groups* is every stored group. + grants nothing, so it admits nothing either. Nor does a group an account of + *org* may not hold (:func:`org_role_groups_held`). *groups* is every stored + group, and *identities* the sign-ins linked to the account. """ - held = groups_held_by(username, oidc_groups, stamp, groups, bindings=self._bindings) + held = groups_held_by( + username, oidc_groups, stamp, groups, bindings=self._bindings, identities=identities + ) + home = (self._home_org() if self._home_org is not None else None) or "" + held = org_role_groups_held(account_org=org, groups=held, home_org=home) return any(group.roles for group in held) @staticmethod diff --git a/src/dfe_engine/auth/jwt_authority.py b/src/dfe_engine/auth/jwt_authority.py index 984cd1b75..edea89c9e 100644 --- a/src/dfe_engine/auth/jwt_authority.py +++ b/src/dfe_engine/auth/jwt_authority.py @@ -239,16 +239,19 @@ def mint_machine_token( expires_delta=timedelta(seconds=ttl_seconds), ) - def verify(self, token: str) -> dict[str, Any]: - """Verify signature + issuer + expiry. Raises ``InvalidTokenError`` on any failure.""" - header = jwt.get_unverified_header(token) - kid = header.get("kid") + def _verify_key(self, token: str) -> EllipticCurvePublicKey: + """The trusted public key the token's ``kid`` names, else ``InvalidTokenError``.""" + kid = jwt.get_unverified_header(token).get("kid") key = self._verify_keys.get(kid) if kid else None if key is None: raise InvalidTokenError(f"unknown or missing key id (kid={kid!r})") + return key + + def verify(self, token: str) -> dict[str, Any]: + """Verify signature + issuer + expiry. Raises ``InvalidTokenError`` on any failure.""" claims = jwt.decode( token, - key, + self._verify_key(token=token), algorithms=[self._alg], issuer=self._issuer, leeway=_CLOCK_SKEW_SECONDS, @@ -260,6 +263,18 @@ def verify(self, token: str) -> dict[str, Any]: raise InvalidTokenError(f"token audience {claims['aud']!r} is not for this issuer") return claims + def verify_for(self, token: str, *, audience: str) -> dict[str, Any]: + """Verify a token this engine minted for *audience*: signature, issuer, expiry and that audience, else ``InvalidTokenError``.""" + return jwt.decode( + token, + self._verify_key(token=token), + algorithms=[self._alg], + audience=audience, + issuer=self._issuer, + leeway=_CLOCK_SKEW_SECONDS, + options={"require": ["aud", "exp", "iss"]}, + ) + def jwks(self) -> dict[str, list[dict[str, str]]]: """The public JWK Set for ``/.well-known/jwks.json`` (public halves only).""" return {"keys": [_public_jwk(pub, self._alg) for pub in self._verify_keys.values()]} diff --git a/src/dfe_engine/auth/local_provider.py b/src/dfe_engine/auth/local_provider.py index 779056e21..8827b419b 100644 --- a/src/dfe_engine/auth/local_provider.py +++ b/src/dfe_engine/auth/local_provider.py @@ -23,6 +23,7 @@ from dfe_engine.auth.accounts import Account, AccountStore from dfe_engine.auth.groups import GroupStore +from dfe_engine.auth.identity_links import link_candidates from dfe_engine.auth.models import AuthContext, AuthenticationError @@ -58,6 +59,24 @@ def __init__( self._accounts = account_store self._groups = group_store + def account_name(self, identifier: str) -> str: + """The account name *identifier* signs in as: itself, or for an email the one local account vouched for holding it. + + An email no local account holds, or several do, comes back unchanged and so fails as an unknown name would. An email the owner set themselves never counts, as in linking. + """ + if ("@" not in identifier) or (self._accounts.get(identifier) is not None): + return identifier + holders = [ + account + for account in link_candidates( + accounts=self._accounts.scan(), + email=identifier, + protected=self._accounts.protected.usernames, + ) + if not (account.source_provider) + ] + return holders[0].username if len(holders) == 1 else identifier + def authenticate( self, username: str, diff --git a/src/dfe_engine/auth/membership.py b/src/dfe_engine/auth/membership.py index 49c6eace0..f4a427d4e 100644 --- a/src/dfe_engine/auth/membership.py +++ b/src/dfe_engine/auth/membership.py @@ -10,7 +10,7 @@ from collections.abc import Collection, Iterable, Mapping -from dfe_engine.auth.accounts import Account, AccountStore +from dfe_engine.auth.accounts import Account, AccountStore, LinkedIdentity from dfe_engine.auth.groups import Group, GroupStore @@ -71,7 +71,8 @@ def groups_held( The group files are the authority, so a member removed there loses the group even while the account's own list still names it. An IdP-owned account's own list is what its IdP asserts, and holds only the groups those identifiers are linked to - (:func:`linked_groups`), beside any an operator added it to by hand. + (:func:`linked_groups`), beside any an operator added it to by hand. Each IdP + sign-in linked to the account adds the groups its own assertion links to. Args: account: The account. @@ -82,7 +83,12 @@ def groups_held( Sorted group names. """ held = groups_held_by( - account.username, account.groups, account.source_provider, groups, bindings=bindings + account.username, + account.groups, + account.source_provider, + groups, + bindings=bindings, + identities=account.identities, ) return [group.name for group in held] @@ -94,6 +100,7 @@ def groups_held_by( groups: Iterable[Group], *, bindings: Mapping[str, str], + identities: Iterable[LinkedIdentity] = (), ) -> list[Group]: """The stored groups an account with these fields holds, the lookup :func:`groups_held` makes. @@ -107,15 +114,19 @@ def groups_held_by( linked group. groups: Every stored group, listed once by the caller. bindings: ``auth.source_provider_bindings``. + identities: The IdP sign-ins linked to the account, each linking groups by + its own assertion under its own provider. Returns: The held groups, sorted by name. """ listed = list(groups) held = {group.name: group for group in listed if username in group.members} - if stamp: - providers = linked_providers([stamp], bindings) - held.update((group.name, group) for group in linked_groups(asserted, listed, providers)) + assertions = [(stamp, asserted)] if stamp else [] + assertions.extend((identity.provider, identity.groups) for identity in identities) + for provider, identifiers in assertions: + providers = linked_providers([provider], bindings) + held.update((group.name, group) for group in linked_groups(identifiers, listed, providers)) return [held[name] for name in sorted(held)] diff --git a/src/dfe_engine/auth/models.py b/src/dfe_engine/auth/models.py index 1e86029d0..ae786c90a 100644 --- a/src/dfe_engine/auth/models.py +++ b/src/dfe_engine/auth/models.py @@ -86,22 +86,25 @@ class ScopedGrant(BaseModel): # The tenant role: holding it never unfences a group or a caller from its org. ORG_VIEWER_ROLE = "org_viewer" +# An org's administrator, bound only at that org's scope: a system group grants nothing through it. +ORG_ADMIN_ROLE = "org_admin" + def is_platform_role(role: str, role_config: RoleConfig) -> bool: """Whether a system-scope grant of ``role`` may read across orgs. Only a role the definitions declare and do not mark ``scoped`` may. ``org_viewer`` - never may, whatever a deployment's definitions say, and an undefined role grants - nothing, so it unfences nothing either. + and ``org_admin`` never may, whatever a deployment's definitions say, and an + undefined role grants nothing, so it unfences nothing either. Args: role: The role name. role_config: The role definitions ``authorize()`` reads. Returns: - True for a declared, unscoped role other than ``org_viewer``. + True for a declared, unscoped role other than ``org_viewer`` and ``org_admin``. """ - if role == ORG_VIEWER_ROLE: + if role in (ORG_ADMIN_ROLE, ORG_VIEWER_ROLE): return False definition = role_config.roles.get(role) return definition is not None and not definition.scoped diff --git a/src/dfe_engine/auth/oidc/models.py b/src/dfe_engine/auth/oidc/models.py index ffb1509b5..117afd984 100644 --- a/src/dfe_engine/auth/oidc/models.py +++ b/src/dfe_engine/auth/oidc/models.py @@ -23,9 +23,11 @@ api -- Groups fetched from the provider's admin API on a schedule. """ +import re +from collections.abc import Iterable from typing import Annotated, Literal, Self, get_args -from pydantic import BaseModel, Field, WithJsonSchema, model_validator +from pydantic import BaseModel, Field, WithJsonSchema, field_validator, model_validator # --------------------------------------------------------------------------- # Group sync status @@ -78,6 +80,24 @@ # okta and generic still default to that set, so only these types fail a login on it. _LEGACY_REPAIRED_TYPES = frozenset({"entra_id", "google"}) +_EMAIL_DOMAIN = re.compile(r"^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9-]{2,63}\Z") + + +def _folded_domains(*, domains: Iterable[str]) -> list[str]: + """The domains stripped and casefolded, blanks and repeats dropped, in first-seen order.""" + folded = (domain.strip().casefold() for domain in domains) + return list(dict.fromkeys(domain for domain in folded if domain)) + + +def checked_email_domains(*, domains: Iterable[str]) -> list[str]: + """The domains folded, refused unless each is a bare domain such as ``corp.com``.""" + folded = _folded_domains(domains=domains) + refused = [domain for domain in folded if not (_EMAIL_DOMAIN.match(domain))] + if refused: + names = ", ".join(repr(domain) for domain in refused) + raise ValueError(f"must be bare domains such as 'corp.com', not {names}") + return folded + class GroupResolutionConfig(BaseModel): """Configuration for how group membership is resolved from a provider. @@ -176,6 +196,9 @@ class OIDCProvider(BaseModel): type: _ProviderType = "generic" """Provider implementation type.""" + org: str = "" + """The org whose provider this is: its sign-ins land in that org as viewers and link only to that org's accounts. Empty is a platform provider.""" + enabled: bool = True """Whether this provider is active.""" @@ -215,6 +238,11 @@ class OIDCProvider(BaseModel): groups: GroupResolutionConfig = Field(default_factory=GroupResolutionConfig) """Group resolution configuration for this provider.""" + trusted_email_domains: list[str] = Field(default_factory=list) + """Email domains this provider vouches for, so a first sign-in can link to the account holding its email. + + The email must also be verified (``email_verified``, or ``xms_edov`` from Entra). Empty links nothing.""" + created_at: str = "" """ISO 8601 UTC timestamp of initial creation.""" @@ -229,6 +257,12 @@ class OIDCProvider(BaseModel): sync_error: str = "" """Error message from the most recent failed sync, if any.""" + @field_validator("trusted_email_domains") + @classmethod + def _fold_trusted_email_domains(cls, value: list[str]) -> list[str]: + """Store the domains casefolded and once each, so a sign-in's domain matches by equality.""" + return _folded_domains(domains=value) + @model_validator(mode="after") def _fill_default_scopes(self) -> Self: """Give a provider with no scopes configured the ones its type needs. diff --git a/src/dfe_engine/auth/oidc/rp.py b/src/dfe_engine/auth/oidc/rp.py index 394bc7155..175399e53 100644 --- a/src/dfe_engine/auth/oidc/rp.py +++ b/src/dfe_engine/auth/oidc/rp.py @@ -47,6 +47,9 @@ # Claims a userinfo response may fill. Groups stay ID-token-only because they decide roles. _USERINFO_FILL_CLAIMS = ("email", "name", "preferred_username") +# Claims that vouch for ``email``: the OIDC standard one and Entra's optional domain-owner claim. +_EMAIL_PROOF_CLAIMS = ("email_verified", "xms_edov") + DIRECTORY_GROUPS_FALLBACKS = "auth_oidc_login_directory_fallbacks_total" DIRECTORY_GROUPS_REFUSALS = "auth_oidc_login_directory_refusals_total" @@ -116,6 +119,9 @@ class NormalizedIdentity(BaseModel): email: str = "" """The ``email`` claim, else the first of ``preferred_username`` and ``upn`` that holds an ``@``, else empty.""" + email_verified: bool = False + """The IdP vouches for ``email``: it came from the ``email`` claim with ``email_verified`` or ``xms_edov`` true.""" + name: str = "" """The display name: the ``name`` claim, else ``preferred_username``, else empty.""" @@ -130,6 +136,9 @@ class NormalizedIdentity(BaseModel): API. A consumer that only reads ``groups`` need not care - this is a diagnostic flag so the enrichment path is observable in logs and tests.""" + auth_time: int | None = None + """The ID token's ``auth_time``: when the person last entered credentials at the IdP, in epoch seconds.""" + groups_unresolved: bool = False """True when the directory gave no answer and the token carried no groups. @@ -179,13 +188,26 @@ def _display_name(*, claims: dict[str, Any]) -> str: ) -def needs_userinfo(*, claims: dict[str, Any]) -> bool: - """Whether the ID token is too thin to name the user: no display name, or no email. +def _vouched(*, claims: dict[str, Any], name: str) -> bool: + """Whether the claim is true, as a JSON boolean or the string ``"true"`` some IdPs send.""" + value = claims.get(name) + return (value is True) or (isinstance(value, str) and value.strip().casefold() == "true") + + +def needs_userinfo(*, claims: dict[str, Any], wants_email_proof: bool = False) -> bool: + """Whether the ID token is too thin: no display name, no email, or no email proof where one is wanted. A token with a name and no email would otherwise skip userinfo, and the email would fall back to the username claims even where the IdP holds the address. + Okta's authorization-code ID token carries no ``email_verified``, which only + its userinfo answers, so a provider trusted for email domains asks for it. """ - return not (_display_name(claims=claims)) or not (_claim_text(claims=claims, name="email")) + unproved = (wants_email_proof) and not any(claim in claims for claim in _EMAIL_PROOF_CLAIMS) + return ( + not (_display_name(claims=claims)) + or not (_claim_text(claims=claims, name="email")) + or (unproved) + ) def extract_identity( @@ -198,7 +220,8 @@ def extract_identity( ``preferred_username`` and then ``upn``, taking the first that holds an ``@``: Entra emits no ``email`` for a cloud-only user with no mailbox, and its UPN is an address, while a bare username such as Keycloak's is not one and leaves the - email blank. The display name is ``name``, falling back to ``preferred_username``. Groups + email blank. ``email_verified`` holds only for an address from the ``email`` claim + itself, never one of those fallbacks. The display name is ``name``, falling back to ``preferred_username``. Groups come from the claim named by ``provider.groups.claim_name`` (default ``groups``), matching the token_claim resolution mode used across the DFE auth paths. A provider in ``manual`` mode yields no groups at all, because its users' membership is managed in dfe-engine and the token grants nothing. @@ -213,12 +236,14 @@ def extract_identity( A NormalizedIdentity with subject, email, and groups. """ subject = str(userinfo_claims.get("sub") or "") - email = str(userinfo_claims.get("email") or "") + claimed_email = str(userinfo_claims.get("email") or "") + email = claimed_email if not email: usernames = ( str(userinfo_claims.get(claim) or "") for claim in ("preferred_username", "upn") ) email = next((value for value in usernames if "@" in value), "") + vouched = any(_vouched(claims=userinfo_claims, name=claim) for claim in _EMAIL_PROOF_CLAIMS) name = _display_name(claims=userinfo_claims) groups = [] overflowed = False @@ -226,8 +251,20 @@ def extract_identity( claim_name = provider.groups.claim_name or "groups" groups = _coerce_groups(raw=userinfo_claims.get(claim_name)) overflowed = _has_group_overage(claim_name=claim_name, claims=userinfo_claims) + raw_auth_time = userinfo_claims.get("auth_time") + auth_time = ( + int(raw_auth_time) + if (isinstance(raw_auth_time, (int, float))) and (not isinstance(raw_auth_time, bool)) + else None + ) return NormalizedIdentity( - email=email, groups=groups, groups_overflowed=overflowed, name=name, subject=subject + auth_time=auth_time, + email=email, + email_verified=bool(claimed_email) and vouched, + groups=groups, + groups_overflowed=overflowed, + name=name, + subject=subject, ) @@ -246,7 +283,10 @@ def merge_userinfo_claims( """Fill the profile claims the ID token left blank from the userinfo response. Only ``email``, ``name`` and ``preferred_username`` are filled, and only where - the ID token has no non-blank value. A userinfo response for another subject + the ID token has no non-blank value. An ``email`` filled from userinfo brings + that response's ``email_verified`` and ``xms_edov`` with it, since each vouches + only for the address it arrived with. Where both name the same address, userinfo + fills a proof the ID token lacks. A userinfo response for another subject raises UserinfoSubjectMismatchError, because OIDC Core 5.3.4 forbids using it. """ if userinfo_claims.get("sub") != id_token_claims.get("sub"): @@ -256,6 +296,18 @@ def merge_userinfo_claims( value = _claim_text(claims=userinfo_claims, name=claim) if value and not (_claim_text(claims=id_token_claims, name=claim)): merged[claim] = value + token_email = _claim_text(claims=id_token_claims, name="email") + info_email = _claim_text(claims=userinfo_claims, name="email") + same_email = bool(token_email) and token_email.casefold() == info_email.casefold() + if merged.get("email") != id_token_claims.get("email"): + for claim in _EMAIL_PROOF_CLAIMS: + merged.pop(claim, None) + if claim in userinfo_claims: + merged[claim] = userinfo_claims[claim] + elif same_email: + for claim in _EMAIL_PROOF_CLAIMS: + if (claim in userinfo_claims) and (claim not in id_token_claims): + merged[claim] = userinfo_claims[claim] return merged @@ -367,15 +419,17 @@ async def login_authorization_url( provider_name: str, request: Request, redirect_uri: str, + **params: str | int, ) -> str: """Begin the auth-code flow and return the IdP authorize URL (SPA-friendly). Same session state as ``login_redirect`` (state + nonce in ``request.session``), but returns the URL for the browser to navigate explicitly--``fetch()`` cannot reliably follow a 302 to a cross-origin IdP. + *params* join the authorize request, such as ``prompt`` and ``max_age``. """ client = self._client(provider_name) - rv = await client.create_authorization_url(redirect_uri) + rv = await client.create_authorization_url(redirect_uri, **params) await client.save_authorize_data(request, redirect_uri=redirect_uri, **rv) return str(rv["url"]) @@ -421,7 +475,7 @@ async def _identity_from_token( """The identity a validated token response names, its groups read from the directory where the token carries none.""" # Authlib parses + validates the id_token and exposes its claims here. userinfo = dict(token.get("userinfo") or {}) - if needs_userinfo(claims=userinfo): + if needs_userinfo(claims=userinfo, wants_email_proof=bool(provider.trusted_email_domains)): userinfo = await fill_from_userinfo_endpoint( claims=userinfo, client=client, issuer=provider.issuer, token=token ) diff --git a/src/dfe_engine/auth/reauth.py b/src/dfe_engine/auth/reauth.py new file mode 100644 index 000000000..a5ef30c08 --- /dev/null +++ b/src/dfe_engine/auth/reauth.py @@ -0,0 +1,52 @@ +# Project: dfe-engine +# File: auth/reauth.py +# Purpose: The grant a caller earns by proving it is still itself, which every access change needs +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""The grant a caller earns by proving it is still itself, which every access change needs.""" + +from datetime import timedelta +from typing import Literal + +from jwt import InvalidTokenError + +from dfe_engine.auth.jwt_authority import JwtAuthority + +REAUTH_AUDIENCE = "dfe-engine-account-reauth" +REAUTH_HEADER = "X-DFE-Reauth" +REAUTH_LIFETIME = timedelta(minutes=10) + +type ReauthKind = Literal["account", "api_key", "group", "provider", "role"] +REAUTH_KINDS: tuple[ReauthKind, ...] = ("account", "api_key", "group", "provider", "role") + +# Store names hold no colon, so a prefixed target never names an account or another kind. +_TARGET_PREFIXES: dict[str, str] = { + "account": "", + "api_key": "api-key:", + "group": "group:", + "provider": "provider:", + "role": "role:", +} + + +def grant_target(*, kind: ReauthKind, name: str) -> str: + """The grant target for changing the *kind* called *name*.""" + return f"{_TARGET_PREFIXES[kind]}{name}" + + +def grant_allows(*, authority: JwtAuthority, caller: str, target: str, token: str) -> bool: + """Whether *token* is a live grant this engine signed for *caller* to change *target*.""" + try: + claims = authority.verify_for(audience=REAUTH_AUDIENCE, token=token) + except InvalidTokenError: + return False + return (claims.get("sub") == caller) and (claims.get("target") == target) + + +def mint_reauth_grant(*, authority: JwtAuthority, caller: str, target: str) -> str: + """Sign a grant letting *caller* change *target* for ``REAUTH_LIFETIME``.""" + claims = {"aud": REAUTH_AUDIENCE, "sub": caller, "target": target} + return authority.sign(claims=claims, expires_delta=REAUTH_LIFETIME) diff --git a/src/dfe_engine/auth/resources/roles.yaml b/src/dfe_engine/auth/resources/roles.yaml index 586c603db..71419a80f 100644 --- a/src/dfe_engine/auth/resources/roles.yaml +++ b/src/dfe_engine/auth/resources/roles.yaml @@ -99,6 +99,22 @@ roles: - "service:read" - "org:read" - "usage:read" + org_admin: + description: "Administers one org's accounts and identity providers, holding an org viewer's reads. Bound only at an org's scope" + resource_type: core + permissions: + - "query:execute" + - "source:read" + - "sampler:read" + - "dashboard:read" + - "usage:read" + - "account:read" + - "account:write" + - "account:delete" + - "accounts:reset_password" + - "oidc:read" + - "oidc:write" + - "oidc:delete" org_viewer: description: "Org-restricted data viewer" resource_type: core diff --git a/src/dfe_engine/orgs/lifecycle.py b/src/dfe_engine/orgs/lifecycle.py index f52ee6fbd..06767d046 100644 --- a/src/dfe_engine/orgs/lifecycle.py +++ b/src/dfe_engine/orgs/lifecycle.py @@ -28,8 +28,6 @@ org = await manager.create_org("acme", org_ids=["acme"], admin_id="admin") """ -from __future__ import annotations - from typing import TYPE_CHECKING from dfe_engine.auth.audit import ( @@ -39,8 +37,10 @@ ) from dfe_engine.orgs.models import Org from dfe_engine.orgs.registry import OrgRegistry +from dfe_engine.orgs.role_groups import drop_org_role_groups, ensure_org_role_groups if TYPE_CHECKING: + from dfe_engine.auth.groups import GroupStore from dfe_engine.hyperdx.client import HyperDXClient @@ -57,9 +57,11 @@ def __init__( self, registry: OrgRegistry, hyperdx_client: HyperDXClient | None = None, + group_store: GroupStore | None = None, ) -> None: self._registry = registry self._hdx = hyperdx_client + self._groups = group_store # ------------------------------------------------------------------ # Public API @@ -92,6 +94,8 @@ async def create_org( ValueError: If an org with this name already exists. """ org = self._registry.create(name, org_ids=org_ids, display_name=display_name) + if self._groups is not None: + ensure_org_role_groups(group_store=self._groups, org=name) org = await self._provision_hyperdx(org) audit_org_change(admin_id=admin_id, org_name=name, change="created") return org @@ -114,6 +118,9 @@ async def delete_org(self, name: str, *, admin_id: str) -> None: if org is None: raise KeyError(name) + # The org's groups go first, so a failed drop leaves the org to retry rather than orphaned groups. + if self._groups is not None: + drop_org_role_groups(group_store=self._groups, org=name) self._registry.delete(name) audit_org_change(admin_id=admin_id, org_name=name, change="deleted") diff --git a/src/dfe_engine/orgs/role_groups.py b/src/dfe_engine/orgs/role_groups.py new file mode 100644 index 000000000..ade13dcfc --- /dev/null +++ b/src/dfe_engine/orgs/role_groups.py @@ -0,0 +1,112 @@ +# Project: dfe-engine +# File: orgs/role_groups.py +# Purpose: The two groups each org carries, its admins and its viewers +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""The two groups each org carries, its admins and its viewers, the only groups an org account may hold.""" + +from collections.abc import Iterable, Mapping + +from dfe_engine.auth.accounts import Account +from dfe_engine.auth.groups import Group, GroupStore +from dfe_engine.auth.membership import groups_held +from dfe_engine.auth.models import ORG_ADMIN_ROLE, ORG_VIEWER_ROLE + +ORG_ROLES = frozenset({ORG_ADMIN_ROLE, ORG_VIEWER_ROLE}) +"""The roles an org account may hold, each only through a group tied to its own org.""" + + +def _group_name(group: Group) -> str: + """The name groups are sorted by.""" + return group.name + + +def _reaches_past(*, group: Group, org: str) -> bool: + """Whether *group* is tied to, or names, an org other than *org*, which puts that org in its holders' org_ids.""" + tied_elsewhere = (bool(group.scope_org)) and (group.scope_org != org) + return (tied_elsewhere) or (any(other != org for other in group.org_ids)) + + +def _refused(*, group: Group, org: str) -> bool: + """Whether an account of *org* may not hold *group*: one reaching past *org*, or granting any role but org roles bound where they reach only *org*.""" + if _reaches_past(group=group, org=org): + return True + if not (group.roles): + return False + # org_viewer is ``scoped``: bound at system scope it reaches only the orgs its group names, so it must name one. org_admin binds only at its org's scope. + system_bound = not (group.scope_org) + unbound = (system_bound) and ((not (group.org_ids)) or (ORG_ADMIN_ROLE in group.roles)) + return (unbound) or (not (set(group.roles) <= ORG_ROLES)) + + +def org_role_breach(*, account_org: str, groups: Iterable[Group], home_org: str) -> str | None: + """The first of *groups*, by name, an account of *account_org* may not hold, else None. + + An account of your org or of none may hold any group. An org account may hold no group reaching another org, and a group with roles only when they are all org roles reaching its own org: org_admin through a group tied to it, org_viewer also through a system group naming it alone. + """ + if (not (account_org)) or (account_org == home_org): + return None + for group in sorted(groups, key=_group_name): + if _refused(group=group, org=account_org): + return group.name + return None + + +def org_role_groups_held( + *, account_org: str, groups: Iterable[Group], home_org: str +) -> list[Group]: + """*groups* less every one an account of *account_org* may not hold, so its grants never reach past its org.""" + if (not (account_org)) or (account_org == home_org): + return list(groups) + return [group for group in groups if not (_refused(group=group, org=account_org))] + + +def usable_org_admins( + *, + accounts: Iterable[Account], + bindings: Mapping[str, str], + groups: list[Group], + org: str, +) -> list[str]: + """The accounts of *org* that can sign in holding its admins group.""" + admins = f"{org}-admins" + return [ + account.username + for account in accounts + if (account.org == org) + and (not (account.is_link_record)) + and (not (account.is_soft_deleted)) + and (account.session_denied() is None) + and (admins in groups_held(account, groups, bindings=bindings)) + ] + + +def org_role_groups(*, org: str) -> dict[str, str]: + """Each of *org*'s two groups by name, with the one role it grants.""" + return {f"{org}-admins": ORG_ADMIN_ROLE, f"{org}-viewers": ORG_VIEWER_ROLE} + + +def ensure_org_role_groups(*, group_store: GroupStore, org: str) -> None: + """Create whichever of *org*'s two groups is missing, tied to *org*.""" + for name, role in org_role_groups(org=org).items(): + if group_store.get(name) is None: + group_store.create( + name, + [role], + description=f"The {role} role in org {org!r}", + scope=f"org:{org}", + ) + + +def drop_org_role_groups(*, group_store: GroupStore, org: str) -> None: + """Delete *org*'s two groups, leaving a same-named group tied to another org or none.""" + for name in org_role_groups(org=org): + group = group_store.get(name) + if (group is not None) and (group.scope_org == org): + # A group with members cannot be deleted, so its members are let go first. + if group.members: + group_store.update(name, members=[]) + group_store.delete(name) diff --git a/src/vulture_whitelist.py b/src/vulture_whitelist.py index 841860db5..7411d9283 100644 --- a/src/vulture_whitelist.py +++ b/src/vulture_whitelist.py @@ -33,8 +33,9 @@ def __getattr__(self, name: str) -> None: ... _.directory_setting, _.editable, _.expires_in, _.explain_queries, _.field_count, _.groups_skipped _.has_schema, _.header_fields, _.highest, _.highest_7d, _.highest_7d_label, _.hunt_count _.json_column, _.json_derived_count, _.landed_in_default, _.mapping_count, _.member_count -_.min_interval_seconds, _.orphaned_groups, _.peak_memory, _.pending_reconcile, _.per_source_apps -_.preferences, _.principal, _.principals, _.processes, _.provider_idle_scaling +_.min_interval_seconds, _.oidc_type, _.org_display_name, _.orphaned_groups, _.peak_memory +_.pending_reconcile, _.per_source_apps, _.preferences, _.principal, _.principals, _.processes +_.provider_idle_scaling _.provider_max_replica_memory_gb, _.provider_min_replica_memory_gb, _.provider_replicas _.python_version, _.queued, _.read_rows, _.relinked, _.requested_fire, _.rule_errors, _.runnable _.runnable_intakes, _.runnable_reason, _.sampled, _.service_account_json, _.services_config_dir @@ -49,7 +50,7 @@ def __getattr__(self, name: str) -> None: ... _.desired_replication_factor, _.estimated_cost, _.estimated_improvement, _.estimated_rows _.existing_schema, _.explain_duration_ms, _.field_mappings, _.has_transform, _.hinted_columns _.hyperdx_source_error, _.hyperdx_source_teams, _.hyperdx_team_api_key_env, _.hyperdx_team_id -_.inherits, _.initial_setup, _.last_completed_at, _.last_login_at, _.match_ratio +_.inherits, _.initial_setup, _.last_completed_at, _.last_login_at, _.linked_at, _.match_ratio _.matched_searchable, _.module_name, _.next_cursor, _.number, _.oidc_providers, _.parser_config _.pending_steps, _.placeholder, _.poll_interval_seconds, _.previous_deployed_versions, _.principal _.projected_per_day, _.proposed_columns, _.proposed_indices, _.proposed_query, _.proposed_schema diff --git a/tests/e2e/test_api_workflow.py b/tests/e2e/test_api_workflow.py index 55191ca4a..f02a91933 100644 --- a/tests/e2e/test_api_workflow.py +++ b/tests/e2e/test_api_workflow.py @@ -234,6 +234,16 @@ def _login(self, client) -> dict[str, str]: ) return {"Authorization": f"Bearer {resp.json()['access_token']}"} + def _granted(self, client, headers: dict[str, str], kind: str, target: str) -> dict[str, str]: + """*headers* with the re-auth grant the admin earns for the *kind* named *target*.""" + resp = client.post( + "/api/v1/auth/reauth", + json={"kind": kind, "password": E2E_ADMIN_PASSWORD, "target": target}, + headers=headers, + ) + assert resp.status_code == 200, resp.text + return {**headers, "X-DFE-Reauth": resp.json()["grant"]} + def test_create_account_assign_group_login(self, e2e_client): headers = self._login(e2e_client) user_password = secrets.token_urlsafe(16) @@ -241,11 +251,12 @@ def test_create_account_assign_group_login(self, e2e_client): resp = e2e_client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "e2e_user", "password": user_password, "email": "e2e_user@example.com", }, - headers=headers, + headers=self._granted(e2e_client, headers, "account", "e2e_user"), ) assert resp.status_code == 201 @@ -253,7 +264,7 @@ def test_create_account_assign_group_login(self, e2e_client): resp = e2e_client.post( "/api/v1/auth/groups/dfe-admins/members", json={"username": "e2e_user"}, - headers=headers, + headers=self._granted(e2e_client, headers, "group", "dfe-admins"), ) assert resp.status_code == 200 diff --git a/tests/fixtures/api_conformance_allow.txt b/tests/fixtures/api_conformance_allow.txt index 643d831a8..00844f8c3 100644 --- a/tests/fixtures/api_conformance_allow.txt +++ b/tests/fixtures/api_conformance_allow.txt @@ -8,6 +8,7 @@ dry-run DELETE /api/v1/apps/{service}/{instance} dry-run DELETE /api/v1/apps/{service}/{instance}/config dry-run DELETE /api/v1/apps/{service}/{instance}/files/{set_name}/{filename} dry-run DELETE /api/v1/auth/accounts/{username} +dry-run DELETE /api/v1/auth/accounts/{username}/identities/{key} dry-run DELETE /api/v1/auth/api-keys/{short_token} dry-run DELETE /api/v1/auth/groups/{name} dry-run DELETE /api/v1/auth/groups/{name}/members/{username} @@ -153,6 +154,7 @@ hierarchy DELETE /api/v1/apps/{service}/{instance} hierarchy DELETE /api/v1/apps/{service}/{instance}/config hierarchy DELETE /api/v1/apps/{service}/{instance}/files/{set_name}/{filename} hierarchy DELETE /api/v1/auth/accounts/{username} +hierarchy DELETE /api/v1/auth/accounts/{username}/identities/{key} hierarchy DELETE /api/v1/auth/api-keys/{short_token} hierarchy DELETE /api/v1/auth/groups/{name} hierarchy DELETE /api/v1/auth/groups/{name}/members/{username} @@ -194,6 +196,7 @@ hierarchy GET /api/v1/apps/{service}/{instance}/scaling hierarchy GET /api/v1/apps/{service}/{instance}/status hierarchy GET /api/v1/apps/{service}/{instance}/values hierarchy GET /api/v1/auth/accounts +hierarchy GET /api/v1/auth/accounts/availability hierarchy GET /api/v1/auth/accounts/me hierarchy GET /api/v1/auth/accounts/{username} hierarchy GET /api/v1/auth/accounts/{username}/attributes @@ -375,6 +378,7 @@ hierarchy PUT /api/v1/sigma/providers/{name} hierarchy PUT /api/v1/sigma/views/{source_name} if-match DELETE /api/v1/alerts/destinations/{name} if-match DELETE /api/v1/auth/accounts/{username} +if-match DELETE /api/v1/auth/accounts/{username}/identities/{key} if-match DELETE /api/v1/auth/api-keys/{short_token} if-match DELETE /api/v1/auth/groups/{name} if-match DELETE /api/v1/auth/groups/{name}/members/{username} diff --git a/tests/support/oidc.py b/tests/support/oidc.py index 386940865..9cf2e0181 100644 --- a/tests/support/oidc.py +++ b/tests/support/oidc.py @@ -11,9 +11,17 @@ from dfe_engine.auth.oidc.models import OIDCProvider +# The domains the stub relying parties' test identities carry, so their sign-ins pass the trusted-domain check. +TEST_EMAIL_DOMAINS = ("acme.test", "example.com", "example.test") + def serve_provider(app: Any, name: str = "stub") -> None: - """Store *name* enabled in the app's provider registry, as an RP built from it would have found it.""" + """Store *name* enabled in the app's provider registry, trusted for the test email domains, as an RP built from it would have found it.""" app.state.oidc_provider_registry.create( - name, OIDCProvider(type="generic", issuer="https://idp.example") + name, + OIDCProvider( + issuer="https://idp.example", + trusted_email_domains=list(TEST_EMAIL_DOMAINS), + type="generic", + ), ) diff --git a/tests/support/reauth.py b/tests/support/reauth.py new file mode 100644 index 000000000..62e50dd17 --- /dev/null +++ b/tests/support/reauth.py @@ -0,0 +1,66 @@ +# Project: dfe-engine +# File: tests/support/reauth.py +# Purpose: Lift the re-auth grant check from a test app whose tests are about something else +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""Lift the re-auth grant check from a test app whose tests are about something else.""" + +from typing import Any + +from fastapi import FastAPI + +from dfe_engine.api.app import create_app +from dfe_engine.api.deps import ( + require_account_reauth, + require_api_key_reauth, + require_group_reauth, + require_provider_reauth, + require_role_reauth, + require_scim_group_reauth, + require_scim_user_reauth, +) +from dfe_engine.api.v1.account_groups import require_new_group_reauth +from dfe_engine.api.v1.accounts import require_new_account_reauth +from dfe_engine.api.v1.api_keys import require_new_api_key_reauth +from dfe_engine.api.v1.auth import require_retire_reauth +from dfe_engine.api.v1.oidc_providers import require_new_provider_reauth +from dfe_engine.api.v1.roles import require_new_role_reauth +from dfe_engine.api.v1.scim import require_new_scim_group_reauth, require_new_scim_user_reauth + +# tests/unit/test_api/test_account_reauth.py holds every one of these to its grant. +REAUTH_CHECKS = ( + require_account_reauth, + require_api_key_reauth, + require_group_reauth, + require_new_account_reauth, + require_new_api_key_reauth, + require_new_group_reauth, + require_new_provider_reauth, + require_new_role_reauth, + require_new_scim_group_reauth, + require_new_scim_user_reauth, + require_provider_reauth, + require_retire_reauth, + require_role_reauth, + require_scim_group_reauth, + require_scim_user_reauth, +) + + +def _no_reauth() -> None: + """Stand in for a re-auth check.""" + + +def waive_reauth(app: FastAPI) -> FastAPI: + """Let *app*'s access changes through without a re-auth grant.""" + for check in REAUTH_CHECKS: + app.dependency_overrides[check] = _no_reauth + return app + + +def create_app_without_reauth(*args: Any, **kwargs: Any) -> FastAPI: + """An engine app, built as ``create_app`` builds it, that lets access changes through without a grant.""" + return waive_reauth(create_app(*args, **kwargs)) diff --git a/tests/unit/test_api/account_availability_cases.py b/tests/unit/test_api/account_availability_cases.py new file mode 100644 index 000000000..16c8834bc --- /dev/null +++ b/tests/unit/test_api/account_availability_cases.py @@ -0,0 +1,76 @@ +# Project: dfe-engine +# File: tests/unit/test_api/account_availability_cases.py +# Purpose: Case tables for whether a new account could take a name and hold an email +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""Case tables for whether a new account could take a name and hold an email.""" + +from typing import TypedDict + +EMAIL_TAKEN = "Another account already uses this email" + + +class AvailabilityCase(TypedDict): + """A name and email asked about while kaz (vouched email), jo (self-set email) and kaz's link record okta-kaz are stored.""" + + id: str + email: str + expected_email: str + expected_username: str + username: str + + +AVAILABILITY_CASES: list[AvailabilityCase] = [ + { + "id": "a_free_name_and_email_are_available", + "email": "newbie@example.test", + "expected_email": "", + "expected_username": "", + "username": "newbie", + }, + { + "id": "a_stored_name_is_taken", + "email": "", + "expected_email": "", + "expected_username": "Account 'kaz' already exists", + "username": "kaz", + }, + { + "id": "a_name_differing_only_in_case_is_taken", + "email": "", + "expected_email": "", + "expected_username": "Account 'kaz' already exists", + "username": "KAZ", + }, + { + "id": "a_link_records_name_is_taken", + "email": "", + "expected_email": "", + "expected_username": "Account 'okta-kaz' already exists", + "username": "okta-kaz", + }, + { + "id": "an_invalid_name_is_refused", + "email": "", + "expected_email": "", + "expected_username": "Invalid account name: '-bad'", + "username": "-bad", + }, + { + "id": "a_vouched_email_is_taken", + "email": "KAZ@example.test", + "expected_email": EMAIL_TAKEN, + "expected_username": "", + "username": "newbie", + }, + { + "id": "a_self_set_email_is_available", + "email": "jo@example.test", + "expected_email": "", + "expected_username": "", + "username": "newbie", + }, +] diff --git a/tests/unit/test_api/account_links_cases.py b/tests/unit/test_api/account_links_cases.py new file mode 100644 index 000000000..08452c74f --- /dev/null +++ b/tests/unit/test_api/account_links_cases.py @@ -0,0 +1,50 @@ +# Project: dfe-engine +# File: tests/unit/test_api/account_links_cases.py +# Purpose: Case tables for the API tests of accounts that IdP sign-ins are linked to +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""Case tables for the API tests of accounts that IdP sign-ins are linked to.""" + +from typing import TypedDict + +from tests.unit.test_auth.factories import make_linked_identity + + +class ProviderTypesCase(TypedDict): + """Updates to the local kaz, linked to the generic provider stub, and the types it then reads with.""" + + id: str + expected_identity_types: list[str] + expected_oidc_type: str + updates: dict[str, object] + + +PROVIDER_TYPES_CASES: list[ProviderTypesCase] = [ + { + "id": "a_linked_sign_in_reads_its_provider_type", + "expected_identity_types": ["generic"], + "expected_oidc_type": "", + "updates": {}, + }, + { + "id": "an_idp_account_reads_its_provider_type", + "expected_identity_types": [], + "expected_oidc_type": "generic", + "updates": {"external": True, "identities": [], "oidc_id": "stub"}, + }, + { + "id": "an_unregistered_provider_reads_empty", + "expected_identity_types": [""], + "expected_oidc_type": "", + "updates": { + "external": True, + "identities": [ + make_linked_identity(key="gone-kaz", provider="gone", subject="gone-kaz") + ], + "oidc_id": "gone", + }, + }, +] diff --git a/tests/unit/test_api/conftest.py b/tests/unit/test_api/conftest.py index 25caff532..14af6ab1a 100644 --- a/tests/unit/test_api/conftest.py +++ b/tests/unit/test_api/conftest.py @@ -30,6 +30,7 @@ ) from tests.support.accounts import admin_on_its_own_password, session_token from tests.support.core_sources import write_landing_definition +from tests.support.reauth import waive_reauth from tests.unit.test_query.view_fakes import OneViewCatalog, RecordingClient, view_definition # The admin password these fixtures inject, as a deployment's secret store would. @@ -138,6 +139,7 @@ def app(api_settings: DFESettings): endpoint works against store-backed accounts. """ application = create_app(settings=api_settings) + waive_reauth(application) # The lifespan will call bootstrap_auth, but we need to also seed # extra test accounts (operator, viewer) that aren't created by diff --git a/tests/unit/test_api/deps_cases.py b/tests/unit/test_api/deps_cases.py new file mode 100644 index 000000000..98ce5b2ae --- /dev/null +++ b/tests/unit/test_api/deps_cases.py @@ -0,0 +1,98 @@ +# Project: dfe-engine +# File: tests/unit/test_api/deps_cases.py +# Purpose: Case tables for the api.deps unit tests +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""Case tables for the api.deps unit tests.""" + +from typing import TypedDict + +from dfe_engine.auth.accounts import Account +from tests.unit.test_auth.factories import make_account, make_linked_identity + +_OKTA_SUBJECT = "00u15mxs3ecygt7oj698" + + +def _link_record(*, key: str, linked_to: str, subject: str) -> Account: + """A link record as a linking login leaves it.""" + return make_account( + external=True, linked_to=linked_to, source_provider="okta", subject=subject, username=key + ) + + +def _person(*, key: str, subject: str, username: str = "kaz") -> Account: + """A local account listing one okta sign-in.""" + identity = make_linked_identity(key=key, provider="okta", subject=subject) + return make_account(identities=[identity], username=username) + + +class AccountForSessionSubjectCase(TypedDict): + id: str + expected_username: str | None + stored: list[Account] + subject: str + + +ACCOUNT_FOR_SESSION_SUBJECT_CASES: list[AccountForSessionSubjectCase] = [ + { + "id": "a_link_record_binds_its_person", + "expected_username": "kaz", + "stored": [ + _person(key=_OKTA_SUBJECT, subject=_OKTA_SUBJECT), + _link_record(key=_OKTA_SUBJECT, linked_to="kaz", subject=_OKTA_SUBJECT), + ], + "subject": _OKTA_SUBJECT, + }, + { + "id": "a_link_record_at_the_stem_binds_its_person", + "expected_username": "kaz", + "stored": [ + _person(key="jane-corp-com", subject="Jane@Corp.com"), + _link_record(key="jane-corp-com", linked_to="kaz", subject="Jane@Corp.com"), + ], + "subject": "Jane@Corp.com", + }, + { + "id": "a_missing_person_binds_nothing", + "expected_username": None, + "stored": [_link_record(key=_OKTA_SUBJECT, linked_to="kaz", subject=_OKTA_SUBJECT)], + "subject": _OKTA_SUBJECT, + }, + { + "id": "a_chained_link_binds_nothing", + "expected_username": None, + "stored": [ + _link_record(key="kaz", linked_to="root", subject="kaz"), + _link_record(key=_OKTA_SUBJECT, linked_to="kaz", subject=_OKTA_SUBJECT), + _person(key=_OKTA_SUBJECT, subject=_OKTA_SUBJECT, username="root"), + ], + "subject": _OKTA_SUBJECT, + }, + { + "id": "a_person_no_longer_listing_the_sign_in_binds_nothing", + "expected_username": None, + "stored": [ + make_account(username="kaz"), + _link_record(key=_OKTA_SUBJECT, linked_to="kaz", subject=_OKTA_SUBJECT), + ], + "subject": _OKTA_SUBJECT, + }, + { + "id": "a_person_listing_another_subject_at_the_key_binds_nothing", + "expected_username": None, + "stored": [ + _person(key="jane-corp-com", subject="jane@corp.com"), + _link_record(key="jane-corp-com", linked_to="kaz", subject="Jane@Corp.com"), + ], + "subject": "Jane@Corp.com", + }, + { + "id": "a_person_binds_its_own_name", + "expected_username": "kaz", + "stored": [_person(key=_OKTA_SUBJECT, subject=_OKTA_SUBJECT)], + "subject": "kaz", + }, +] diff --git a/tests/unit/test_api/oidc_providers_cases.py b/tests/unit/test_api/oidc_providers_cases.py index b2d5e0f13..b43102feb 100644 --- a/tests/unit/test_api/oidc_providers_cases.py +++ b/tests/unit/test_api/oidc_providers_cases.py @@ -555,3 +555,41 @@ class UpdateProviderSecretSourceCase(TypedDict): }, }, ] + + +class TrustedEmailDomainsCase(TypedDict): + """One write of a provider's trusted email domains and the list it stores.""" + + id: str + expected_domains: list[str] + sent_domains: list[str] + + +TRUSTED_EMAIL_DOMAINS_CASES: list[TrustedEmailDomainsCase] = [ + { + "id": "folded_and_deduplicated", + "expected_domains": ["corp.com", "eu.corp.com"], + "sent_domains": [" Corp.COM ", "corp.com", "eu.corp.com"], + }, + { + "id": "blank_entries_dropped", + "expected_domains": ["corp.com"], + "sent_domains": ["", "corp.com", " "], + }, + {"id": "empty_links_nothing", "expected_domains": [], "sent_domains": []}, +] + + +class TrustedEmailDomainsRefusedCase(TypedDict): + """One trusted email domain list the provider API refuses.""" + + id: str + sent_domains: list[str] + + +TRUSTED_EMAIL_DOMAINS_REFUSED_CASES: list[TrustedEmailDomainsRefusedCase] = [ + {"id": "an_address", "sent_domains": ["jane@corp.com"]}, + {"id": "a_wildcard", "sent_domains": ["corp.com", "*.corp.com"]}, + {"id": "a_url", "sent_domains": ["https://corp.com"]}, + {"id": "a_single_label", "sent_domains": ["localhost"]}, +] diff --git a/tests/unit/test_api/org_role_rule_cases.py b/tests/unit/test_api/org_role_rule_cases.py new file mode 100644 index 000000000..89a629aec --- /dev/null +++ b/tests/unit/test_api/org_role_rule_cases.py @@ -0,0 +1,779 @@ +# Project: dfe-engine +# File: tests/unit/test_api/org_role_rule_cases.py +# Purpose: Case tables for org roles: the rule that an org account holds only its own org's admin or viewer group, and what an org admin may do +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""Case tables for org roles: the rule that an org account holds only its own org's admin or viewer group, and what an org admin may do.""" + +from typing import Any, Protocol, TypedDict + +from fastapi import FastAPI + +from dfe_engine.auth.identity_links import LinkTicket +from dfe_engine.auth.oidc.models import OIDCProvider + +ACCOUNTS = "/api/v1/auth/accounts" + +ACME_SSO = OIDCProvider( + client_id="acme-sso-client", issuer="https://acme-sso.test", org="acme", type="generic" +) +"""acme's own provider, stored as acme-sso: its sign-ins reach acme's accounts only.""" +API_KEYS = "/api/v1/auth/api-keys" +GROUPS = "/api/v1/auth/groups" +PASSWORD = "org-role-password-1" +PROVIDERS = "/api/v1/auth/oidc-providers" +SCIM = "/api/v1/scim/v2" + + +class Arrange(Protocol): + """A write made straight to the stores, as a path the API's checks never see would make it.""" + + def __call__(self, *, app: FastAPI) -> None: ... + + +class LiveGrantsCase(TypedDict): + """An account's roles and orgs, read from its own session, after *arrange* runs on the fixture's stores.""" + + id: str + arrange: Arrange + expected_org_ids: list[str] + expected_roles: list[str] + username: str + + +class OrgAdminAccountsCase(TypedDict): + """A request kim makes as acme's only admin, with ace an acme viewer, gil a globex viewer and ann an account of your org.""" + + id: str + body: dict[str, Any] | None + expected_code: str | None + expected_status: int + method: str + path: str + + +class OrgAdminProvidersCase(TypedDict): + """A request kim makes as acme's admin, with acme-idp, globex-idp (trusting globex.test) and the platform's platform-idp stored.""" + + id: str + body: dict[str, Any] | None + expected_code: str | None + expected_status: int + method: str + path: str + + +class OrgAdminRoleCase(TypedDict): + """A group write naming org_admin, with the fixture's accounts and groups.""" + + id: str + body: dict[str, Any] + expected_code: str | None + expected_status: int + method: str + path: str + + +class OrgRoleCase(TypedDict): + """A write while hyperi is your org, with the accounts and groups the fixture stores.""" + + id: str + body: dict[str, Any] + expected_status: int + method: str + path: str + + +def _add_ann_to_a_system_org_admin_group(*, app: FastAPI) -> None: + """Make ann a member of a system group granting org_admin.""" + app.state.group_store.create("sys-org-admins", ["org_admin"], members=["ann"]) + + +def _add_kim_to_a_roleless_group_of_globex(*, app: FastAPI) -> None: + """Make kim a member of a group with no roles tied to globex.""" + app.state.group_store.create("globex-misc", [], members=["kim"], scope="org:globex") + + +def _add_kim_to_a_system_group(*, app: FastAPI) -> None: + """Make kim a member of sys-analysts.""" + app.state.group_store.add_member("sys-analysts", "kim") + + +def _add_kim_to_a_system_org_admin_group_of_acme(*, app: FastAPI) -> None: + """Make kim a member of a system group granting org_admin over acme alone.""" + groups = app.state.group_store + groups.create("acme-sys-admins", ["org_admin"], members=["kim"]) + groups.update("acme-sys-admins", org_ids=["acme"]) + + +def _assert_a_system_group_for_ida(*, app: FastAPI) -> None: + """Link sys-analysts to sys-id and have ida's IdP assert it, as a sign-in records.""" + app.state.group_store.update("sys-analysts", source_id="sys-id", source_provider="scim") + app.state.account_store.update("ida", groups=["ext-1", "ext-eng", "sys-id"]) + + +def _give_eng_a_role(*, app: FastAPI) -> None: + """Give eng, which ida signs in through, the data_analyst role.""" + app.state.group_store.update("eng", roles=["data_analyst"]) + + +def _leave_as_stored(*, app: FastAPI) -> None: + """Write nothing.""" + + +def _link_a_sign_in_to_kim(*, app: FastAPI) -> None: + """Link sys-analysts to sys-id and link to kim a sign-in through acme-sso asserting it.""" + app.state.oidc_provider_registry.create("acme-sso", ACME_SSO) + app.state.group_store.update("sys-analysts", source_id="sys-id", source_provider="acme-sso") + ticket = LinkTicket( + account="kim", + email="kim@example.test", + groups=["sys-id"], + provider="acme-sso", + subject="kim-sub", + ) + app.state.jit_provisioner.complete_link(ticket=ticket) + + +def _link_a_system_group_to_ida(*, app: FastAPI) -> None: + """Link sys-analysts to ext-1, which ida's IdP asserts.""" + app.state.group_store.update("sys-analysts", source_id="ext-1", source_provider="scim") + + +def _make_kim_an_acme_admin(*, app: FastAPI) -> None: + """Swap kim's acme-viewers for acme-admins.""" + groups = app.state.group_store + groups.update("acme-viewers", members=["ida"]) + groups.add_member("acme-admins", "kim") + + +def _move_kim_to_a_system_viewer_of_acme(*, app: FastAPI) -> None: + """Swap kim's acme-viewers for a system group granting org_viewer over acme alone.""" + groups = app.state.group_store + groups.update("acme-viewers", members=["ida"]) + groups.create("acme-readers", ["org_viewer"], members=["kim"]) + groups.update("acme-readers", org_ids=["acme"]) + + +def _name_globex_your_org(*, app: FastAPI) -> None: + """Make globex your org in hyperi's place.""" + app.state.org_registry.home.set(actor="test", name="globex") + + +def _new_account(*, groups: list[str], org: str) -> dict[str, Any]: + """A create body for the account newbie.""" + return { + "email": "newbie@example.test", + "groups": groups, + "name": "Newbie", + "org": org, + "password": PASSWORD, + "username": "newbie", + } + + +def _new_provider(*, domains: list[str], org: str) -> dict[str, Any]: + """A create body for the provider acme-two.""" + return { + "client_id": "acme-two-client", + "issuer": "https://idp.acme.test", + "name": "acme-two", + "org": org, + "trusted_email_domains": domains, + "type": "generic", + } + + +def _org_key(*, groups: list[str], org: str) -> dict[str, Any]: + """A create body for the API key org-key.""" + return {"groups": groups, "name": "org-key", "org": org} + + +def _reach_globex_from_acme_viewers(*, app: FastAPI) -> None: + """Give acme-viewers globex as another org it reaches.""" + app.state.group_store.update("acme-viewers", org_ids=["globex"]) + + +LIVE_GRANTS_CASES: list[LiveGrantsCase] = [ + { + "id": "an_org_viewer_reaches_its_own_org", + "arrange": _leave_as_stored, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "kim", + }, + { + "id": "a_system_group_listing_an_org_account_grants_it_nothing", + "arrange": _add_kim_to_a_system_group, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "kim", + }, + { + "id": "a_roleless_group_of_another_org_gives_it_nothing", + "arrange": _add_kim_to_a_roleless_group_of_globex, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "kim", + }, + { + "id": "a_system_org_viewer_naming_only_its_org_reaches_it", + "arrange": _move_kim_to_a_system_viewer_of_acme, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "kim", + }, + { + "id": "a_system_group_linked_to_its_idp_group_grants_it_nothing", + "arrange": _link_a_system_group_to_ida, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "ida", + }, + { + "id": "a_role_on_a_group_it_signs_in_through_grants_it_nothing", + "arrange": _give_eng_a_role, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "ida", + }, + { + "id": "a_system_group_its_idp_asserts_at_sign_in_grants_it_nothing", + "arrange": _assert_a_system_group_for_ida, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "ida", + }, + { + "id": "a_linked_sign_in_asserting_a_system_group_grants_it_nothing", + "arrange": _link_a_sign_in_to_kim, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "kim", + }, + { + "id": "its_own_group_reaching_another_org_grants_it_nothing", + "arrange": _reach_globex_from_acme_viewers, + "expected_org_ids": [], + "expected_roles": [], + "username": "kim", + }, + { + "id": "an_org_admin_reaches_its_own_org", + "arrange": _make_kim_an_acme_admin, + "expected_org_ids": ["acme"], + "expected_roles": ["org_admin"], + "username": "kim", + }, + { + "id": "a_system_group_naming_its_org_does_not_make_it_admin", + "arrange": _add_kim_to_a_system_org_admin_group_of_acme, + "expected_org_ids": ["acme"], + "expected_roles": ["org_viewer"], + "username": "kim", + }, + { + "id": "a_system_group_granting_org_admin_grants_your_orgs_account_nothing", + "arrange": _add_ann_to_a_system_org_admin_group, + "expected_org_ids": [], + "expected_roles": ["data_analyst"], + "username": "ann", + }, + { + "id": "an_account_of_your_org_holds_a_system_group", + "arrange": _leave_as_stored, + "expected_org_ids": [], + "expected_roles": ["data_analyst"], + "username": "ann", + }, + { + "id": "an_account_of_your_old_org_loses_its_system_group", + "arrange": _name_globex_your_org, + "expected_org_ids": [], + "expected_roles": [], + "username": "ann", + }, +] + +ORG_ADMIN_ACCOUNTS_CASES: list[OrgAdminAccountsCase] = [ + { + "id": "creating_an_account_in_its_org_passes", + "body": _new_account(groups=["acme-viewers"], org="acme"), + "expected_code": None, + "expected_status": 201, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "creating_an_account_in_another_org_is_refused", + "body": _new_account(groups=["globex-viewers"], org="globex"), + "expected_code": "forbidden", + "expected_status": 403, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "creating_a_root_account_is_refused", + "body": _new_account(groups=[], org=""), + "expected_code": "forbidden", + "expected_status": 403, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "creating_an_account_with_a_role_it_does_not_hold_is_refused", + "body": _new_account(groups=["acme-analysts"], org="acme"), + "expected_code": "forbidden", + "expected_status": 403, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "reading_an_account_of_its_org_passes", + "body": None, + "expected_code": None, + "expected_status": 200, + "method": "GET", + "path": f"{ACCOUNTS}/ace", + }, + { + "id": "another_orgs_account_is_not_found", + "body": None, + "expected_code": "not_found", + "expected_status": 404, + "method": "GET", + "path": f"{ACCOUNTS}/gil", + }, + { + "id": "an_account_of_your_org_is_not_found", + "body": None, + "expected_code": "not_found", + "expected_status": 404, + "method": "GET", + "path": f"{ACCOUNTS}/ann", + }, + { + "id": "making_an_account_of_its_org_admin_passes", + "body": {"groups": ["acme-admins"]}, + "expected_code": None, + "expected_status": 200, + "method": "PUT", + "path": f"{ACCOUNTS}/ace", + }, + { + "id": "disabling_an_account_of_its_org_passes", + "body": {"enabled": False}, + "expected_code": None, + "expected_status": 200, + "method": "PUT", + "path": f"{ACCOUNTS}/ace", + }, + { + "id": "moving_an_account_to_another_org_is_refused", + "body": {"groups": ["globex-viewers"], "org": "globex"}, + "expected_code": "forbidden", + "expected_status": 403, + "method": "PUT", + "path": f"{ACCOUNTS}/ace", + }, + { + "id": "editing_another_orgs_account_is_not_found", + "body": {"enabled": False}, + "expected_code": "not_found", + "expected_status": 404, + "method": "PUT", + "path": f"{ACCOUNTS}/gil", + }, + { + "id": "demoting_its_orgs_last_admin_is_refused", + "body": {"groups": ["acme-viewers"]}, + "expected_code": "last_org_admin", + "expected_status": 409, + "method": "PUT", + "path": f"{ACCOUNTS}/kim", + }, + { + "id": "resetting_a_password_in_its_org_passes", + "body": {"new_password": "org-admin-reset-1"}, + "expected_code": None, + "expected_status": 200, + "method": "POST", + "path": f"{ACCOUNTS}/ace/reset-password", + }, + { + "id": "resetting_another_orgs_password_is_not_found", + "body": {"new_password": "org-admin-reset-1"}, + "expected_code": "not_found", + "expected_status": 404, + "method": "POST", + "path": f"{ACCOUNTS}/gil/reset-password", + }, + { + "id": "deleting_an_account_of_its_org_passes", + "body": None, + "expected_code": None, + "expected_status": 204, + "method": "DELETE", + "path": f"{ACCOUNTS}/ace", + }, + { + "id": "deleting_another_orgs_account_is_not_found", + "body": None, + "expected_code": "not_found", + "expected_status": 404, + "method": "DELETE", + "path": f"{ACCOUNTS}/gil", + }, +] + +ORG_ADMIN_PROVIDERS_CASES: list[OrgAdminProvidersCase] = [ + { + "id": "creating_a_provider_in_its_org_passes", + "body": _new_provider(domains=["acme.test"], org="acme"), + "expected_code": None, + "expected_status": 201, + "method": "POST", + "path": PROVIDERS, + }, + { + "id": "creating_a_provider_in_another_org_is_refused", + "body": _new_provider(domains=[], org="globex"), + "expected_code": "forbidden", + "expected_status": 403, + "method": "POST", + "path": PROVIDERS, + }, + { + "id": "creating_a_platform_provider_is_refused", + "body": _new_provider(domains=[], org=""), + "expected_code": "forbidden", + "expected_status": 403, + "method": "POST", + "path": PROVIDERS, + }, + { + "id": "trusting_another_orgs_domain_is_refused", + "body": _new_provider(domains=["globex.test"], org="acme"), + "expected_code": "domain_taken", + "expected_status": 422, + "method": "POST", + "path": PROVIDERS, + }, + { + "id": "naming_its_provider_after_the_proxy_provider_is_refused", + "body": {**_new_provider(domains=[], org="acme"), "name": "oidc"}, + "expected_code": "provider_name_reserved", + "expected_status": 422, + "method": "POST", + "path": PROVIDERS, + }, + { + "id": "naming_its_provider_scim_is_refused", + "body": {**_new_provider(domains=[], org="acme"), "name": "scim"}, + "expected_code": "provider_name_reserved", + "expected_status": 422, + "method": "POST", + "path": PROVIDERS, + }, + { + "id": "reading_its_client_id_from_an_engine_env_var_is_refused", + "body": {**_new_provider(domains=[], org="acme"), "client_id": "", "client_id_env": "PATH"}, + "expected_code": "env_source_refused", + "expected_status": 422, + "method": "POST", + "path": PROVIDERS, + }, + { + "id": "reading_its_secret_from_an_engine_env_var_is_refused", + "body": {**_new_provider(domains=[], org="acme"), "client_secret_env": "PATH"}, + "expected_code": "env_source_refused", + "expected_status": 422, + "method": "POST", + "path": PROVIDERS, + }, + { + "id": "pointing_its_provider_at_an_engine_env_var_is_refused", + "body": {"client_secret_env": "PATH"}, + "expected_code": "env_source_refused", + "expected_status": 422, + "method": "PUT", + "path": f"{PROVIDERS}/acme-idp", + }, + { + "id": "reading_its_orgs_provider_passes", + "body": None, + "expected_code": None, + "expected_status": 200, + "method": "GET", + "path": f"{PROVIDERS}/acme-idp", + }, + { + "id": "another_orgs_provider_is_not_found", + "body": None, + "expected_code": "not_found", + "expected_status": 404, + "method": "GET", + "path": f"{PROVIDERS}/globex-idp", + }, + { + "id": "a_platform_provider_is_not_found", + "body": None, + "expected_code": "not_found", + "expected_status": 404, + "method": "GET", + "path": f"{PROVIDERS}/platform-idp", + }, + { + "id": "editing_its_orgs_provider_passes", + "body": {"display_name": "Acme sign-in"}, + "expected_code": None, + "expected_status": 200, + "method": "PUT", + "path": f"{PROVIDERS}/acme-idp", + }, + { + "id": "moving_its_provider_to_another_org_is_refused", + "body": {"org": "globex"}, + "expected_code": "forbidden", + "expected_status": 403, + "method": "PUT", + "path": f"{PROVIDERS}/acme-idp", + }, + { + "id": "testing_another_orgs_provider_is_not_found", + "body": None, + "expected_code": "not_found", + "expected_status": 404, + "method": "GET", + "path": f"{PROVIDERS}/globex-idp/test", + }, + { + "id": "verifying_another_orgs_provider_login_is_not_found", + "body": None, + "expected_code": "not_found", + "expected_status": 404, + "method": "GET", + "path": f"{PROVIDERS}/globex-idp/verify-login", + }, + { + "id": "syncing_its_orgs_provider_groups_is_refused", + "body": None, + "expected_code": "forbidden", + "expected_status": 403, + "method": "POST", + "path": f"{PROVIDERS}/acme-idp/sync", + }, + { + "id": "deleting_another_orgs_provider_is_not_found", + "body": None, + "expected_code": "not_found", + "expected_status": 404, + "method": "DELETE", + "path": f"{PROVIDERS}/globex-idp", + }, + { + "id": "deleting_its_orgs_provider_passes", + "body": None, + "expected_code": None, + "expected_status": 200, + "method": "DELETE", + "path": f"{PROVIDERS}/acme-idp", + }, +] + +ORG_ADMIN_ROLE_CASES: list[OrgAdminRoleCase] = [ + { + "id": "a_system_group_may_not_grant_org_admin", + "body": {"name": "sys-org-admins", "roles": ["org_admin"]}, + "expected_code": "org_admin_org_only", + "expected_status": 422, + "method": "POST", + "path": GROUPS, + }, + { + "id": "a_system_group_may_not_be_given_org_admin", + "body": {"roles": ["org_admin"]}, + "expected_code": "org_admin_org_only", + "expected_status": 422, + "method": "PUT", + "path": f"{GROUPS}/sys-analysts", + }, + { + "id": "an_org_group_may_grant_org_admin", + "body": {"name": "acme-leads", "roles": ["org_admin"], "scope": "org:acme"}, + "expected_code": None, + "expected_status": 201, + "method": "POST", + "path": GROUPS, + }, +] + +ORG_ROLE_CASES: list[OrgRoleCase] = [ + { + "id": "creating_an_org_account_with_its_viewer_group_passes", + "body": _new_account(groups=["acme-viewers"], org="acme"), + "expected_status": 201, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "creating_an_org_account_with_another_orgs_group_is_refused", + "body": _new_account(groups=["globex-viewers"], org="acme"), + "expected_status": 422, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "creating_an_org_account_with_a_system_group_is_refused", + "body": _new_account(groups=["sys-analysts"], org="acme"), + "expected_status": 422, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "creating_an_org_account_with_its_orgs_other_role_is_refused", + "body": _new_account(groups=["acme-analysts"], org="acme"), + "expected_status": 422, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "a_root_account_may_hold_any_group", + "body": _new_account(groups=["globex-viewers", "sys-analysts"], org=""), + "expected_status": 201, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "an_account_of_your_org_may_hold_any_group", + "body": _new_account(groups=["sys-analysts"], org="hyperi"), + "expected_status": 201, + "method": "POST", + "path": ACCOUNTS, + }, + { + "id": "giving_an_org_account_another_orgs_group_is_refused", + "body": {"groups": ["globex-viewers"]}, + "expected_status": 422, + "method": "PUT", + "path": f"{ACCOUNTS}/kim", + }, + { + "id": "making_an_org_account_its_orgs_admin_passes", + "body": {"groups": ["acme-admins"]}, + "expected_status": 200, + "method": "PUT", + "path": f"{ACCOUNTS}/kim", + }, + { + "id": "moving_an_org_account_and_keeping_its_old_group_is_refused", + "body": {"org": "globex"}, + "expected_status": 422, + "method": "PUT", + "path": f"{ACCOUNTS}/kim", + }, + { + "id": "moving_an_org_account_with_its_new_orgs_group_passes", + "body": {"groups": ["globex-viewers"], "org": "globex"}, + "expected_status": 200, + "method": "PUT", + "path": f"{ACCOUNTS}/kim", + }, + { + "id": "adding_an_org_account_to_another_orgs_group_is_refused", + "body": {"username": "kim"}, + "expected_status": 422, + "method": "POST", + "path": f"{GROUPS}/globex-viewers/members", + }, + { + "id": "giving_an_org_accounts_group_another_role_is_refused", + "body": {"roles": ["data_analyst"]}, + "expected_status": 422, + "method": "PUT", + "path": f"{GROUPS}/acme-viewers", + }, + { + "id": "creating_a_system_group_holding_an_org_account_is_refused", + "body": {"members": ["kim"], "name": "sys-kim", "roles": ["data_viewer"]}, + "expected_status": 422, + "method": "POST", + "path": GROUPS, + }, + { + "id": "creating_a_roleless_group_of_another_org_holding_an_org_account_is_refused", + "body": {"members": ["kim"], "name": "globex-misc", "roles": [], "scope": "org:globex"}, + "expected_status": 422, + "method": "POST", + "path": GROUPS, + }, + { + "id": "creating_a_group_linked_to_an_org_accounts_idp_group_is_refused", + "body": { + "name": "new-analysts", + "roles": ["data_analyst"], + "source_id": "ext-1", + "source_provider": "scim", + }, + "expected_status": 422, + "method": "POST", + "path": GROUPS, + }, + { + "id": "linking_a_system_group_to_an_org_accounts_idp_group_is_refused", + "body": {"source_id": "ext-1", "source_provider": "scim"}, + "expected_status": 422, + "method": "PUT", + "path": f"{GROUPS}/sys-analysts", + }, + { + "id": "linking_an_org_accounts_viewer_group_to_its_idp_group_passes", + "body": {"source_id": "ext-1", "source_provider": "scim"}, + "expected_status": 200, + "method": "PUT", + "path": f"{GROUPS}/acme-viewers", + }, + { + "id": "giving_a_group_an_org_account_signs_in_through_a_role_is_refused", + "body": {"roles": ["data_analyst"]}, + "expected_status": 422, + "method": "PUT", + "path": f"{GROUPS}/eng", + }, + { + "id": "moving_a_scim_external_id_to_an_org_accounts_idp_group_is_refused", + "body": { + "displayName": "sys-analysts", + "externalId": "ext-1", + "members": [], + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + }, + "expected_status": 400, + "method": "PUT", + "path": f"{SCIM}/Groups/sys-analysts", + }, + { + "id": "minting_an_org_key_holding_a_system_group_is_refused", + "body": _org_key(groups=["sys-analysts"], org="acme"), + "expected_status": 422, + "method": "POST", + "path": API_KEYS, + }, + { + "id": "minting_an_org_key_holding_its_viewer_group_passes", + "body": _org_key(groups=["acme-viewers"], org="acme"), + "expected_status": 201, + "method": "POST", + "path": API_KEYS, + }, + { + "id": "minting_a_key_of_your_org_holding_a_system_group_passes", + "body": _org_key(groups=["sys-analysts"], org="hyperi"), + "expected_status": 201, + "method": "POST", + "path": API_KEYS, + }, +] diff --git a/tests/unit/test_api/root_accounts_cases.py b/tests/unit/test_api/root_accounts_cases.py index 82731329e..30420bf9c 100644 --- a/tests/unit/test_api/root_accounts_cases.py +++ b/tests/unit/test_api/root_accounts_cases.py @@ -55,3 +55,40 @@ class OrgFilterCase(TypedDict): {"id": "another_org_lists_only_its_own", "expected": {"globex-bob"}, "org": "globex"}, {"id": "empty_lists_only_root_accounts", "expected": {"root-kim"}, "org": ""}, ] + + +class OrgDisplayNameCase(TypedDict): + """An account naming *account_org* while *your_org* is named, and the display name its read reports.""" + + id: str + account_org: str + expected_org_display_name: str + your_org: str | None + + +ORG_DISPLAY_NAME_CASES: list[OrgDisplayNameCase] = [ + { + "id": "a_root_account_reads_your_orgs_display_name", + "account_org": "", + "expected_org_display_name": "Acme Corp", + "your_org": "acme", + }, + { + "id": "a_bound_account_reads_its_orgs_display_name", + "account_org": "globex", + "expected_org_display_name": "Globex Inc", + "your_org": "acme", + }, + { + "id": "an_org_without_a_display_name_reads_its_name", + "account_org": "initech", + "expected_org_display_name": "initech", + "your_org": "acme", + }, + { + "id": "a_root_account_reads_empty_while_no_org_is_yours", + "account_org": "", + "expected_org_display_name": "", + "your_org": None, + }, +] diff --git a/tests/unit/test_api/test_account_availability.py b/tests/unit/test_api/test_account_availability.py new file mode 100644 index 000000000..5f7e913f9 --- /dev/null +++ b/tests/unit/test_api/test_account_availability.py @@ -0,0 +1,62 @@ +# Project: dfe-engine +# File: tests/unit/test_api/test_account_availability.py +# Purpose: API tests for whether a new account could take a name and hold an email +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from tests.unit.test_api.account_availability_cases import AVAILABILITY_CASES, AvailabilityCase +from tests.unit.test_auth.factories import make_account + +_AVAILABILITY = "/api/v1/auth/accounts/availability" + + +@pytest.fixture +def stored(app: FastAPI, client: TestClient) -> FastAPI: + """Store kaz with a vouched email, jo with a self-set one, and okta-kaz linked to kaz.""" + store = app.state.account_store + store.put(make_account(email="kaz@example.test", email_verified=True, username="kaz")) + store.put(make_account(email="jo@example.test", email_verified=False, username="jo")) + store.put( + make_account( + external=True, + linked_to="kaz", + source_provider="okta", + subject="00u1", + username="okta-kaz", + ) + ) + return app + + +class TestAvailability: + @pytest.mark.parametrize( + "case", AVAILABILITY_CASES, ids=[case["id"] for case in AVAILABILITY_CASES] + ) + def test_matches_expected( + self, + admin_headers: dict[str, str], + client: TestClient, + stored: FastAPI, + case: AvailabilityCase, + ): + body = client.get( + _AVAILABILITY, + headers=admin_headers, + params={"email": case["email"], "username": case["username"]}, + ).json() + assert (body["username"], body["email"]) == ( + case["expected_username"], + case["expected_email"], + ) + + def test_a_reader_without_account_write_is_refused( + self, client: TestClient, stored: FastAPI, viewer_headers: dict[str, str] + ): + resp = client.get(_AVAILABILITY, headers=viewer_headers, params={"username": "x"}) + assert resp.status_code == 403 diff --git a/tests/unit/test_api/test_account_crud.py b/tests/unit/test_api/test_account_crud.py index f6b252a62..e8c9384d0 100644 --- a/tests/unit/test_api/test_account_crud.py +++ b/tests/unit/test_api/test_account_crud.py @@ -12,6 +12,8 @@ import secrets import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient from dfe_engine.auth.accounts import Account, AccountStore from dfe_engine.auth.bootstrap import MIN_ADMIN_PASSWORD_LENGTH @@ -40,6 +42,7 @@ def test_create_account(self, client, admin_headers): resp = client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "newuser", "password": _PASSWORD, "email": "newuser@example.com", @@ -58,7 +61,7 @@ def test_create_account(self, client, admin_headers): assert "password_hash" not in data assert data["email"] == "newuser@example.com" assert data["phone"] == "" - assert data["name"] == "" + assert data["name"] == "Test User" group = client.get("/api/v1/auth/groups/dfe-viewers", headers=admin_headers) assert "newuser" in group.json()["members"] @@ -90,7 +93,7 @@ def test_create_account_with_contact_fields(self, client, admin_headers): def test_create_without_an_email(self, client, admin_headers): resp = client.post( "/api/v1/auth/accounts", - json={"username": "no-email", "password": _PASSWORD}, + json={"name": "Test User", "username": "no-email", "password": _PASSWORD}, headers=admin_headers, ) assert resp.status_code == 201 @@ -101,7 +104,12 @@ def test_create_with_an_empty_email(self, client, admin_headers): # says what leaving the key out says. resp = client.post( "/api/v1/auth/accounts", - json={"username": "empty-email", "password": _PASSWORD, "email": ""}, + json={ + "name": "Test User", + "username": "empty-email", + "password": _PASSWORD, + "email": "", + }, headers=admin_headers, ) assert resp.status_code == 201 @@ -111,6 +119,7 @@ def test_create_with_email_only(self, client, admin_headers): resp = client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "email-only", "password": _PASSWORD, "email": "only@example.com", @@ -121,17 +130,37 @@ def test_create_with_email_only(self, client, admin_headers): data = resp.json() assert data["email"] == "only@example.com" assert data["phone"] == "" - assert data["name"] == "" + assert data["name"] == "Test User" + + @pytest.mark.parametrize( + "body", + [{}, {"name": ""}, {"name": " "}], + ids=["missing", "empty", "blank"], + ) + def test_a_missing_or_blank_name_is_refused(self, app, client, admin_headers, body): + resp = client.post( + "/api/v1/auth/accounts", + json={"password": _PASSWORD, "username": "nameless", **body}, + headers=admin_headers, + ) + assert (resp.status_code, [e["field"] for e in resp.json()["errors"]]) == (422, ["name"]) + assert app.state.account_store.get("nameless") is None def test_create_duplicate_returns_409(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "dupuser", "password": _PASSWORD, "email": "dupuser@example.com"}, + json={ + "name": "Test User", + "username": "dupuser", + "password": _PASSWORD, + "email": "dupuser@example.com", + }, headers=admin_headers, ) resp = client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "dupuser", "password": secrets.token_urlsafe(16), "email": "dupuser@example.com", @@ -150,6 +179,7 @@ def test_a_name_taken_after_the_lookup_is_still_a_409(self, app, client, admin_h resp = client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "racer", "password": secrets.token_urlsafe(16), "groups": ["dfe-viewers"], @@ -168,7 +198,12 @@ def test_a_name_no_account_can_have_is_a_422(self, app, client, admin_headers, u resp = client.post( "/api/v1/auth/accounts", - json={"username": username, "password": _PASSWORD, "groups": ["dfe-viewers"]}, + json={ + "name": "Test User", + "username": username, + "password": _PASSWORD, + "groups": ["dfe-viewers"], + }, headers=admin_headers, ) @@ -183,7 +218,7 @@ def test_a_password_longer_than_the_hash_takes_is_a_422(self, app, client, admin resp = client.post( "/api/v1/auth/accounts", - json={"username": "long-pw", "password": password}, + json={"name": "Test User", "username": "long-pw", "password": password}, headers=admin_headers, ) @@ -197,7 +232,7 @@ def test_a_store_fault_is_not_answered_as_a_bad_request(self, app, client, admin resp = client.post( "/api/v1/auth/accounts", - json={"username": "fine-name", "password": _PASSWORD}, + json={"name": "Test User", "username": "fine-name", "password": _PASSWORD}, headers=admin_headers, ) @@ -215,7 +250,7 @@ def test_a_password_under_the_floor_is_refused(self, client, app, admin_headers) short = _short_password() resp = client.post( "/api/v1/auth/accounts", - json={"username": "short-pw", "password": short, "groups": []}, + json={"name": "Test User", "username": "short-pw", "password": short, "groups": []}, headers=admin_headers, ) assert resp.status_code == 422, resp.text @@ -228,7 +263,7 @@ def test_a_password_under_the_floor_is_refused(self, client, app, admin_headers) # What the console's CreateAccountForm posts. The setup wizard creates the first # user with it, so a field required beyond these leaves a fresh deployment with # no way into its own console. -CONSOLE_CREATE_FIELDS = {"username", "password", "groups"} +CONSOLE_CREATE_FIELDS = {"groups", "name", "password", "username"} class TestConsoleCreatePayload: @@ -241,7 +276,12 @@ class TestConsoleCreatePayload: def test_the_console_payload_creates_an_account(self, client, admin_headers): resp = client.post( "/api/v1/auth/accounts", - json={"username": "wizard-first-user", "password": _PASSWORD, "groups": []}, + json={ + "name": "Test User", + "username": "wizard-first-user", + "password": _PASSWORD, + "groups": [], + }, headers=admin_headers, ) assert resp.status_code == 201 @@ -326,10 +366,98 @@ def test_list_filters_by_oidc_id(self, client, admin_headers, app): assert searched.status_code == 200 assert all(a["username"] != "oidc-bob" for a in searched.json()["items"]) + @pytest.mark.parametrize( + ("org", "expected"), + [("acme", {"org-alice"}), ("", {"no-org-carol"})], + ids=["an_org_lists_its_accounts", "empty_lists_the_accounts_bound_to_none"], + ) + def test_list_filters_by_org( + self, + admin_headers: dict[str, str], + app: FastAPI, + client: TestClient, + org: str, + expected: set[str], + ): + store = app.state.account_store + for username, account_org in ( + ("org-alice", "acme"), + ("org-bob", "globex"), + ("no-org-carol", ""), + ): + store.create(username=username, password="") + store.update(username=username, org=account_org) + page = client.get( + "/api/v1/auth/accounts", + headers=admin_headers, + params={"limit": 100, "org": org}, + ).json() + listed = {item["username"] for item in page["items"]} + assert listed & {"org-alice", "org-bob", "no-org-carol"} == expected + + def test_list_orders_root_accounts_first_then_by_org( + self, admin_headers: dict[str, str], app: FastAPI, client: TestClient + ): + store = app.state.account_store + for username, account_org in ( + ("order-zed", "globex"), + ("order-amy", "acme"), + ("order-root-b", ""), + ("order-root-a", ""), + ): + store.create(username=username, password="") + store.update(username=username, org=account_org) + page = client.get( + "/api/v1/auth/accounts", + headers=admin_headers, + params={"limit": 100, "order_by": "org"}, + ).json() + listed = [item["username"] for item in page["items"]] + assert [name for name in listed if name.startswith("order-")] == [ + "order-root-a", + "order-root-b", + "order-amy", + "order-zed", + ] + + @pytest.mark.parametrize( + ("roles", "scope", "expected"), + [ + (["admin"], "system", True), + (["admin"], "org:acme", False), + (["data_viewer"], "system", False), + ], + ids=[ + "a_system_admin_group_makes_an_admin", + "an_org_admin_group_does_not", + "a_group_without_the_admin_role_does_not", + ], + ) + def test_admin_flag( + self, + admin_headers: dict[str, str], + app: FastAPI, + client: TestClient, + roles: list[str], + scope: str, + expected: bool, + ): + app.state.account_store.create(username="flag-kim", password="") + app.state.group_store.create( + members=["flag-kim"], name="flag-group", roles=roles, scope=scope + ) + body = client.get("/api/v1/auth/accounts/flag-kim", headers=admin_headers).json() + assert body["admin"] is expected + def test_list_blocked_omitted_returns_all(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "listed-blocked", "password": _PASSWORD, "email": "lb@example.com"}, + json={ + "name": "Test User", + "username": "listed-blocked", + "password": _PASSWORD, + "email": "lb@example.com", + }, headers=admin_headers, ) client.put( @@ -347,7 +475,12 @@ def test_list_blocked_omitted_returns_all(self, client, admin_headers): def test_list_blocked_true_returns_only_blocked(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "only-blocked", "password": _PASSWORD, "email": "ob@example.com"}, + json={ + "name": "Test User", + "username": "only-blocked", + "password": _PASSWORD, + "email": "ob@example.com", + }, headers=admin_headers, ) client.put( @@ -370,7 +503,12 @@ def test_list_blocked_true_returns_only_blocked(self, client, admin_headers): def test_list_blocked_false_returns_only_unblocked(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "now-blocked", "password": _PASSWORD, "email": "nb@example.com"}, + json={ + "name": "Test User", + "username": "now-blocked", + "password": _PASSWORD, + "email": "nb@example.com", + }, headers=admin_headers, ) client.put( @@ -500,7 +638,12 @@ def test_oidc_account_surfaces_external_true(self, client, app, admin_headers, a def test_list_and_create_include_external(self, client, admin_headers): created = client.post( "/api/v1/auth/accounts", - json={"username": "local-user", "password": _PASSWORD, "email": "local@example.com"}, + json={ + "name": "Test User", + "username": "local-user", + "password": _PASSWORD, + "email": "local@example.com", + }, headers=admin_headers, ) assert created.status_code == 201 @@ -518,7 +661,12 @@ def test_update_groups(self, client, admin_headers): # Create account first client.post( "/api/v1/auth/accounts", - json={"username": "updatable", "password": _PASSWORD, "email": "updatable@example.com"}, + json={ + "name": "Test User", + "username": "updatable", + "password": _PASSWORD, + "email": "updatable@example.com", + }, headers=admin_headers, ) resp = client.put( @@ -536,6 +684,7 @@ def test_update_groups_removes_from_old_group(self, client, admin_headers): client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "grp-sync", "password": _PASSWORD, "email": "grp-sync@example.com", @@ -692,19 +841,46 @@ def test_update_contact_fields_empty_string_clears(self, client, admin_headers): ) resp = client.put( "/api/v1/auth/accounts/contact-clear", - json={"phone": "", "name": ""}, + json={"phone": ""}, headers=admin_headers, ) assert resp.status_code == 200 data = resp.json() assert data["email"] == "gone@example.com" assert data["phone"] == "" - assert data["name"] == "" + assert data["name"] == "Gone" + + def test_a_set_name_cannot_be_cleared(self, app, client, admin_headers): + client.post( + "/api/v1/auth/accounts", + json={"name": "Named", "password": _PASSWORD, "username": "named"}, + headers=admin_headers, + ) + resp = client.put("/api/v1/auth/accounts/named", json={"name": " "}, headers=admin_headers) + assert ( + resp.status_code, + resp.json()["code"], + app.state.account_store.get("named").name, + ) == ( + 422, + "name_required", + "Named", + ) + + def test_an_account_with_no_name_still_takes_an_empty_one(self, app, client, admin_headers): + app.state.account_store.create("unnamed", _PASSWORD) + resp = client.put( + "/api/v1/auth/accounts/unnamed", + json={"name": "", "phone": "+1"}, + headers=admin_headers, + ) + assert (resp.status_code, resp.json()["phone"]) == (200, "+1") def test_update_empty_email_returns_422(self, client, admin_headers): client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "email-required", "password": _PASSWORD, "email": "keep@example.com", @@ -721,7 +897,12 @@ def test_update_empty_email_returns_422(self, client, admin_headers): def test_update_enabled(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "disableme", "password": _PASSWORD, "email": "disableme@example.com"}, + json={ + "name": "Test User", + "username": "disableme", + "password": _PASSWORD, + "email": "disableme@example.com", + }, headers=admin_headers, ) resp = client.put( @@ -747,7 +928,12 @@ def test_deactivate_admin_is_allowed_when_another_usable_admin_remains( ): created = client.post( "/api/v1/auth/accounts", - json={"username": "ops", "password": _PASSWORD, "groups": ["dfe-admins"]}, + json={ + "name": "Test User", + "username": "ops", + "password": _PASSWORD, + "groups": ["dfe-admins"], + }, headers=admin_headers, ) assert created.status_code == 201, created.text @@ -767,7 +953,12 @@ def test_strip_admin_group_from_last_usable_admin_is_refused( store = recovery_accounts.state.account_store created = client.post( "/api/v1/auth/accounts", - json={"username": "ops", "password": _PASSWORD, "groups": ["dfe-admins"]}, + json={ + "name": "Test User", + "username": "ops", + "password": _PASSWORD, + "groups": ["dfe-admins"], + }, headers=admin_headers, ) assert created.status_code == 201, created.text @@ -800,7 +991,12 @@ def test_strip_admin_group_is_allowed_when_another_usable_admin_remains( ): created = client.post( "/api/v1/auth/accounts", - json={"username": "ops", "password": _PASSWORD, "groups": ["dfe-admins"]}, + json={ + "name": "Test User", + "username": "ops", + "password": _PASSWORD, + "groups": ["dfe-admins"], + }, headers=admin_headers, ) assert created.status_code == 201, created.text @@ -818,7 +1014,12 @@ def test_deactivate_own_account_is_refused(self, recovery_accounts, client, admi store = recovery_accounts.state.account_store created = client.post( "/api/v1/auth/accounts", - json={"username": "ops", "password": _PASSWORD, "groups": ["dfe-admins"]}, + json={ + "name": "Test User", + "username": "ops", + "password": _PASSWORD, + "groups": ["dfe-admins"], + }, headers=admin_headers, ) assert created.status_code == 201, created.text @@ -847,7 +1048,12 @@ def test_block_own_account_is_refused(self, recovery_accounts, client, admin_hea store = recovery_accounts.state.account_store created = client.post( "/api/v1/auth/accounts", - json={"username": "ops", "password": _PASSWORD, "groups": ["dfe-admins"]}, + json={ + "name": "Test User", + "username": "ops", + "password": _PASSWORD, + "groups": ["dfe-admins"], + }, headers=admin_headers, ) assert created.status_code == 201, created.text @@ -875,7 +1081,12 @@ def test_block_own_account_is_refused(self, recovery_accounts, client, admin_hea def test_update_blocked(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "blockme", "password": _PASSWORD, "email": "blockme@example.com"}, + json={ + "name": "Test User", + "username": "blockme", + "password": _PASSWORD, + "email": "blockme@example.com", + }, headers=admin_headers, ) resp = client.put( @@ -1209,7 +1420,12 @@ def test_a_new_password_longer_than_bcrypt_takes_is_a_422(self, client, app, adm def test_reset_password(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "pwreset", "password": _PASSWORD, "email": "pwreset@example.com"}, + json={ + "name": "Test User", + "username": "pwreset", + "password": _PASSWORD, + "email": "pwreset@example.com", + }, headers=admin_headers, ) resp = client.post( @@ -1223,7 +1439,12 @@ def test_reset_password(self, client, admin_headers): def test_reset_to_current_password_rejected(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "pwsame", "password": _PASSWORD, "email": "pwsame@example.com"}, + json={ + "name": "Test User", + "username": "pwsame", + "password": _PASSWORD, + "email": "pwsame@example.com", + }, headers=admin_headers, ) resp = client.post( @@ -1398,7 +1619,12 @@ class TestDeleteAccount: def test_delete_account(self, client, admin_headers): client.post( "/api/v1/auth/accounts", - json={"username": "deleteme", "password": _PASSWORD, "email": "deleteme@example.com"}, + json={ + "name": "Test User", + "username": "deleteme", + "password": _PASSWORD, + "email": "deleteme@example.com", + }, headers=admin_headers, ) resp = client.delete("/api/v1/auth/accounts/deleteme", headers=admin_headers) @@ -1420,6 +1646,7 @@ def test_delete_admin_is_allowed_when_another_usable_admin_remains( created = client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "ops", "password": _PASSWORD, "groups": ["dfe-admins"], @@ -1438,7 +1665,12 @@ def test_delete_own_account_as_last_admin_is_self_delete( store = recovery_accounts.state.account_store created = client.post( "/api/v1/auth/accounts", - json={"username": "ops", "password": _PASSWORD, "groups": ["dfe-admins"]}, + json={ + "name": "Test User", + "username": "ops", + "password": _PASSWORD, + "groups": ["dfe-admins"], + }, headers=admin_headers, ) assert created.status_code == 201, created.text @@ -1506,7 +1738,12 @@ def test_rename_leaves_the_original_in_place( """A rename is a create plus a delete, and the delete is what refuses.""" created = client.post( "/api/v1/auth/accounts", - json={"username": f"{username}-renamed", "password": _PASSWORD, "groups": []}, + json={ + "name": "Test User", + "username": f"{username}-renamed", + "password": _PASSWORD, + "groups": [], + }, headers=admin_headers, ) assert created.status_code == 201 diff --git a/tests/unit/test_api/test_account_links.py b/tests/unit/test_api/test_account_links.py new file mode 100644 index 000000000..2c343e2c4 --- /dev/null +++ b/tests/unit/test_api/test_account_links.py @@ -0,0 +1,234 @@ +# Project: dfe-engine +# File: tests/unit/test_api/test_account_links.py +# Purpose: API tests for accounts that IdP sign-ins are linked to +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +from typing import Any + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from dfe_engine.settings import DFESettings +from tests.support.accounts import session_token +from tests.support.oidc import serve_provider +from tests.unit.test_api.account_links_cases import PROVIDER_TYPES_CASES, ProviderTypesCase +from tests.unit.test_auth.factories import make_link_ticket + +_ACCOUNTS = "/api/v1/auth/accounts" +_EMAIL = "kaz@example.test" +_KEY = "stub-kaz" + + +@pytest.fixture +def linked(app: FastAPI, client: TestClient) -> FastAPI: + """Store the local kaz with the stub sign-in stub-kaz linked to it, its g1 giving data_viewer.""" + serve_provider(app) + app.state.group_store.create( + "stub-viewers", ["data_viewer"], source_provider="stub", source_id="g1" + ) + app.state.account_store.create("kaz", "kaz-local-password-1", email=_EMAIL) + ticket = make_link_ticket( + account="kaz", email=_EMAIL, groups=["g1"], provider="stub", subject=_KEY + ) + app.state.jit_provisioner.complete_link(ticket=ticket) + return app + + +def _provider_types(*, body: dict[str, Any]) -> tuple[str, list[str]]: + """An account read's provider type, then its linked sign-ins' types.""" + return (body["oidc_type"], [identity["provider_type"] for identity in body["identities"]]) + + +def _usernames(*, client: TestClient, headers: dict[str, str]) -> list[str]: + """The account names the list answers with.""" + page = client.get(_ACCOUNTS, headers=headers, params={"limit": 100}).json() + return sorted(item["username"] for item in page["items"]) + + +class TestReads: + def test_the_list_hides_link_records( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + assert _KEY not in _usernames(client=client, headers=admin_headers) + + def test_a_link_record_answers_404( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + resp = client.get(f"{_ACCOUNTS}/{_KEY}", headers=admin_headers) + assert (resp.status_code, resp.json()["code"]) == (404, "not_found") + + def test_the_account_lists_its_sign_ins( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + body = client.get(f"{_ACCOUNTS}/kaz", headers=admin_headers).json() + identities = [ + (i["key"], i["provider"], i["subject"], i["email"]) for i in body["identities"] + ] + assert identities == [(_KEY, "stub", _KEY, _EMAIL)] + + @pytest.mark.parametrize( + "case", PROVIDER_TYPES_CASES, ids=[case["id"] for case in PROVIDER_TYPES_CASES] + ) + def test_provider_types( + self, + admin_headers: dict[str, str], + client: TestClient, + linked: FastAPI, + case: ProviderTypesCase, + ): + linked.state.account_store.update(username="kaz", **case["updates"]) + detail = client.get(f"{_ACCOUNTS}/kaz", headers=admin_headers).json() + page = client.get(_ACCOUNTS, headers=admin_headers, params={"limit": 100}).json() + listed = next(item for item in page["items"] if item["username"] == "kaz") + expected = (case["expected_oidc_type"], case["expected_identity_types"]) + assert (_provider_types(body=detail), _provider_types(body=listed)) == ( + expected, + expected, + ) + + +class TestUnlink: + def test_the_sign_in_becomes_its_own_account( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + resp = client.delete(f"{_ACCOUNTS}/kaz/identities/{_KEY}", headers=admin_headers) + store = linked.state.account_store + assert (resp.status_code, store.get("kaz").identities, store.get(_KEY).linked_to) == ( + 204, + [], + "", + ) + + def test_every_session_of_the_account_ends( + self, + admin_headers: dict[str, str], + api_settings: DFESettings, + client: TestClient, + linked: FastAPI, + ): + token = session_token(linked, api_settings, {"sub": "kaz"}) + client.delete(f"{_ACCOUNTS}/kaz/identities/{_KEY}", headers=admin_headers) + me = client.get("/api/v1/auth/me", headers={"Authorization": f"Bearer {token}"}) + assert (me.status_code, me.json()["code"]) == (401, "session_ended") + + def test_an_unknown_sign_in_answers_404( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + resp = client.delete(f"{_ACCOUNTS}/kaz/identities/no-such-key", headers=admin_headers) + assert (resp.status_code, resp.json()["code"]) == (404, "not_found") + + +class TestDeletes: + def test_deleting_the_account_deletes_its_link_records( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + resp = client.delete(f"{_ACCOUNTS}/kaz", headers=admin_headers) + assert (resp.status_code, linked.state.account_store.get(_KEY)) == (204, None) + + def test_deleting_the_provider_unlinks_and_keeps_the_account( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + resp = client.delete("/api/v1/auth/oidc-providers/stub", headers=admin_headers) + store = linked.state.account_store + kaz = store.get("kaz") + assert (resp.status_code, kaz.enabled, kaz.identities, store.get(_KEY)) == ( + 200, + True, + [], + None, + ) + + +class TestEmailTaken: + def test_a_create_is_refused( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + body = { + "name": "Test User", + "email": _EMAIL.upper(), + "password": "another-password-1", + "username": "kaz2", + } + resp = client.post(_ACCOUNTS, headers=admin_headers, json=body) + assert (resp.status_code, resp.json()["code"]) == (409, "email_taken") + + def test_an_update_is_refused( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + linked.state.account_store.create("kaz2", "another-password-1", email="k2@example.test") + resp = client.put(f"{_ACCOUNTS}/kaz2", headers=admin_headers, json={"email": _EMAIL}) + assert (resp.status_code, resp.json()["code"]) == (409, "email_taken") + + def test_an_admin_set_email_is_vouched_for( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + body = { + "name": "Test User", + "email": "new@example.test", + "password": "another-password-1", + "username": "kaz3", + } + resp = client.post(_ACCOUNTS, headers=admin_headers, json=body) + assert (resp.status_code, resp.json()["email_verified"]) == (201, True) + + def test_an_own_email_edit_is_not_vouched_for( + self, api_settings: DFESettings, client: TestClient, linked: FastAPI + ): + token = session_token(linked, api_settings, {"sub": "kaz"}) + resp = client.put( + f"{_ACCOUNTS}/me", + headers={"Authorization": f"Bearer {token}"}, + json={"email": "kaz-new@example.test"}, + ) + assert (resp.status_code, resp.json()["email_verified"]) == (200, False) + + def test_the_holder_keeps_its_own_email( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + resp = client.put(f"{_ACCOUNTS}/kaz", headers=admin_headers, json={"email": _EMAIL}) + assert resp.status_code == 200 + + +class TestAnIdpAdminCannotDeactivateItself: + @pytest.mark.parametrize( + ("method", "body", "code"), + [("PUT", {"enabled": False}, "self_deactivate"), ("DELETE", None, "self_delete")], + ) + def test_refused( + self, + api_settings: DFESettings, + app: FastAPI, + client: TestClient, + method: str, + body: dict[str, bool] | None, + code: str, + ): + serve_provider(app) + app.state.group_store.create( + "stub-admins", ["admin"], source_provider="stub", source_id="g-admin" + ) + app.state.jit_provisioner.ensure_account( + "Jane@Corp.com", ["g-admin"], "stub", email="jane@corp.com" + ) + token = session_token(app, api_settings, {"sub": "Jane@Corp.com"}) + resp = client.request( + method, + f"{_ACCOUNTS}/jane-corp-com", + headers={"Authorization": f"Bearer {token}"}, + json=body, + ) + assert (resp.status_code, resp.json()["code"]) == (403, code) + + +class TestScim: + def test_users_leave_out_link_records( + self, admin_headers: dict[str, str], client: TestClient, linked: FastAPI + ): + listed = client.get("/api/v1/scim/v2/Users", headers=admin_headers).json() + names = [user["userName"] for user in listed["Resources"]] + one = client.get(f"/api/v1/scim/v2/Users/{_KEY}", headers=admin_headers) + assert (_KEY in names, "kaz" in names, one.status_code) == (False, True, 404) diff --git a/tests/unit/test_api/test_account_org_binding.py b/tests/unit/test_api/test_account_org_binding.py index f96387ca6..9ecee8823 100644 --- a/tests/unit/test_api/test_account_org_binding.py +++ b/tests/unit/test_api/test_account_org_binding.py @@ -40,7 +40,7 @@ def _sign_in(client: TestClient, username: str) -> dict[str, str]: def _create(client: TestClient, admin_headers: dict[str, str], **fields): - body = {"username": "alice", "password": PASSWORD, **fields} + body = {"name": "Test User", "username": "alice", "password": PASSWORD, **fields} return client.post(ACCOUNTS, json=body, headers=admin_headers) @@ -111,7 +111,12 @@ def test_an_update_to_an_unknown_org_is_refused( def _tenant_viewer(app: FastAPI, client: TestClient, admin_headers, *, org: str, grants: list[str]): - """alice, bound to *org*, holding org_viewer system-wide over the orgs in *grants*.""" + """alice, bound to *org*, holding org_viewer system-wide over the orgs in *grants*. + + An account of an org other than yours holds no group reaching another org, so *org* is named your org where *grants* reach past it. + """ + if (org) and (set(grants) != {org}): + app.state.org_registry.home.set(actor="test", name=org) assert _create(client, admin_headers, org=org).status_code == 201 app.state.group_store.create("tenant-viewers", roles=["org_viewer"], members=["alice"]) app.state.group_store.update("tenant-viewers", org_ids=grants) @@ -196,6 +201,7 @@ def test_a_platform_reader_reads_the_org_it_is_bound_to( orgs: None, reader: RecordingClient, ): + app.state.org_registry.home.set(actor="test", name="globex") assert _create(client, admin_headers, org="globex").status_code == 201 app.state.group_store.add_member("dfe-viewers", "alice") app.state.account_store.update("alice", groups=["dfe-viewers"]) diff --git a/tests/unit/test_api/test_account_reauth.py b/tests/unit/test_api/test_account_reauth.py new file mode 100644 index 000000000..0a6f65e51 --- /dev/null +++ b/tests/unit/test_api/test_account_reauth.py @@ -0,0 +1,388 @@ +# Project: dfe-engine +# File: tests/unit/test_api/test_account_reauth.py +# Purpose: API tests for the re-auth grant every access change needs +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +from datetime import timedelta + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from dfe_engine.api.deps import jwt_authority_for +from dfe_engine.auth.bootstrap import admin_account_name +from dfe_engine.auth.identity_links import LINK_TICKET_AUDIENCE +from dfe_engine.auth.reauth import REAUTH_AUDIENCE, REAUTH_HEADER +from dfe_engine.settings import DFESettings +from tests.support.accounts import session_token +from tests.support.reauth import REAUTH_CHECKS +from tests.unit.test_api.conftest import ADMIN_PASSWORD + +ACCOUNTS = "/api/v1/auth/accounts" +API_KEYS = "/api/v1/auth/api-keys" +GROUPS = "/api/v1/auth/groups" +PROVIDERS = "/api/v1/auth/oidc-providers" +REAUTH = "/api/v1/auth/reauth" +RETIRE = "/api/v1/auth/setup/retire-admin" +ROLES = "/api/v1/auth/roles" +SCIM = "/api/v1/scim/v2" +PASSWORD = "reauth-password-1" +SCIM_USER = "urn:ietf:params:scim:schemas:core:2.0:User" +SCIM_GROUP = "urn:ietf:params:scim:schemas:core:2.0:Group" + + +def _account_body(username: str, **fields: object) -> dict[str, object]: + """A create-account body for a local account called *username*.""" + return { + "email": f"{username}@example.test", + "name": username, + "password": PASSWORD, + "username": username, + **fields, + } + + +def _provider_body(name: str) -> dict[str, str]: + """A create-provider body for a generic provider called *name*.""" + return { + "client_id_env": "OIDC_CLIENT_ID", + "display_name": name, + "issuer": "https://accounts.example.com", + "name": name, + "type": "generic", + } + + +# Every access change, as (method, path, body). ``{short_token}`` is bob-key's. +WRITES = [ + pytest.param("POST", ACCOUNTS, _account_body("dave"), id="account-create"), + pytest.param("PUT", f"{ACCOUNTS}/bob", {"name": "Bobby"}, id="account-update"), + pytest.param( + "POST", + f"{ACCOUNTS}/bob/reset-password", + {"new_password": "reset-password-12"}, + id="account-reset", + ), + pytest.param("DELETE", f"{ACCOUNTS}/bob", None, id="account-delete"), + pytest.param("DELETE", f"{ACCOUNTS}/bob/identities/bob-sub", None, id="account-unlink"), + pytest.param( + "POST", + f"{ACCOUNTS}/bob/rotate-password", + {"new_password": "rotated-password-1234567"}, + id="account-rotate", + ), + pytest.param("PUT", f"{ACCOUNTS}/bob/attributes", {"attributes": {}}, id="account-attributes"), + pytest.param( + "PUT", + f"{ACCOUNTS}/bob/sensitive-attributes", + {"attributes": {}}, + id="account-sensitive-attributes", + ), + pytest.param("POST", GROUPS, {"name": "new-team", "roles": []}, id="group-create"), + pytest.param("PUT", f"{GROUPS}/bob-team", {"description": "Bob's"}, id="group-update"), + pytest.param( + "POST", f"{GROUPS}/bob-team/members", {"username": "carol"}, id="group-add-member" + ), + pytest.param("DELETE", f"{GROUPS}/bob-team/members/bob", None, id="group-remove-member"), + pytest.param("DELETE", f"{GROUPS}/bob-team", None, id="group-delete"), + pytest.param("PUT", f"{GROUPS}/bob-team/attributes", {"attributes": {}}, id="group-attributes"), + pytest.param( + "PUT", + f"{GROUPS}/bob-team/sensitive-attributes", + {"attributes": {}}, + id="group-sensitive-attributes", + ), + pytest.param( + "POST", ROLES, {"name": "new-role", "permissions": ["group:read"]}, id="role-create" + ), + pytest.param("PUT", f"{ROLES}/bob-role", {"permissions": ["group:read"]}, id="role-update"), + pytest.param("DELETE", f"{ROLES}/bob-role", None, id="role-delete"), + pytest.param("POST", PROVIDERS, _provider_body("new-idp"), id="provider-create"), + pytest.param("PUT", f"{PROVIDERS}/bob-idp", {"display_name": "Bob"}, id="provider-update"), + pytest.param("DELETE", f"{PROVIDERS}/bob-idp", None, id="provider-delete"), + pytest.param("POST", f"{PROVIDERS}/bob-idp/sync", None, id="provider-sync"), + pytest.param("POST", API_KEYS, {"name": "new-key"}, id="api-key-create"), + pytest.param("DELETE", f"{API_KEYS}/{{short_token}}", None, id="api-key-revoke"), + pytest.param( + "POST", f"{SCIM}/Users", {"schemas": [SCIM_USER], "userName": "erin"}, id="scim-user-create" + ), + pytest.param("PUT", f"{SCIM}/Users/bob", {"schemas": [SCIM_USER]}, id="scim-user-replace"), + pytest.param("PATCH", f"{SCIM}/Users/bob", {"Operations": []}, id="scim-user-patch"), + pytest.param("DELETE", f"{SCIM}/Users/bob", None, id="scim-user-delete"), + pytest.param( + "POST", + f"{SCIM}/Groups", + {"displayName": "scim-team", "schemas": [SCIM_GROUP]}, + id="scim-group-create", + ), + pytest.param( + "PUT", f"{SCIM}/Groups/bob-team", {"schemas": [SCIM_GROUP]}, id="scim-group-replace" + ), + pytest.param("PATCH", f"{SCIM}/Groups/bob-team", {"Operations": []}, id="scim-group-patch"), + pytest.param("DELETE", f"{SCIM}/Groups/bob-team", None, id="scim-group-delete"), +] + +# A change of each kind, as (kind, target, method, path, body). +OPENED = [ + pytest.param("account", "dave", "POST", ACCOUNTS, _account_body("dave"), id="account-create"), + pytest.param("account", "bob", "PUT", f"{ACCOUNTS}/bob", {"name": "Bobby"}, id="account"), + pytest.param( + "group", "bob-team", "PUT", f"{GROUPS}/bob-team", {"description": "B"}, id="group" + ), + pytest.param( + "role", + "new-role", + "POST", + ROLES, + {"name": "new-role", "permissions": ["group:read"]}, + id="role-create", + ), + pytest.param("role", "bob-role", "DELETE", f"{ROLES}/bob-role", None, id="role"), + pytest.param( + "provider", "new-idp", "POST", PROVIDERS, _provider_body("new-idp"), id="provider-create" + ), + pytest.param("provider", "bob-idp", "DELETE", f"{PROVIDERS}/bob-idp", None, id="provider"), + pytest.param("api_key", "new-key", "POST", API_KEYS, {"name": "new-key"}, id="api-key-create"), + pytest.param( + "api_key", "{short_token}", "DELETE", f"{API_KEYS}/{{short_token}}", None, id="api-key" + ), + pytest.param( + "account", + "erin", + "POST", + f"{SCIM}/Users", + {"schemas": [SCIM_USER], "userName": "erin"}, + id="scim-user-create", + ), + pytest.param("account", "bob", "DELETE", f"{SCIM}/Users/bob", None, id="scim-user"), + pytest.param("group", "bob-team", "DELETE", f"{SCIM}/Groups/bob-team", None, id="scim-group"), +] + + +def _grant( + *, + client: TestClient, + headers: dict[str, str], + kind: str = "account", + password: str, + target: str, +) -> str: + """The grant the caller behind *headers* earns for the *kind* named *target* with *password*.""" + body = {"kind": kind, "password": password, "target": target} + resp = client.post(REAUTH, headers=headers, json=body) + assert resp.status_code == 200, resp.text + return resp.json()["grant"] + + +def _hold_to_grants(*, app: FastAPI) -> None: + """Lift the test app's re-auth waiver, so every access change needs its grant.""" + for check in REAUTH_CHECKS: + app.dependency_overrides.pop(check, None) + + +@pytest.fixture +def short_token(admin_headers: dict[str, str], app: FastAPI, client: TestClient) -> str: + """Store bob, carol, bob-team, bob-role, bob-idp and bob-key, then hold every access change to its grant.""" + for username in ("bob", "carol"): + resp = client.post(ACCOUNTS, headers=admin_headers, json=_account_body(username)) + assert resp.status_code == 201, resp.text + app.state.group_store.create("bob-team", [], members=["bob"]) + seeds = [ + (ROLES, {"name": "bob-role", "permissions": ["group:read"]}), + (PROVIDERS, _provider_body("bob-idp")), + (API_KEYS, {"name": "bob-key"}), + ] + for path, body in seeds: + resp = client.post(path, headers=admin_headers, json=body) + assert resp.status_code in (200, 201), resp.text + token = resp.json()["short_token"] + _hold_to_grants(app=app) + return token + + +class TestAccessReauth: + @pytest.mark.parametrize(("method", "path", "body"), WRITES) + def test_a_change_without_a_grant_is_refused( + self, + admin_headers: dict[str, str], + client: TestClient, + short_token: str, + method: str, + path: str, + body: dict | None, + ): + resp = client.request( + method, path.format(short_token=short_token), headers=admin_headers, json=body + ) + assert (resp.status_code, resp.json().get("code")) == (403, "reauth_required"), resp.text + + @pytest.mark.parametrize(("kind", "target", "method", "path", "body"), OPENED) + def test_a_grant_for_the_target_opens_it( + self, + admin_headers: dict[str, str], + client: TestClient, + short_token: str, + kind: str, + target: str, + method: str, + path: str, + body: dict | None, + ): + grant = _grant( + client=client, + headers=admin_headers, + kind=kind, + password=ADMIN_PASSWORD, + target=target.format(short_token=short_token), + ) + resp = client.request( + method, + path.format(short_token=short_token), + headers={**admin_headers, REAUTH_HEADER: grant}, + json=body, + ) + assert resp.status_code < 300, resp.text + + @pytest.mark.parametrize( + ("kind", "expected_status"), [("group", 200), ("account", 403)], ids=["group", "account"] + ) + def test_only_a_grant_of_the_right_kind_opens_it( + self, + admin_headers: dict[str, str], + client: TestClient, + short_token: str, + kind: str, + expected_status: int, + ): + grant = _grant( + client=client, + headers=admin_headers, + kind=kind, + password=ADMIN_PASSWORD, + target="bob-team", + ) + resp = client.put( + f"{GROUPS}/bob-team", + headers={**admin_headers, REAUTH_HEADER: grant}, + json={"description": "Bob's"}, + ) + assert resp.status_code == expected_status, resp.text + + def test_a_grant_for_another_target_is_refused( + self, admin_headers: dict[str, str], client: TestClient, short_token: str + ): + grant = _grant( + client=client, headers=admin_headers, password=ADMIN_PASSWORD, target="carol" + ) + resp = client.put( + f"{ACCOUNTS}/bob", + headers={**admin_headers, REAUTH_HEADER: grant}, + json={"name": "Bobby"}, + ) + assert (resp.status_code, resp.json().get("code")) == (403, "reauth_required"), resp.text + + def test_another_callers_grant_is_refused( + self, + admin_headers: dict[str, str], + client: TestClient, + operator_headers: dict[str, str], + short_token: str, + ): + grant = _grant( + client=client, headers=operator_headers, password="test-operator-pw", target="bob" + ) + resp = client.put( + f"{ACCOUNTS}/bob", + headers={**admin_headers, REAUTH_HEADER: grant}, + json={"name": "Bobby"}, + ) + assert (resp.status_code, resp.json().get("code")) == (403, "reauth_required"), resp.text + + @pytest.mark.parametrize( + ("audience", "lifetime"), + [(REAUTH_AUDIENCE, timedelta(minutes=-10)), (LINK_TICKET_AUDIENCE, timedelta(minutes=5))], + ids=["expired", "another_audience"], + ) + def test_a_token_that_is_no_live_grant_is_refused( + self, + admin_headers: dict[str, str], + api_settings: DFESettings, + client: TestClient, + short_token: str, + audience: str, + lifetime: timedelta, + ): + claims = {"aud": audience, "sub": "admin", "target": "bob"} + token = jwt_authority_for(api_settings).sign(claims=claims, expires_delta=lifetime) + resp = client.put( + f"{ACCOUNTS}/bob", + headers={**admin_headers, REAUTH_HEADER: token}, + json={"name": "Bobby"}, + ) + assert (resp.status_code, resp.json().get("code")) == (403, "reauth_required"), resp.text + + def test_a_wrong_password_earns_nothing( + self, admin_headers: dict[str, str], client: TestClient, short_token: str + ): + resp = client.post( + REAUTH, headers=admin_headers, json={"password": "not-the-password", "target": "bob"} + ) + assert (resp.status_code, resp.json()["code"]) == (403, "invalid_password") + + def test_an_identity_providers_account_is_sent_to_its_provider( + self, api_settings: DFESettings, app: FastAPI, client: TestClient, short_token: str + ): + accounts = app.state.account_store + accounts.create("ida", "", groups=[]) + accounts.update("ida", external=True, source_provider="scim", subject="ida") + token = session_token(app, api_settings, {"sub": "ida"}) + resp = client.post( + REAUTH, + headers={"Authorization": f"Bearer {token}"}, + json={"password": "anything", "target": "bob"}, + ) + assert (resp.status_code, resp.json()["code"]) == (409, "reauth_via_idp") + + def test_an_api_key_needs_no_grant(self, app: FastAPI, client: TestClient, short_token: str): + _, key = app.state.api_key_store.create("ops-key", groups=["dfe-admins"]) + resp = client.put(f"{ACCOUNTS}/bob", headers={"X-API-Key": key}, json={"name": "Bobby"}) + assert resp.status_code == 200, resp.text + + +class TestRetireAdminReauth: + @pytest.mark.parametrize( + ("granted", "expected_reauth_required"), + [(False, True), (True, False)], + ids=["no_grant", "grant"], + ) + def test_another_admin_needs_a_grant( + self, + admin_headers: dict[str, str], + api_settings: DFESettings, + app: FastAPI, + client: TestClient, + granted: bool, + expected_reauth_required: bool, + ): + body = _account_body("ada", groups=["dfe-admins"]) + resp = client.post(ACCOUNTS, headers=admin_headers, json=body) + assert resp.status_code == 201, resp.text + _hold_to_grants(app=app) + headers = {"Authorization": f"Bearer {session_token(app, api_settings, {'sub': 'ada'})}"} + if granted: + target = admin_account_name(api_settings.auth.local.admin_name) + headers[REAUTH_HEADER] = _grant( + client=client, headers=headers, password=PASSWORD, target=target + ) + resp = client.post(RETIRE, headers=headers) + assert (resp.json().get("code") == "reauth_required") is expected_reauth_required, resp.text + + def test_the_admin_retiring_itself_needs_none( + self, admin_headers: dict[str, str], app: FastAPI, client: TestClient + ): + _hold_to_grants(app=app) + resp = client.post(RETIRE, headers=admin_headers) + assert resp.json().get("code") != "reauth_required", resp.text diff --git a/tests/unit/test_api/test_account_routes_need_roles.py b/tests/unit/test_api/test_account_routes_need_roles.py index d234377a4..f87dc4eda 100644 --- a/tests/unit/test_api/test_account_routes_need_roles.py +++ b/tests/unit/test_api/test_account_routes_need_roles.py @@ -58,7 +58,12 @@ class TestAnAccountsGroupsNeedTheirRoles: def test_creating_an_account_in_the_admin_group_is_refused(self, client, app, mgr): resp = client.post( ACCOUNTS, - json={"username": "mallory", "password": _PASSWORD, "groups": ["dfe-admins"]}, + json={ + "name": "Test User", + "username": "mallory", + "password": _PASSWORD, + "groups": ["dfe-admins"], + }, headers=mgr, ) @@ -147,7 +152,12 @@ def test_a_roleless_group_is_accepted_for_an_idp_account( def test_groups_whose_roles_the_caller_holds_are_accepted(self, client, app, mgr): resp = client.post( ACCOUNTS, - json={"username": "helper", "password": _PASSWORD, "groups": ["account-managers"]}, + json={ + "name": "Test User", + "username": "helper", + "password": _PASSWORD, + "groups": ["account-managers"], + }, headers=mgr, ) @@ -157,7 +167,12 @@ def test_groups_whose_roles_the_caller_holds_are_accepted(self, client, app, mgr def test_admin_still_puts_an_account_into_the_admin_group(self, client, app, admin_headers): resp = client.post( ACCOUNTS, - json={"username": "second", "password": _PASSWORD, "groups": ["dfe-admins"]}, + json={ + "name": "Test User", + "username": "second", + "password": _PASSWORD, + "groups": ["dfe-admins"], + }, headers=admin_headers, ) @@ -276,7 +291,9 @@ def test_a_recreated_account_inherits_nothing( ): deleted = client.delete(path, headers=admin_headers) recreated = client.post( - ACCOUNTS, json={"username": "ghost", "password": _PASSWORD}, headers=admin_headers + ACCOUNTS, + json={"name": "Test User", "username": "ghost", "password": _PASSWORD}, + headers=admin_headers, ) assert deleted.status_code == 204, deleted.text diff --git a/tests/unit/test_api/test_admin_change_audit.py b/tests/unit/test_api/test_admin_change_audit.py index d9cb4d46b..9b2ec9778 100644 --- a/tests/unit/test_api/test_admin_change_audit.py +++ b/tests/unit/test_api/test_admin_change_audit.py @@ -59,7 +59,12 @@ def _group(app, members: list[str] | None = None) -> None: def _create_account(client, app, admin, viewer) -> Outcome: password = secrets.token_urlsafe(16) - body = {"username": ACCOUNT, "password": password, "groups": ["dfe-viewers"]} + body = { + "name": "Test User", + "username": ACCOUNT, + "password": password, + "groups": ["dfe-viewers"], + } resp = client.post("/api/v1/auth/accounts", json=body, headers=admin) return Outcome(resp.status_code, [password, _hash(app, ACCOUNT)]) diff --git a/tests/unit/test_api/test_api_key_org_binding.py b/tests/unit/test_api/test_api_key_org_binding.py index 05d0a7159..077b09e80 100644 --- a/tests/unit/test_api/test_api_key_org_binding.py +++ b/tests/unit/test_api/test_api_key_org_binding.py @@ -80,6 +80,8 @@ def test_a_key_bound_to_an_org_its_groups_do_not_grant_is_refused( orgs: None, reader: RecordingClient, ): + # A key bound to any org but yours may not be minted with a group reaching acme at all. + app.state.org_registry.home.set(actor="test", name="globex") created = _key(client, admin_headers, app, org="globex") assert created.status_code == 201, created.text diff --git a/tests/unit/test_api/test_attributes_api.py b/tests/unit/test_api/test_attributes_api.py index 6d7457794..c1d997106 100644 --- a/tests/unit/test_api/test_attributes_api.py +++ b/tests/unit/test_api/test_attributes_api.py @@ -30,6 +30,7 @@ def _make_account(self, client, admin_headers, username: str) -> None: client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": username, "password": secrets.token_urlsafe(16), "email": f"{username}@example.com", @@ -170,6 +171,7 @@ def targets(self, client, admin_headers) -> list[str]: client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "deepuser", "password": secrets.token_urlsafe(16), "email": "deepuser@example.com", diff --git a/tests/unit/test_api/test_auth.py b/tests/unit/test_api/test_auth.py index c02d657ea..8ac33d30d 100644 --- a/tests/unit/test_api/test_auth.py +++ b/tests/unit/test_api/test_auth.py @@ -82,6 +82,14 @@ def test_login_success(self, client: TestClient): assert "admin" in data["roles"] assert data["expires_in"] == 30 * 60 + def test_a_local_account_signs_in_with_its_email(self, app, client: TestClient): + app.state.account_store.create("emailuser", "email-user-pw-1", email="Email.User@corp.com") + resp = client.post( + "/api/v1/auth/login", + json={"username": "email.user@corp.com", "password": "email-user-pw-1"}, + ) + assert (resp.status_code, resp.json()["user_id"]) == (200, "emailuser") + def test_login_bad_password(self, client: TestClient): resp = client.post( "/api/v1/auth/login", @@ -468,6 +476,7 @@ def test_me_ignores_stale_jwt_when_account_has_no_groups( client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "nogrp", "password": secrets.token_urlsafe(16), "email": "nogrp@example.com", @@ -627,6 +636,7 @@ def test_a_session_with_no_groups_has_no_identity( client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "hdx-nogrp", "password": secrets.token_urlsafe(16), "email": "hdx-nogrp@example.com", @@ -756,7 +766,7 @@ def test_a_bound_idp_user_gets_its_accounts_roles(self, client: TestClient, app, def test_a_scim_adopted_local_login_whose_subject_differs_is_unbound( self, client: TestClient, app ): - """Login answers with roles, but no account backs the session, so its token is refused.""" + """Login answers, but no account backs the session, so it carries no role and its token is refused.""" password = secrets.token_urlsafe(16) store = app.state.account_store store.create("bob", password, groups=["dfe-analysts"]) @@ -769,7 +779,7 @@ def test_a_scim_adopted_local_login_whose_subject_differs_is_unbound( refreshed = client.post("/api/v1/auth/refresh", headers=headers) assert login.status_code == 200, login.text - assert login.json()["roles"] == ["data_analyst"] + assert login.json()["roles"] == [] assert me.status_code == 401, me.text assert me.json()["code"] == "session_ended" assert refreshed.status_code == 401, refreshed.text diff --git a/tests/unit/test_api/test_auth_setup_status.py b/tests/unit/test_api/test_auth_setup_status.py index d4736d4fd..a78d03e57 100644 --- a/tests/unit/test_api/test_auth_setup_status.py +++ b/tests/unit/test_api/test_auth_setup_status.py @@ -14,7 +14,6 @@ from ruamel.yaml import YAML from dfe_engine import yaml_utils -from dfe_engine.api.app import create_app from dfe_engine.api.deps import _registries from dfe_engine.auth import breakglass from dfe_engine.auth.accounts import Account @@ -37,6 +36,7 @@ SourceSettings, ) from tests.support.orgs import name_your_org +from tests.support.reauth import create_app_without_reauth def _settings(tmp_path: Path) -> DFESettings: @@ -95,7 +95,7 @@ def _complete_setup(app) -> None: def test_setup_status_public_and_incomplete_on_fresh_bootstrap(tmp_path): - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: resp = client.get("/api/v1/auth/setup-status") @@ -129,7 +129,7 @@ def _change_admin_password(client: TestClient, new_password: str) -> None: def test_the_forced_change_clears_default_credentials_without_a_restart(tmp_path): """Login, refresh and setup-status all answer from the admin's current password.""" owner_password = secrets.token_urlsafe(16) - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: body = client.get("/api/v1/auth/setup-status").json() @@ -159,11 +159,15 @@ def test_a_restart_keeps_the_owners_password_and_the_cleared_flag(tmp_path): settings = _settings(tmp_path) owner_password = secrets.token_urlsafe(16) try: - with TestClient(create_app(settings=settings), raise_server_exceptions=False) as client: + with TestClient( + create_app_without_reauth(settings=settings), raise_server_exceptions=False + ) as client: _change_admin_password(client, owner_password) _registries.clear() - with TestClient(create_app(settings=settings), raise_server_exceptions=False) as client: + with TestClient( + create_app_without_reauth(settings=settings), raise_server_exceptions=False + ) as client: stale = client.post( "/api/v1/auth/login", json={"username": "admin", "password": SHIPPED_DEFAULT} ) @@ -180,7 +184,7 @@ def test_a_restart_keeps_the_owners_password_and_the_cleared_flag(tmp_path): def test_an_admin_issued_the_default_again_is_flagged_again(tmp_path): """A store write that issues the default puts the flag back on the next read.""" - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: _change_admin_password(client, secrets.token_urlsafe(16)) @@ -198,7 +202,7 @@ def test_setup_status_carries_the_deploy_kind_and_fetch_command(tmp_path): settings = _settings(tmp_path) settings.deployment.target = "kubernetes" settings.deployment.namespace = "dfe" - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: body = client.get("/api/v1/auth/setup-status").json() @@ -216,7 +220,7 @@ def test_setup_status_carries_the_deploy_kind_and_fetch_command(tmp_path): def test_default_credentials_clears_once_the_password_is_minted(tmp_path): settings = _settings(tmp_path) settings.auth.local.admin_password = MINTED_ADMIN - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: assert client.get("/api/v1/auth/setup-status").json()["default_credentials"] is False @@ -231,7 +235,7 @@ def test_default_credentials_clears_once_the_password_is_minted(tmp_path): def test_login_on_the_default_password_flags_the_session(tmp_path): - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: token = client.post( @@ -250,7 +254,7 @@ def test_setup_status_reports_auth_steps_even_when_auth_is_disabled(tmp_path): ``bootstrap_auth`` runs unconditionally and ``POST /auth/login`` never checks the toggle, so the wizard must still call for the first real user. """ - app = create_app(settings=_settings_auth_disabled(tmp_path)) + app = create_app_without_reauth(settings=_settings_auth_disabled(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: setup = client.get("/api/v1/auth/setup-status").json()["initial_setup"] @@ -263,7 +267,7 @@ def test_setup_status_reports_auth_steps_even_when_auth_is_disabled(tmp_path): def test_setup_status_step_details_carry_required_and_complete(tmp_path): - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: name_your_org(app=app) @@ -282,7 +286,7 @@ def test_setup_status_step_details_carry_required_and_complete(tmp_path): def test_setup_status_complete_when_all_required_steps_done(tmp_path): - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: _complete_setup(app) @@ -300,7 +304,7 @@ def test_setup_status_complete_when_all_required_steps_done(tmp_path): def test_setup_stays_complete_once_finished(tmp_path): """Deleting the last user, then restarting, never reopens the wizard.""" settings = _settings(tmp_path) - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: _complete_setup(app) @@ -315,7 +319,9 @@ def test_setup_stays_complete_once_finished(tmp_path): assert setup["completed_steps"] == ["organisations"] _registries.clear() - with TestClient(create_app(settings=settings), raise_server_exceptions=False) as client: + with TestClient( + create_app_without_reauth(settings=settings), raise_server_exceptions=False + ) as client: assert client.get("/api/v1/auth/setup-status").json()["initial_setup"]["complete"] finally: _registries.clear() @@ -323,7 +329,7 @@ def test_setup_stays_complete_once_finished(tmp_path): def test_setup_stays_open_until_it_finishes(tmp_path): """An org with no user records nothing, so deleting it leaves the wizard where it was.""" - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: app.state.org_registry.create("acme", display_name="Acme") @@ -339,7 +345,7 @@ def test_setup_stays_open_until_it_finishes(tmp_path): def test_setup_status_partial_completion(tmp_path): - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: name_your_org(app=app) @@ -354,7 +360,7 @@ def test_setup_status_partial_completion(tmp_path): def test_setup_status_returns_registries_while_incomplete(tmp_path): - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: # No real user yet, so the wizard still has a step to render these for. @@ -371,7 +377,7 @@ def test_setup_status_returns_registries_while_incomplete(tmp_path): def test_an_org_created_through_the_api_is_listed_until_setup_completes(tmp_path): """The console's order: create the organisation, then the first user.""" - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: owner_password = secrets.token_urlsafe(16) @@ -402,7 +408,11 @@ def test_an_org_created_through_the_api_is_listed_until_setup_completes(tmp_path user = client.post( "/api/v1/auth/accounts", - json={"username": "alexops", "password": secrets.token_urlsafe(16)}, + json={ + "name": "Test User", + "username": "alexops", + "password": secrets.token_urlsafe(16), + }, headers=admin, ) assert user.status_code in (200, 201), user.text @@ -421,7 +431,7 @@ def test_an_org_created_through_the_api_is_listed_until_setup_completes(tmp_path def test_setup_status_never_returns_accounts(tmp_path): """The account list is not served pre-login -- only the first_user verdict is.""" - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: app.state.account_store.create("alice", "a-strong-user-password") @@ -436,7 +446,7 @@ def test_setup_status_never_returns_accounts(tmp_path): def test_setup_status_withholds_registries_once_complete(tmp_path): - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: _complete_setup(app) @@ -453,7 +463,7 @@ def test_break_glass_logs_in_from_the_committed_hash(tmp_path): """The hash in governance settings is what the recovery login verifies against.""" settings = _with_deploy_repo(_settings(tmp_path), tmp_path) settings.auth.local.breakglass_password = MINTED_BREAKGLASS - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: resp = client.post( @@ -470,7 +480,7 @@ def test_break_glass_logs_in_from_the_committed_hash(tmp_path): def test_disabled_break_glass_login_is_403_with_a_reason(tmp_path): settings = _with_deploy_repo(_settings(tmp_path), tmp_path) settings.auth.local.breakglass_password = MINTED_BREAKGLASS - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: breakglass.set_enabled(_deploy_repo_crud(tmp_path), False, "tester") @@ -493,7 +503,7 @@ def test_disabled_break_glass_login_is_403_with_a_reason(tmp_path): def test_setup_status_keeps_oidc_login_options_once_complete(tmp_path): """Post-setup the login screen still gets the enabled IdPs -- name + label only.""" - app = create_app(settings=_settings(tmp_path)) + app = create_app_without_reauth(settings=_settings(tmp_path)) try: with TestClient(app, raise_server_exceptions=False) as client: app.state.oidc_provider_registry.create( @@ -531,7 +541,7 @@ def test_setup_status_does_not_reparse_unchanged_account_files(tmp_path, monkeyp every file's parse from the last call, parsing again only a file that changed. """ settings = _with_deploy_repo(_settings(tmp_path), tmp_path) - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: name_your_org(app=app) diff --git a/tests/unit/test_api/test_deps.py b/tests/unit/test_api/test_deps.py new file mode 100644 index 000000000..4e2447c13 --- /dev/null +++ b/tests/unit/test_api/test_deps.py @@ -0,0 +1,32 @@ +# Project: dfe-engine +# File: tests/unit/test_api/test_deps.py +# Purpose: Unit tests for the api.deps session lookups +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +from pathlib import Path + +import pytest + +from dfe_engine.api.deps import account_for_session_subject +from tests.unit.test_api.deps_cases import ( + ACCOUNT_FOR_SESSION_SUBJECT_CASES, + AccountForSessionSubjectCase, +) +from tests.unit.test_auth.factories import make_account_store + + +class TestAccountForSessionSubject: + @pytest.mark.parametrize( + "case", + ACCOUNT_FOR_SESSION_SUBJECT_CASES, + ids=[case["id"] for case in ACCOUNT_FOR_SESSION_SUBJECT_CASES], + ) + def test_matches_expected(self, tmp_path: Path, case: AccountForSessionSubjectCase): + store = make_account_store(directory=tmp_path) + for account in case["stored"]: + store.put(account=account) + bound = account_for_session_subject(store=store, user_id=case["subject"]) + assert getattr(bound, "username", None) == case["expected_username"] diff --git a/tests/unit/test_api/test_group_crud.py b/tests/unit/test_api/test_group_crud.py index d966b43ab..131566118 100644 --- a/tests/unit/test_api/test_group_crud.py +++ b/tests/unit/test_api/test_group_crud.py @@ -413,11 +413,11 @@ class TestJoiningAnOrgGroupNeedsItsRolesInThatOrg: @pytest.fixture def acme(self, client, app, admin_headers, api_settings) -> dict[str, dict[str, str]]: - """acme-admins (admin) and acme-infra (infra_admin), each with one member.""" + """acme-ops (admin) and acme-infra (infra_admin), each with one member.""" resp = client.post("/api/v1/orgs", json={"name": "acme"}, headers=admin_headers) assert resp.status_code == 201, resp.text for username, group, role in ( - ("orgadmin", "acme-admins", "admin"), + ("orgadmin", "acme-ops", "admin"), ("orgop", "acme-infra", "infra_admin"), ): app.state.account_store.create(username, secrets.token_urlsafe(16)) @@ -431,19 +431,19 @@ def acme(self, client, app, admin_headers, api_settings) -> dict[str, dict[str, def test_an_org_infra_admin_cannot_join_the_org_admins(self, client, app, acme): by_post = client.post( - "/api/v1/auth/groups/acme-admins/members", + "/api/v1/auth/groups/acme-ops/members", json={"username": "orgop"}, headers=acme["orgop"], ) by_put = client.put( - "/api/v1/auth/groups/acme-admins", + "/api/v1/auth/groups/acme-ops", json={"members": ["orgadmin", "orgop"]}, headers=acme["orgop"], ) assert by_post.status_code == 403, by_post.text assert by_put.status_code == 403, by_put.text - assert app.state.group_store.get("acme-admins").members == ["orgadmin"] + assert app.state.group_store.get("acme-ops").members == ["orgadmin"] def test_an_admin_of_another_org_cannot_join_the_org_admins( self, client, app, admin_headers, api_settings, acme @@ -453,7 +453,7 @@ def test_an_admin_of_another_org_cannot_join_the_org_admins( assert resp.status_code == 201, resp.text app.state.account_store.create("crosser", secrets.token_urlsafe(16)) app.state.group_store.create( - "globex-admins", ["admin"], members=["crosser"], scope="org:globex" + "globex-ops", ["admin"], members=["crosser"], scope="org:globex" ) app.state.group_store.add_member("acme-infra", "crosser") headers = { @@ -461,13 +461,13 @@ def test_an_admin_of_another_org_cannot_join_the_org_admins( } resp = client.post( - "/api/v1/auth/groups/acme-admins/members", + "/api/v1/auth/groups/acme-ops/members", json={"username": "crosser"}, headers=headers, ) assert resp.status_code == 403, resp.text - assert "crosser" not in app.state.group_store.get("acme-admins").members + assert "crosser" not in app.state.group_store.get("acme-ops").members created = client.post( "/api/v1/auth/groups", json={"name": "acme-own", "roles": ["admin"], "scope": "org:acme"}, @@ -477,31 +477,27 @@ def test_an_admin_of_another_org_cannot_join_the_org_admins( def test_the_org_admin_still_adds_a_member(self, client, app, acme): resp = client.post( - "/api/v1/auth/groups/acme-admins/members", + "/api/v1/auth/groups/acme-ops/members", json={"username": "orgop"}, headers=acme["orgadmin"], ) assert resp.status_code == 200, resp.text - assert "orgop" in app.state.group_store.get("acme-admins").members + assert "orgop" in app.state.group_store.get("acme-ops").members def test_an_org_infra_admin_cannot_remove_the_org_admin(self, client, app, acme): - resp = client.delete( - "/api/v1/auth/groups/acme-admins/members/orgadmin", headers=acme["orgop"] - ) + resp = client.delete("/api/v1/auth/groups/acme-ops/members/orgadmin", headers=acme["orgop"]) assert resp.status_code == 403, resp.text - assert app.state.group_store.get("acme-admins").members == ["orgadmin"] + assert app.state.group_store.get("acme-ops").members == ["orgadmin"] def test_the_org_admin_still_removes_a_member(self, client, app, acme): - app.state.group_store.add_member("acme-admins", "orgop") + app.state.group_store.add_member("acme-ops", "orgop") - resp = client.delete( - "/api/v1/auth/groups/acme-admins/members/orgop", headers=acme["orgadmin"] - ) + resp = client.delete("/api/v1/auth/groups/acme-ops/members/orgop", headers=acme["orgadmin"]) assert resp.status_code == 200, resp.text - assert app.state.group_store.get("acme-admins").members == ["orgadmin"] + assert app.state.group_store.get("acme-ops").members == ["orgadmin"] class TestScimJoinsNeedTheGroupsRoles: @@ -1797,6 +1793,7 @@ def test_update_members_syncs_account_groups(self, client, admin_headers): client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "memsync-user", "password": secrets.token_urlsafe(16), "email": "memsync-user@example.com", @@ -1828,6 +1825,7 @@ def test_remove_member_syncs_account_groups(self, client, admin_headers): client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "rm-sync-user", "password": secrets.token_urlsafe(16), "email": "rm-sync-user@example.com", @@ -2048,6 +2046,7 @@ def test_remove_member_is_refused_when_sole_usable_admin( created = client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "ops", "password": secrets.token_urlsafe(16), "groups": ["dfe-admins"], @@ -2083,6 +2082,7 @@ def test_remove_member_is_allowed_when_another_usable_admin_remains( created = client.post( "/api/v1/auth/accounts", json={ + "name": "Test User", "username": "ops", "password": secrets.token_urlsafe(16), "groups": ["dfe-admins"], @@ -2096,3 +2096,45 @@ def test_remove_member_is_allowed_when_another_usable_admin_remains( ) assert resp.status_code == 200, resp.text assert "ops" not in recovery_accounts.state.group_store.get("dfe-admins").members + + +class TestLinkedMembers: + @pytest.fixture + def linked(self, app: FastAPI) -> None: + """Link dfe-viewers to Okta's 00g-viewers, whose sign-ins ivy and olga assert, with olga also a stored member.""" + app.state.group_store.update( + name="dfe-viewers", source_id="00g-viewers", source_provider="okta" + ) + for username in ("ivy", "olga"): + app.state.account_store.create(groups=["00g-viewers"], password="", username=username) + app.state.account_store.update(external=True, source_provider="okta", username=username) + app.state.group_store.add_member(group_name="dfe-viewers", username="olga") + + @pytest.mark.parametrize( + "path", + ["/api/v1/auth/groups?page_size=100", "/api/v1/auth/groups/dfe-viewers"], + ids=["list", "detail"], + ) + def test_a_link_holder_is_listed_apart_from_the_stored_members( + self, admin_headers: dict[str, str], client: TestClient, linked: None, path: str + ): + body = client.get(path, headers=admin_headers).json() + groups = body["items"] if "items" in body else [body] + group = next(item for item in groups if item["name"] == "dfe-viewers") + assert (group["linked_members"], "olga" in group["members"], "ivy" in group["members"]) == ( + ["ivy"], + True, + False, + ) + + def test_a_members_write_never_stores_a_link_holder( + self, admin_headers: dict[str, str], app: FastAPI, client: TestClient, linked: None + ): + group = client.get("/api/v1/auth/groups/dfe-viewers", headers=admin_headers).json() + resp = client.put( + "/api/v1/auth/groups/dfe-viewers", + headers=admin_headers, + json={"members": group["members"]}, + ) + assert resp.status_code == 200, resp.text + assert "ivy" not in app.state.group_store.get("dfe-viewers").members diff --git a/tests/unit/test_api/test_group_scope_probe.py b/tests/unit/test_api/test_group_scope_probe.py index 6ddf3b4cd..c8b4140a4 100644 --- a/tests/unit/test_api/test_group_scope_probe.py +++ b/tests/unit/test_api/test_group_scope_probe.py @@ -35,7 +35,7 @@ def orgadmin( assert resp.status_code == 201, resp.text app.state.account_store.create("orgadmin", "pw-orgadmin-123456") for body in ( - {"name": "acme-admins", "roles": ["admin"], "scope": "org:acme", "members": ["orgadmin"]}, + {"name": "acme-ops", "roles": ["admin"], "scope": "org:acme", "members": ["orgadmin"]}, {"name": "acme-eng", "roles": ["data_viewer"], "scope": "org:acme"}, {"name": "globex-analysts", "roles": ["data_analyst"], "scope": "org:globex"}, { diff --git a/tests/unit/test_api/test_ingest_credentials.py b/tests/unit/test_api/test_ingest_credentials.py index 86f79d40b..827b8c18d 100644 --- a/tests/unit/test_api/test_ingest_credentials.py +++ b/tests/unit/test_api/test_ingest_credentials.py @@ -323,7 +323,7 @@ def acme_admin(client, app, admin_headers, api_settings, orgs) -> dict[str, str] resp = client.post( "/api/v1/auth/groups", json={ - "name": "acme-admins", + "name": "acme-ops", "roles": ["admin"], "scope": "org:acme", "members": ["acme-admin"], diff --git a/tests/unit/test_api/test_login_audit.py b/tests/unit/test_api/test_login_audit.py index 2c63e1867..a63bf52ed 100644 --- a/tests/unit/test_api/test_login_audit.py +++ b/tests/unit/test_api/test_login_audit.py @@ -46,6 +46,7 @@ def has_provider(self, name: str) -> bool: async def handle_callback(self, provider: str, request) -> NormalizedIdentity: return NormalizedIdentity( + email_verified=True, subject="alice@example.com", email="alice@example.com", groups=["dfe-admins"], diff --git a/tests/unit/test_api/test_login_backoff.py b/tests/unit/test_api/test_login_backoff.py index c62298bb2..fcdc6f2ba 100644 --- a/tests/unit/test_api/test_login_backoff.py +++ b/tests/unit/test_api/test_login_backoff.py @@ -49,6 +49,16 @@ def test_five_failures_make_the_next_attempt_wait(client, app, audit_events): ) +def test_failures_by_email_count_against_the_account_name(client, app): + password = secrets.token_urlsafe(16) + app.state.account_store.create("carol", password, email="carol@corp.com") + failures = [_attempt(client, "Carol@corp.com", "wrong-password").status_code for _ in range(5)] + + waiting = _attempt(client, "carol", password) + + assert (failures, waiting.status_code) == ([401] * 5, 429) + + def test_a_waiting_attempt_checks_no_password(client, app, monkeypatch): _account(app) for _ in range(5): diff --git a/tests/unit/test_api/test_loop_stays_free.py b/tests/unit/test_api/test_loop_stays_free.py index bd03b8c57..926d53987 100644 --- a/tests/unit/test_api/test_loop_stays_free.py +++ b/tests/unit/test_api/test_loop_stays_free.py @@ -47,6 +47,7 @@ ) from dfe_engine.api.write_turn import WRITE_TURN from dfe_engine.source import catalogue as source_catalogue_module +from tests.support.reauth import waive_reauth from .test_e2e_server import ( _ADMIN_OWN_PASSWORD, @@ -122,8 +123,12 @@ def parked(*args, **kwargs): def seeded(tmp_path): """An e2e-server process over a Kubernetes-shaped deploy repo, with every seed applied.""" _stood_up_as_on_kubernetes(tmp_path / "deploy") - app = create_app( - settings=_settings(tmp_path, e2e_server=True, gitops=True, deployment_target="kubernetes") + app = waive_reauth( + create_app( + settings=_settings( + tmp_path, e2e_server=True, gitops=True, deployment_target="kubernetes" + ) + ) ) try: with TestClient(app, raise_server_exceptions=False) as client: diff --git a/tests/unit/test_api/test_no_backend_error_text.py b/tests/unit/test_api/test_no_backend_error_text.py index 9d10f40e5..8d73a40a7 100644 --- a/tests/unit/test_api/test_no_backend_error_text.py +++ b/tests/unit/test_api/test_no_backend_error_text.py @@ -157,8 +157,8 @@ def execute(self, **_kwargs): raise ViewExecutionError(f"Failed to execute view 'x': {SENTINEL}") app.state.view_executor = _FailingExecutor() - # The view is held to the session's org, so the viewer's account is bound to one. - app.state.account_store.update("viewer", org="test-org") + # The view is held to the session's org, so the root viewer is bound to your org. + app.state.org_registry.home.set(actor="test", name="test-org") resp = client.post( "/api/v1/queries/views/analytics/events/execute", headers=viewer_headers, json={} diff --git a/tests/unit/test_api/test_oidc_directory_outage_login.py b/tests/unit/test_api/test_oidc_directory_outage_login.py index 2b278e5bc..0a6946868 100644 --- a/tests/unit/test_api/test_oidc_directory_outage_login.py +++ b/tests/unit/test_api/test_oidc_directory_outage_login.py @@ -46,7 +46,14 @@ FAILING = {"error": {"code": "ServiceUnavailable", "status": "UNAVAILABLE"}} SCOPE_REFUSED = {"error": {"code": 403, "status": "PERMISSION_DENIED"}} -USERINFO = {"email": "alice@acme.test", "name": "Alice", "oid": OID, "sub": SUBJECT} +USERINFO = { + "email": "alice@acme.test", + "email_verified": True, + "name": "Alice", + "oid": OID, + "sub": SUBJECT, + "xms_edov": True, +} PROVIDERS: dict[str, OIDCProvider] = { "entra": OIDCProvider(type="entra_id", issuer="https://login.microsoftonline.com/t/v2.0"), diff --git a/tests/unit/test_api/test_oidc_link.py b/tests/unit/test_api/test_oidc_link.py new file mode 100644 index 000000000..de0e2d3ae --- /dev/null +++ b/tests/unit/test_api/test_oidc_link.py @@ -0,0 +1,159 @@ +# Project: dfe-engine +# File: tests/unit/test_api/test_oidc_link.py +# Purpose: API tests for linking an IdP sign-in to a local account by its password +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +from datetime import timedelta +from urllib.parse import parse_qs, urlsplit + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from dfe_engine.auth.identity_links import LINK_TICKET_AUDIENCE +from dfe_engine.auth.oidc.rp import NormalizedIdentity +from tests.support.oidc import serve_provider + +_EMAIL = "kaz@example.test" +_PASSWORD = "kaz-local-password-1" +_SUBJECT = "stub-kaz" + + +class _VerifiedOidcRp: + """An RP stub whose stub provider vouches for kaz's email.""" + + def has_provider(self, name: str) -> bool: + """Serve the stub provider only.""" + return name == "stub" + + async def handle_callback(self, provider: str, request: object) -> NormalizedIdentity: + """Answer every callback with kaz's verified identity.""" + return NormalizedIdentity( + email=_EMAIL, email_verified=True, groups=["g1"], name="Kaz", subject=_SUBJECT + ) + + async def login_authorization_url( + self, provider: str, request: object, redirect_uri: str + ) -> str: + """Hand back a fixed authorize URL.""" + return "https://idp.example/authorize?state=test" + + +def _callback(*, client: TestClient): + """Run the stub provider's callback without following its redirect.""" + return client.get("https://testserver/api/v1/auth/oidc/stub/callback", follow_redirects=False) + + +def _link(*, client: TestClient, password: str, ticket: str): + """Redeem *ticket* with *password*.""" + return client.post("/api/v1/auth/oidc/link", json={"password": password, "ticket": ticket}) + + +def _ticket(*, client: TestClient) -> str: + """The ticket a JSON callback answers link_required with.""" + return _callback(client=client).json()["link_ticket"] + + +@pytest.fixture +def linkable(app: FastAPI, client: TestClient) -> FastAPI: + """Trust the stub provider for example.test, give its g1 a role and store the local kaz holding the email.""" + serve_provider(app) + app.state.oidc_provider_registry.update("stub", trusted_email_domains=["example.test"]) + app.state.group_store.create( + "stub-viewers", ["data_viewer"], source_provider="stub", source_id="g1" + ) + app.state.account_store.create("kaz", _PASSWORD, email=_EMAIL) + app.state.oidc_rp = _VerifiedOidcRp() + return app + + +class TestCallbackHoldsTheLink: + def test_json(self, client: TestClient, linkable: FastAPI): + resp = _callback(client=client) + body = resp.json() + assert (resp.status_code, body["code"], body["account"], "link_ticket" in body) == ( + 409, + "link_required", + "kaz", + True, + ) + + def test_writes_nothing(self, client: TestClient, linkable: FastAPI): + _callback(client=client) + assert linkable.state.account_store.get(_SUBJECT) is None + + def test_browser(self, client: TestClient, linkable: FastAPI): + client.get( + "https://testserver/api/v1/auth/oidc/stub/login", + params={"redirect": "false", "return_to": "/login/oidc?login_nonce=n1"}, + ) + resp = _callback(client=client) + location = urlsplit(resp.headers["location"]) + fields = parse_qs(location.fragment) + assert ( + resp.status_code, + location.path, + fields["error"], + fields["account"], + "link_ticket" in fields, + "access_token" in fields, + ) == (303, "/login/oidc", ["link_required"], ["kaz"], True, False) + + +class TestLink: + def test_signs_in_as_the_account(self, client: TestClient, linkable: FastAPI): + resp = _link(client=client, password=_PASSWORD, ticket=_ticket(client=client)) + bearer = {"Authorization": f"Bearer {resp.json()['access_token']}"} + me = client.get("/api/v1/auth/me", headers=bearer).json() + assert (resp.status_code, me["user_id"], me["roles"]) == (200, "kaz", ["data_viewer"]) + + def test_the_next_login_needs_no_password(self, client: TestClient, linkable: FastAPI): + _link(client=client, password=_PASSWORD, ticket=_ticket(client=client)) + resp = _callback(client=client) + bearer = {"Authorization": f"Bearer {resp.json()['access_token']}"} + me = client.get("/api/v1/auth/me", headers=bearer).json() + assert (resp.status_code, me["user_id"]) == (200, "kaz") + + def test_the_local_password_keeps_working(self, client: TestClient, linkable: FastAPI): + _link(client=client, password=_PASSWORD, ticket=_ticket(client=client)) + resp = client.post("/api/v1/auth/login", json={"password": _PASSWORD, "username": "kaz"}) + assert (resp.status_code, resp.json()["roles"]) == (200, ["data_viewer"]) + + def test_a_wrong_password_links_nothing(self, client: TestClient, linkable: FastAPI): + resp = _link(client=client, password="not-the-password", ticket=_ticket(client=client)) + assert ( + resp.status_code, + resp.json()["code"], + linkable.state.account_store.get(_SUBJECT), + ) == ( + 401, + "unauthorized", + None, + ) + + @pytest.mark.parametrize("ticket", ["not-a-token", "expired", "another-audience"]) + def test_an_unusable_ticket(self, client: TestClient, linkable: FastAPI, ticket: str): + authority = linkable.state.jwt_authority + tickets = { + "another-audience": authority.sign(claims={"aud": "dfe-hyperdx", "account": "kaz"}), + "expired": authority.sign( + claims={"aud": LINK_TICKET_AUDIENCE, "account": "kaz"}, + expires_delta=timedelta(minutes=-10), + ), + "not-a-token": "not-a-token", + } + resp = _link(client=client, password=_PASSWORD, ticket=tickets[ticket]) + assert (resp.status_code, resp.json()["code"]) == (401, "link_ticket_invalid") + + def test_withdrawn_trust_refuses_the_ticket(self, client: TestClient, linkable: FastAPI): + ticket = _ticket(client=client) + linkable.state.oidc_provider_registry.update("stub", trusted_email_domains=[]) + resp = _link(client=client, password=_PASSWORD, ticket=ticket) + assert (resp.status_code, resp.json()["code"]) == (401, "link_stale") + + def test_the_ticket_is_no_bearer_token(self, client: TestClient, linkable: FastAPI): + bearer = {"Authorization": f"Bearer {_ticket(client=client)}"} + assert client.get("/api/v1/auth/me", headers=bearer).status_code == 401 diff --git a/tests/unit/test_api/test_oidc_providers.py b/tests/unit/test_api/test_oidc_providers.py index b66e1aefe..392351210 100644 --- a/tests/unit/test_api/test_oidc_providers.py +++ b/tests/unit/test_api/test_oidc_providers.py @@ -25,10 +25,14 @@ CREATE_PROVIDER_UNSET_ENV_CASES, SWITCHED_SECRET, SWITCHED_SECRET_ENV, + TRUSTED_EMAIL_DOMAINS_CASES, + TRUSTED_EMAIL_DOMAINS_REFUSED_CASES, UNSET_SECRET_ENV, UPDATE_PROVIDER_SECRET_SOURCE_CASES, UPDATE_TENANT_ID_ENV_CASES, CreateProviderUnsetEnvCase, + TrustedEmailDomainsCase, + TrustedEmailDomainsRefusedCase, UpdateProviderSecretSourceCase, UpdateTenantIdEnvCase, ) @@ -206,6 +210,87 @@ def test_an_unset_env_var_beside_a_value_is_accepted( ) +class TestTrustedEmailDomains: + @pytest.mark.parametrize( + "case", + TRUSTED_EMAIL_DOMAINS_CASES, + ids=[case["id"] for case in TRUSTED_EMAIL_DOMAINS_CASES], + ) + def test_create( + self, + admin_headers: dict[str, str], + app: FastAPI, + client: TestClient, + case: TrustedEmailDomainsCase, + ): + resp = _create_provider( + admin_headers=admin_headers, client=client, trusted_email_domains=case["sent_domains"] + ) + stored = app.state.oidc_provider_registry.get("test-provider").trusted_email_domains + assert (resp.status_code, resp.json()["trusted_email_domains"], stored) == ( + 201, + case["expected_domains"], + case["expected_domains"], + ) + + @pytest.mark.parametrize( + "case", + TRUSTED_EMAIL_DOMAINS_CASES, + ids=[case["id"] for case in TRUSTED_EMAIL_DOMAINS_CASES], + ) + def test_update( + self, admin_headers: dict[str, str], client: TestClient, case: TrustedEmailDomainsCase + ): + _create_provider( + admin_headers=admin_headers, client=client, trusted_email_domains=["old.example"] + ) + resp = client.put( + "/api/v1/auth/oidc-providers/test-provider", + headers=admin_headers, + json={"trusted_email_domains": case["sent_domains"]}, + ) + assert (resp.status_code, resp.json()["trusted_email_domains"]) == ( + 200, + case["expected_domains"], + ) + + @pytest.mark.parametrize( + "case", + TRUSTED_EMAIL_DOMAINS_REFUSED_CASES, + ids=[case["id"] for case in TRUSTED_EMAIL_DOMAINS_REFUSED_CASES], + ) + def test_refused( + self, + admin_headers: dict[str, str], + app: FastAPI, + client: TestClient, + case: TrustedEmailDomainsRefusedCase, + ): + resp = _create_provider( + admin_headers=admin_headers, client=client, trusted_email_domains=case["sent_domains"] + ) + stored = app.state.oidc_provider_registry.get("test-provider") + assert (resp.status_code, _field_errors(resp), stored) == ( + 422, + ["trusted_email_domains"], + None, + ) + + def test_an_update_of_domains_alone_skips_the_field_rules( + self, admin_headers: dict[str, str], app: FastAPI, client: TestClient + ): + # Written past the API: an api-mode Okta provider missing every directory field the rules require. + app.state.oidc_provider_registry.create( + "legacy", make_oidc_provider(groups={"mode": "api"}, type="okta") + ) + resp = client.put( + "/api/v1/auth/oidc-providers/legacy", + headers=admin_headers, + json={"trusted_email_domains": ["corp.com"]}, + ) + assert (resp.status_code, resp.json()["trusted_email_domains"]) == (200, ["corp.com"]) + + class TestListProviders: """GET /api/v1/auth/oidc-providers""" diff --git a/tests/unit/test_api/test_oidc_reauth.py b/tests/unit/test_api/test_oidc_reauth.py new file mode 100644 index 000000000..8edf92d86 --- /dev/null +++ b/tests/unit/test_api/test_oidc_reauth.py @@ -0,0 +1,209 @@ +# Project: dfe-engine +# File: tests/unit/test_api/test_oidc_reauth.py +# Purpose: API tests for re-auth through a fresh sign-in at the caller's identity provider +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +import time +from urllib.parse import parse_qs, urlsplit + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from dfe_engine.api.deps import jwt_authority_for +from dfe_engine.api.v1 import oidc_login +from dfe_engine.auth.oidc.rp import NormalizedIdentity +from dfe_engine.auth.reauth import grant_allows +from dfe_engine.settings import DFESettings +from tests.support.accounts import session_token +from tests.support.oidc import serve_provider + +LOGIN = "https://testserver/api/v1/auth/oidc/stub/login" +CALLBACK = "https://testserver/api/v1/auth/oidc/stub/callback" +REAUTH = "https://testserver/api/v1/auth/oidc/reauth" +RETURN_TO = "/settings/accounts" + + +class _ReauthRp: + """A stub RP that hands out a fresh state per authorize request and signs in *subject* at *auth_time*.""" + + def __init__(self, *, auth_time: int | None, subject: str) -> None: + self.auth_time = auth_time + self.issued = 0 + self.params = {} + self.subject = subject + + def has_provider(self, name: str) -> bool: + """Whether *name* is the stub provider.""" + return name == "stub" + + async def handle_callback(self, provider: str, request: object) -> NormalizedIdentity: + """The identity the stub IdP signs in.""" + return NormalizedIdentity(auth_time=self.auth_time, groups=["g1"], subject=self.subject) + + async def login_authorization_url( + self, provider: str, request: object, redirect_uri: str, **params: str | int + ) -> str: + """Record *params* and answer with an authorize URL carrying the next state.""" + self.issued += 1 + self.params = params + return f"https://idp.example/authorize?state=s{self.issued}" + + +def _fragment(*, location: str) -> dict[str, str]: + """The fields of *location*'s URL fragment.""" + return {key: values[0] for key, values in parse_qs(urlsplit(location).fragment).items()} + + +def _state(*, url: str) -> str: + """The ``state`` an authorize URL carries.""" + return parse_qs(urlsplit(url).query)["state"][0] + + +def _reauth( + *, + app: FastAPI, + client: TestClient, + headers: dict[str, str], + kind: str = "account", + rp: _ReauthRp, + target: str = "bob", +) -> dict[str, str]: + """Start a re-auth for *target*, come back through the callback on its state and return the hand-back fragment.""" + app.state.oidc_rp = rp + body = {"kind": kind, "return_to": RETURN_TO, "target": target} + started = client.post(REAUTH, headers=headers, json=body) + assert started.status_code == 200, started.text + state = _state(url=started.json()["authorization_url"]) + resp = client.get(f"{CALLBACK}?state={state}", follow_redirects=False) + assert resp.status_code == 303, resp.text + assert resp.headers["location"].startswith(RETURN_TO) + return _fragment(location=resp.headers["location"]) + + +@pytest.fixture +def ida_headers(api_settings: DFESettings, app: FastAPI, client: TestClient) -> dict[str, str]: + """A session for ida, who signs in through the stub provider only.""" + serve_provider(app) + app.state.group_store.create( + "stub-viewers", ["data_viewer"], source_provider="stub", source_id="g1" + ) + accounts = app.state.account_store + accounts.create("ida", "", groups=["stub-viewers"]) + accounts.update("ida", external=True, oidc_id="stub", source_provider="stub", subject="ida") + token = session_token(app, api_settings, {"sub": "ida"}) + return {"Authorization": f"Bearer {token}"} + + +class TestOidcReauth: + def test_asks_the_idp_for_credentials_again( + self, app: FastAPI, client: TestClient, ida_headers: dict[str, str] + ): + rp = _ReauthRp(auth_time=int(time.time()), subject="ida") + _reauth(app=app, client=client, headers=ida_headers, rp=rp) + assert rp.params == {"max_age": 0, "prompt": "login"} + + @pytest.mark.parametrize( + ("kind", "target", "expected_target"), + [ + ("account", "bob", "bob"), + ("group", "bob-team", "group:bob-team"), + ("role", "bob-role", "role:bob-role"), + ], + ids=["account", "group", "role"], + ) + def test_a_fresh_sign_in_by_the_caller_earns_a_grant( + self, + api_settings: DFESettings, + app: FastAPI, + client: TestClient, + ida_headers: dict[str, str], + kind: str, + target: str, + expected_target: str, + ): + rp = _ReauthRp(auth_time=int(time.time()), subject="ida") + fields = _reauth( + app=app, client=client, headers=ida_headers, kind=kind, rp=rp, target=target + ) + assert grant_allows( + authority=jwt_authority_for(api_settings), + caller="ida", + target=expected_target, + token=fields["reauth_grant"], + ) + + @pytest.mark.parametrize( + ("subject", "age", "expected_error"), + [ + ("someone-else", 0, "reauth_other_person"), + ("ida", 600, "reauth_not_fresh"), + ("ida", None, "reauth_not_fresh"), + ], + ids=["another_person", "stale_sign_in", "no_auth_time"], + ) + def test_a_sign_in_that_proves_nothing_is_refused( + self, + app: FastAPI, + client: TestClient, + ida_headers: dict[str, str], + subject: str, + age: int | None, + expected_error: str, + ): + auth_time = None if age is None else int(time.time()) - age + rp = _ReauthRp(auth_time=auth_time, subject=subject) + fields = _reauth(app=app, client=client, headers=ida_headers, rp=rp) + assert (fields.get("error"), "reauth_grant" in fields) == (expected_error, False) + + def test_a_slow_sign_in_is_refused( + self, + app: FastAPI, + client: TestClient, + ida_headers: dict[str, str], + monkeypatch: pytest.MonkeyPatch, + ): + monkeypatch.setattr(oidc_login, "_REAUTH_SIGN_IN_SECONDS", -1) + rp = _ReauthRp(auth_time=int(time.time()), subject="ida") + fields = _reauth(app=app, client=client, headers=ida_headers, rp=rp) + assert fields.get("error") == "reauth_expired" + + def test_a_login_open_in_another_tab_stays_a_login( + self, app: FastAPI, client: TestClient, ida_headers: dict[str, str] + ): + app.state.oidc_rp = _ReauthRp(auth_time=int(time.time()), subject="ida") + body = {"kind": "account", "return_to": RETURN_TO, "target": "bob"} + started = client.post(REAUTH, headers=ida_headers, json=body) + assert started.status_code == 200, started.text + login = client.get(f"{LOGIN}?redirect=false") + assert login.status_code == 200, login.text + + resp = client.get( + f"{CALLBACK}?state={_state(url=login.json()['authorization_url'])}", + follow_redirects=False, + ) + assert "reauth_grant" not in resp.text + resp.headers.get("location", "") + + again = client.get( + f"{CALLBACK}?state={_state(url=started.json()['authorization_url'])}", + follow_redirects=False, + ) + assert "reauth_grant" in _fragment(location=again.headers.get("location", "")), again.text + + def test_a_password_account_is_sent_to_its_password( + self, admin_headers: dict[str, str], client: TestClient + ): + body = {"kind": "account", "return_to": RETURN_TO, "target": "bob"} + resp = client.post(REAUTH, headers=admin_headers, json=body) + assert (resp.status_code, resp.json()["code"]) == (409, "reauth_via_password") + + def test_an_untrusted_return_to_is_refused( + self, app: FastAPI, client: TestClient, ida_headers: dict[str, str] + ): + app.state.oidc_rp = _ReauthRp(auth_time=int(time.time()), subject="ida") + body = {"kind": "account", "return_to": "https://evil.example/x", "target": "bob"} + resp = client.post(REAUTH, headers=ida_headers, json=body) + assert (resp.status_code, resp.json()["code"]) == (400, "invalid_return_to") diff --git a/tests/unit/test_api/test_oidc_rp.py b/tests/unit/test_api/test_oidc_rp.py index 15b54ec4d..95614bd30 100644 --- a/tests/unit/test_api/test_oidc_rp.py +++ b/tests/unit/test_api/test_oidc_rp.py @@ -333,7 +333,11 @@ async def login_authorization_url(self, provider: str, request, redirect_uri: st async def handle_callback(self, provider: str, request) -> NormalizedIdentity: return NormalizedIdentity( - email="stub@example.test", groups=["g1"], name="Stub User", subject="stub-user" + email_verified=True, + email="stub@example.test", + groups=["g1"], + name="Stub User", + subject="stub-user", ) @@ -678,7 +682,11 @@ def __init__(self, subject: str) -> None: async def handle_callback(self, provider: str, request) -> NormalizedIdentity: return NormalizedIdentity( - email="evil@example.test", groups=["g1"], name="Taken Over", subject=self._subject + email_verified=True, + email="evil@example.test", + groups=["g1"], + name="Taken Over", + subject=self._subject, ) @@ -690,7 +698,11 @@ def __init__(self, groups: list[str]) -> None: async def handle_callback(self, provider: str, request) -> NormalizedIdentity: return NormalizedIdentity( - email="stub@example.test", groups=self._groups, name="Stub User", subject="stub-user" + email_verified=True, + email="stub@example.test", + groups=self._groups, + name="Stub User", + subject="stub-user", ) @@ -777,6 +789,8 @@ def _break_the_account_store(app) -> None: ("no-role", "no_role_granted", ("auth.login.denied", "no_role_granted")), ("disabled", "account_disabled", ("auth.login.denied", "account_disabled")), ("blocked", "account_blocked", ("auth.login.denied", "account_blocked")), + ("email-held", "email_held", ("auth.login.denied", "email_held")), + ("email-untrusted", "email_untrusted", ("auth.login.denied", "email_untrusted")), ("local-admin", "unauthorized", ("auth.login.denied", "protected_account")), ("store-down", "service_unavailable", ("auth.jit.provision_failed", None)), ], @@ -793,6 +807,13 @@ def test_a_refused_browser_login_returns_to_the_console_with_the_code( store.create("stub-user", "", groups=["dfe-viewers"]) flag = {"enabled": False} if refusal == "disabled" else {"blocked": True} store.update("stub-user", external=True, source_provider="stub", **flag) + elif refusal == "email-held": + app.state.oidc_rp = _SubjectOidcRp("new-user") + store.create("kim", "kim-password-12", email="evil@example.test") + store.create("kim2", "kim-password-12", email="evil@example.test") + elif refusal == "email-untrusted": + app.state.oidc_rp = _SubjectOidcRp("new-user") + app.state.oidc_provider_registry.update("stub", trusted_email_domains=["other.example"]) elif refusal == "local-admin": app.state.oidc_rp = _SubjectOidcRp("admin") else: diff --git a/tests/unit/test_api/test_openapi_auth_errors.py b/tests/unit/test_api/test_openapi_auth_errors.py index e31730e2b..e025c37bc 100644 --- a/tests/unit/test_api/test_openapi_auth_errors.py +++ b/tests/unit/test_api/test_openapi_auth_errors.py @@ -28,6 +28,7 @@ "GET /api/v1/auth/setup-status", "GET /api/v1/auth/oidc/{provider}/login", "GET /api/v1/auth/oidc/{provider}/callback", + "POST /api/v1/auth/oidc/link", "GET /api/v1/scim/v2/ServiceProviderConfig", "GET /api/v1/scim/v2/ResourceTypes", "GET /api/v1/scim/v2/Schemas", @@ -37,6 +38,9 @@ # Public, but it refuses a bad login itself, so it declares both statuses by hand. LOGIN = "POST /api/v1/auth/login" +# Public routes that check a password themselves, so they declare the 401 a wrong one gets. +PASSWORD_CHECKS = frozenset({LOGIN, "POST /api/v1/auth/oidc/link"}) + # The committed spec lists the sigma routes and test_openapi_spec_committed.py keeps it equal to the app. COMMITTED_SPEC = json.loads( (Path(__file__).resolve().parents[3] / "openapi" / "openapi.json").read_text() @@ -136,7 +140,7 @@ def test_every_public_operation_is_real_and_declares_neither(spec): assert PUBLIC_OPERATIONS <= operations.keys(), sorted(PUBLIC_OPERATIONS - operations.keys()) declared = sorted( f"{key} -> {status}" - for key in PUBLIC_OPERATIONS - {LOGIN} + for key in PUBLIC_OPERATIONS - PASSWORD_CHECKS for status in AUTH_STATUSES if status in operations[key].get("responses", {}) ) diff --git a/tests/unit/test_api/test_org_role_rule.py b/tests/unit/test_api/test_org_role_rule.py new file mode 100644 index 000000000..442502e6e --- /dev/null +++ b/tests/unit/test_api/test_org_role_rule.py @@ -0,0 +1,474 @@ +# Project: dfe-engine +# File: tests/unit/test_api/test_org_role_rule.py +# Purpose: API tests for org roles: the rule that an org account holds only its own org's admin or viewer group, and what an org admin may do +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +import re + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from dfe_engine.auth.identity_links import LinkTicket +from dfe_engine.auth.jit import ( + JitEmailHeldError, + JitIdentityCollisionError, + JitLinkRequiredError, + JitNoRoleError, +) +from dfe_engine.query.executor import ViewExecutor +from dfe_engine.settings import DFESettings +from tests.support.accounts import session_token +from tests.unit.test_api.org_role_rule_cases import ( + ACCOUNTS, + ACME_SSO, + LIVE_GRANTS_CASES, + ORG_ADMIN_ACCOUNTS_CASES, + ORG_ADMIN_PROVIDERS_CASES, + ORG_ADMIN_ROLE_CASES, + ORG_ROLE_CASES, + PASSWORD, + PROVIDERS, + SCIM, + LiveGrantsCase, + OrgAdminAccountsCase, + OrgAdminProvidersCase, + OrgAdminRoleCase, + OrgRoleCase, +) +from tests.unit.test_query.view_fakes import OneViewCatalog, RecordingClient, view_definition + +EXECUTE = "/api/v1/queries/views/analytics/events/execute" +ME = "/api/v1/auth/me" + + +def _reach(*, client: TestClient, headers: dict[str, str]) -> tuple[list[str], list[str]]: + """The roles and orgs the session behind *headers* holds, each sorted.""" + resp = client.get(ME, headers=headers) + assert resp.status_code == 200, resp.text + return sorted(resp.json()["roles"]), sorted(resp.json()["org_ids"]) + + +@pytest.fixture +def acme_admin(api_settings: DFESettings, orgs: FastAPI) -> dict[str, str]: + """Make kim acme's only admin beside ace, a local acme viewer, and gil, a globex viewer, and return kim's headers.""" + accounts = orgs.state.account_store + groups = orgs.state.group_store + for username, org in (("ace", "acme"), ("gil", "globex")): + accounts.create(username, PASSWORD, groups=[f"{org}-viewers"]) + accounts.update(username, org=org, password_change_required=False) + groups.add_member(f"{org}-viewers", username) + groups.update("acme-viewers", members=["ace", "ida"]) + groups.add_member("acme-admins", "kim") + token = session_token(orgs, api_settings, {"sub": "kim"}) + return {"Authorization": f"Bearer {token}"} + + +@pytest.fixture +def providers(admin_headers: dict[str, str], client: TestClient, orgs: FastAPI) -> FastAPI: + """Store acme-idp, globex-idp trusting globex.test, and the platform's platform-idp trusting example.test.""" + for name, org, domains in ( + ("acme-idp", "acme", []), + ("globex-idp", "globex", ["globex.test"]), + ("platform-idp", "", ["example.test"]), + ): + body = { + "client_id": f"{name}-client", + "issuer": f"https://{name}.test", + "name": name, + "org": org, + "trusted_email_domains": domains, + "type": "generic", + } + resp = client.post(PROVIDERS, headers=admin_headers, json=body) + assert resp.status_code == 201, resp.text + return orgs + + +@pytest.fixture +def orgs(admin_headers: dict[str, str], app: FastAPI, client: TestClient) -> FastAPI: + """Name hyperi your org, create acme and globex with their groups, and store the accounts the cases read. + + kim is a local acme viewer. ida is an acme viewer its IdP owns, asserting ext-1 and ext-eng, the id the roleless system group eng links. ann belongs to hyperi and holds sys-analysts. + """ + for name in ("hyperi", "acme", "globex"): + resp = client.post("/api/v1/orgs", headers=admin_headers, json={"name": name}) + assert resp.status_code == 201, resp.text + app.state.org_registry.home.set(actor="test", name="hyperi") + groups = app.state.group_store + groups.create("sys-analysts", ["data_analyst"]) + groups.create("acme-analysts", ["data_analyst"], scope="org:acme") + groups.create("eng", [], source_id="ext-eng", source_provider="scim") + kim = { + "email": "kim@example.test", + "groups": ["acme-viewers"], + "name": "Kim", + "org": "acme", + "password": PASSWORD, + "username": "kim", + } + ann = { + "email": "ann@example.test", + "groups": ["sys-analysts"], + "name": "Ann", + "org": "hyperi", + "password": PASSWORD, + "username": "ann", + } + for body in (kim, ann): + resp = client.post(ACCOUNTS, headers=admin_headers, json=body) + assert resp.status_code == 201, resp.text + accounts = app.state.account_store + accounts.create("ida", "", groups=[]) + accounts.update( + "ida", external=True, groups=["ext-1", "ext-eng"], org="acme", source_provider="scim" + ) + groups.add_member("acme-viewers", "ida") + for username in ("ann", "kim"): + accounts.update(username, password_change_required=False) + return app + + +class TestOrgRoleRule: + @pytest.mark.parametrize("case", ORG_ROLE_CASES, ids=[case["id"] for case in ORG_ROLE_CASES]) + def test_matches_expected( + self, + admin_headers: dict[str, str], + client: TestClient, + orgs: FastAPI, + case: OrgRoleCase, + ): + resp = client.request( + case["method"], case["path"], headers=admin_headers, json=case["body"] + ) + code = resp.json().get("code") if resp.status_code == 422 else None + expected_code = "org_role_only" if case["expected_status"] == 422 else None + assert (resp.status_code, code) == (case["expected_status"], expected_code), resp.text + + def test_scim_adds_an_org_account_to_a_group_granting_nothing( + self, admin_headers: dict[str, str], client: TestClient, orgs: FastAPI + ): + created = client.post( + f"{SCIM}/Groups", + headers=admin_headers, + json={ + "displayName": "scim-grp", + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], + }, + ) + assert created.status_code == 201, created.text + added = client.patch( + f"{SCIM}/Groups/scim-grp", + headers=admin_headers, + json={ + "Operations": [{"op": "add", "path": "members", "value": [{"value": "kim"}]}], + "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], + }, + ) + assert (added.status_code, orgs.state.group_store.get("scim-grp").members) == (200, ["kim"]) + + +class TestLiveGrants: + @pytest.mark.parametrize( + "case", LIVE_GRANTS_CASES, ids=[case["id"] for case in LIVE_GRANTS_CASES] + ) + def test_matches_expected( + self, + api_settings: DFESettings, + client: TestClient, + orgs: FastAPI, + case: LiveGrantsCase, + ): + case["arrange"](app=orgs) + token = session_token(orgs, api_settings, {"sub": case["username"]}) + reach = _reach(client=client, headers={"Authorization": f"Bearer {token}"}) + assert reach == (case["expected_roles"], case["expected_org_ids"]) + + def test_org_key_reaches_only_its_org(self, client: TestClient, orgs: FastAPI): + _, key = orgs.state.api_key_store.create( + "acme-key", groups=["acme-viewers", "sys-analysts"], org="acme" + ) + assert _reach(client=client, headers={"X-API-Key": key}) == (["org_viewer"], ["acme"]) + + def test_password_login_claims_only_its_orgs_roles(self, client: TestClient, orgs: FastAPI): + orgs.state.group_store.add_member("sys-analysts", "kim") + resp = client.post("/api/v1/auth/login", json={"password": PASSWORD, "username": "kim"}) + assert (resp.status_code, resp.json().get("roles")) == (200, ["org_viewer"]), resp.text + + def test_idp_sign_in_granting_only_outside_its_org_is_refused(self, orgs: FastAPI): + orgs.state.oidc_provider_registry.create("acme-sso", ACME_SSO) + groups = orgs.state.group_store + groups.update("acme-viewers", members=["ida"]) + groups.update("sys-analysts", source_id="sys-id", source_provider="acme-sso") + ticket = LinkTicket( + account="kim", + email="kim@example.test", + groups=["sys-id"], + provider="acme-sso", + subject="kim-sub", + ) + message = ( + "OIDC login refused: no DFE group with a role is linked to your identity provider " + "groups. Ask a DFE administrator to link one." + ) + with pytest.raises(JitNoRoleError, match=re.escape(message)): + orgs.state.jit_provisioner.complete_link(ticket=ticket) + + +class TestOrgAdminRole: + @pytest.mark.parametrize( + "case", ORG_ADMIN_ROLE_CASES, ids=[case["id"] for case in ORG_ADMIN_ROLE_CASES] + ) + def test_matches_expected( + self, + admin_headers: dict[str, str], + client: TestClient, + orgs: FastAPI, + case: OrgAdminRoleCase, + ): + resp = client.request( + case["method"], case["path"], headers=admin_headers, json=case["body"] + ) + code = resp.json().get("code") if resp.status_code >= 400 else None + assert (resp.status_code, code) == (case["expected_status"], case["expected_code"]), ( + resp.text + ) + + def test_an_org_admin_reads_through_its_orgs_user( + self, api_settings: DFESettings, client: TestClient, orgs: FastAPI + ): + orgs.state.group_store.add_member("acme-admins", "kim") + token = session_token(orgs, api_settings, {"sub": "kim"}) + resp = client.get(ME, headers={"Authorization": f"Bearer {token}"}) + assert (resp.status_code, resp.json()["hyperdx_identity"]) == (200, "dfe_org_acme") + + +class TestOrgAdminAccounts: + @pytest.mark.parametrize( + "case", ORG_ADMIN_ACCOUNTS_CASES, ids=[case["id"] for case in ORG_ADMIN_ACCOUNTS_CASES] + ) + def test_matches_expected( + self, acme_admin: dict[str, str], client: TestClient, case: OrgAdminAccountsCase + ): + resp = client.request(case["method"], case["path"], headers=acme_admin, json=case["body"]) + code = resp.json().get("code") if resp.status_code >= 400 else None + assert (resp.status_code, code) == (case["expected_status"], case["expected_code"]), ( + resp.text + ) + + def test_lists_only_its_orgs_accounts(self, acme_admin: dict[str, str], client: TestClient): + resp = client.get(ACCOUNTS, headers=acme_admin) + listed = sorted(item["username"] for item in resp.json()["items"]) + assert (resp.status_code, listed) == (200, ["ace", "ida", "kim"]), resp.text + + def test_a_second_admin_lets_it_step_down(self, acme_admin: dict[str, str], client: TestClient): + promoted = client.put( + f"{ACCOUNTS}/ace", headers=acme_admin, json={"groups": ["acme-admins"]} + ) + demoted = client.put( + f"{ACCOUNTS}/kim", headers=acme_admin, json={"groups": ["acme-viewers"]} + ) + assert (promoted.status_code, demoted.status_code) == (200, 200), demoted.text + + def test_your_orgs_admin_may_remove_its_last_admin( + self, acme_admin: dict[str, str], admin_headers: dict[str, str], client: TestClient + ): + resp = client.put( + f"{ACCOUNTS}/kim", headers=admin_headers, json={"groups": ["acme-viewers"]} + ) + assert resp.status_code == 200, resp.text + + +class TestOrgViews: + def test_an_org_viewer_runs_its_orgs_isolated_view( + self, api_settings: DFESettings, client: TestClient, orgs: FastAPI, reader: RecordingClient + ): + token = session_token(orgs, api_settings, {"sub": "kim"}) + resp = client.post(EXECUTE, headers={"Authorization": f"Bearer {token}"}, json={}) + assert (resp.status_code, reader.parameters.get("org_id")) == (200, "acme"), resp.text + + def test_an_org_viewer_may_not_run_a_view_of_every_org( + self, api_settings: DFESettings, client: TestClient, orgs: FastAPI, reader: RecordingClient + ): + every_org = view_definition().model_copy(update={"tenant_isolated": False}) + orgs.state.view_executor = ViewExecutor( + catalog=OneViewCatalog(every_org), # ty: ignore[invalid-argument-type] # a stand-in catalog serving one view + database="dfe", + restricted_client=reader, + ) + token = session_token(orgs, api_settings, {"sub": "kim"}) + resp = client.post(EXECUTE, headers={"Authorization": f"Bearer {token}"}, json={}) + assert (resp.status_code, reader.sql) == (403, ""), resp.text + + +class TestOrgAdminProviders: + @pytest.mark.parametrize( + "case", ORG_ADMIN_PROVIDERS_CASES, ids=[case["id"] for case in ORG_ADMIN_PROVIDERS_CASES] + ) + def test_matches_expected( + self, + acme_admin: dict[str, str], + client: TestClient, + providers: FastAPI, + case: OrgAdminProvidersCase, + ): + resp = client.request(case["method"], case["path"], headers=acme_admin, json=case["body"]) + code = resp.json().get("code") if resp.status_code >= 400 else None + assert (resp.status_code, code) == (case["expected_status"], case["expected_code"]), ( + resp.text + ) + + def test_lists_only_its_orgs_providers( + self, acme_admin: dict[str, str], client: TestClient, providers: FastAPI + ): + resp = client.get(PROVIDERS, headers=acme_admin) + listed = [item["name"] for item in resp.json()["items"]] + assert (resp.status_code, listed) == (200, ["acme-idp"]), resp.text + + +class TestOrgProviderSignIn: + def test_a_first_sign_in_lands_in_its_org_as_viewer(self, providers: FastAPI): + account = providers.state.jit_provisioner.ensure_account("dana-sub", [], "acme-idp") + viewers = providers.state.group_store.get("acme-viewers").members + assert (account.org, account.username in viewers) == ("acme", True) + + def test_a_platform_provider_sign_in_holding_no_role_is_refused(self, providers: FastAPI): + message = ( + "OIDC login refused: no DFE group with a role is linked to your identity provider " + "groups. Ask a DFE administrator to link one." + ) + with pytest.raises(JitNoRoleError, match=re.escape(message)): + providers.state.jit_provisioner.ensure_account("eve-sub", [], "platform-idp") + + def test_an_org_provider_does_not_link_another_orgs_account(self, providers: FastAPI): + providers.state.account_store.update("ann", email="ann@example.test", email_verified=True) + message = ( + "OIDC login refused: another DFE account already uses this email. Ask a DFE " + "administrator to trust your email domain on this identity provider." + ) + with pytest.raises(JitEmailHeldError, match=re.escape(message)): + providers.state.jit_provisioner.ensure_account( + "ann-sub", [], "acme-idp", email="ann@example.test", email_verified=True + ) + + def test_a_platform_provider_links_the_account_holding_its_email(self, providers: FastAPI): + providers.state.account_store.update("ann", email="ann@example.test", email_verified=True) + message = "Sign in with this account's password to link your identity provider to it" + with pytest.raises(JitLinkRequiredError, match=re.escape(message)): + providers.state.jit_provisioner.ensure_account( + "ann-sub", [], "platform-idp", email="ann@example.test", email_verified=True + ) + + +class TestOrgProviderFence: + def test_its_provider_never_adopts_an_account_outside_its_org(self, providers: FastAPI): + providers.state.account_store.update( + "ann", external=True, source_provider="acme-idp", subject="ann" + ) + message = "OIDC login refused" + with pytest.raises(JitIdentityCollisionError, match=message) as refused: + providers.state.jit_provisioner.ensure_account("ann", [], "acme-idp") + assert refused.value.reason == "other_org" + + def test_a_platform_provider_does_not_link_an_org_account(self, providers: FastAPI): + message = ( + "OIDC login refused: another DFE account already uses this email. Ask a DFE " + "administrator to trust your email domain on this identity provider." + ) + with pytest.raises(JitEmailHeldError, match=re.escape(message)): + providers.state.jit_provisioner.ensure_account( + "kim-sub", [], "platform-idp", email="kim@example.test", email_verified=True + ) + + def test_a_link_record_keeps_the_persons_org(self, providers: FastAPI): + ticket = LinkTicket( + account="kim", + email="kim@example.test", + groups=[], + provider="acme-idp", + subject="kim-sub", + ) + providers.state.jit_provisioner.complete_link(ticket=ticket) + assert providers.state.account_store.get("kim-sub").org == "acme" + + def test_deleting_its_provider_spares_accounts_outside_its_org( + self, acme_admin: dict[str, str], client: TestClient, providers: FastAPI + ): + accounts = providers.state.account_store + accounts.update("ann", oidc_id="acme-idp") + providers.state.jit_provisioner.ensure_account("dana-sub", [], "acme-idp") + resp = client.delete(f"{PROVIDERS}/acme-idp", headers=acme_admin) + kept = (resp.status_code, accounts.get("ann").enabled, accounts.get("dana-sub")) + assert kept == (200, True, None), resp.text + + def test_deleting_the_provider_every_admin_signs_in_through_is_refused( + self, acme_admin: dict[str, str], client: TestClient, providers: FastAPI + ): + providers.state.account_store.update("kim", oidc_id="acme-idp") + resp = client.delete(f"{PROVIDERS}/acme-idp", headers=acme_admin) + assert (resp.status_code, resp.json()["code"]) == (409, "last_org_admin"), resp.text + + def test_naming_its_provider_after_a_stamp_outside_its_org_is_refused( + self, acme_admin: dict[str, str], client: TestClient, providers: FastAPI + ): + providers.state.account_store.update("ann", oidc_id="legacy-idp") + body = { + "client_id": "legacy-client", + "issuer": "https://legacy.test", + "name": "legacy-idp", + "org": "acme", + "type": "generic", + } + resp = client.post(PROVIDERS, headers=acme_admin, json=body) + assert (resp.status_code, resp.json()["code"]) == (422, "provider_name_reserved") + + def test_a_domain_clash_names_no_other_org( + self, acme_admin: dict[str, str], client: TestClient, providers: FastAPI + ): + body = { + "client_id": "acme-two-client", + "issuer": "https://idp.acme.test", + "name": "acme-two", + "org": "acme", + "trusted_email_domains": ["globex.test"], + "type": "generic", + } + resp = client.post(PROVIDERS, headers=acme_admin, json=body) + assert (resp.status_code, "globex-idp" in resp.json()["detail"]) == (422, False), resp.text + + def test_repointing_a_provider_holding_an_env_secret_is_refused( + self, + acme_admin: dict[str, str], + admin_headers: dict[str, str], + client: TestClient, + providers: FastAPI, + ): + held = client.put( + f"{PROVIDERS}/acme-idp", headers=admin_headers, json={"client_secret_env": "PATH"} + ) + repointed = client.put( + f"{PROVIDERS}/acme-idp", headers=acme_admin, json={"issuer": "https://elsewhere.test"} + ) + codes = (held.status_code, repointed.status_code, repointed.json().get("code")) + assert codes == (200, 422, "env_source_held"), repointed.text + + @pytest.mark.parametrize( + ("name", "org", "expected_status"), + [("acme-idp", "", 422), ("platform-idp", "acme", 200)], + ids=["away_from_its_users_is_refused", "with_no_users_passes"], + ) + def test_moving_a_provider( + self, + admin_headers: dict[str, str], + client: TestClient, + providers: FastAPI, + name: str, + org: str, + expected_status: int, + ): + providers.state.jit_provisioner.ensure_account("dana-sub", [], "acme-idp") + resp = client.put(f"{PROVIDERS}/{name}", headers=admin_headers, json={"org": org}) + assert resp.status_code == expected_status, resp.text diff --git a/tests/unit/test_api/test_password_change_gate.py b/tests/unit/test_api/test_password_change_gate.py index 5f5f82fcf..478a68dcc 100644 --- a/tests/unit/test_api/test_password_change_gate.py +++ b/tests/unit/test_api/test_password_change_gate.py @@ -20,12 +20,12 @@ from prometheus_client.parser import text_string_to_metric_families from scalo.metrics import create_metrics -from dfe_engine.api.app import create_app from dfe_engine.api.deps import _registries from dfe_engine.api.metrics import PASSWORD_CHANGE_REFUSALS from dfe_engine.api.password_change import ALLOWED_BEFORE_CHANGE, PASSWORD_CHANGE_CLAIM from dfe_engine.auth.bootstrap import MIN_ADMIN_PASSWORD_LENGTH from dfe_engine.settings import DFESettings +from tests.support.reauth import create_app_without_reauth from .conftest import ADMIN_PASSWORD @@ -41,7 +41,7 @@ def _password_of(length: int) -> str: @pytest.fixture def fresh(api_settings: DFESettings) -> Iterator[TestClient]: """The app as a deployment boots it: the admin on its issued password.""" - app = create_app(settings=api_settings) + app = create_app_without_reauth(settings=api_settings) try: with TestClient(app, raise_server_exceptions=False) as client: yield client @@ -284,7 +284,7 @@ def test_the_standing_is_reported_once_the_password_is_changed(self, fresh): class TestAcrossARestart: def test_the_flag_survives_a_restart(self, api_settings): for _ in range(2): - app = create_app(settings=api_settings) + app = create_app_without_reauth(settings=api_settings) try: with TestClient(app, raise_server_exceptions=False) as client: assert _login(client)["password_change_required"] is True @@ -292,14 +292,14 @@ def test_the_flag_survives_a_restart(self, api_settings): _registries.clear() def test_the_owners_password_survives_a_restart_and_the_flag_stays_clear(self, api_settings): - app = create_app(settings=api_settings) + app = create_app_without_reauth(settings=api_settings) try: with TestClient(app, raise_server_exceptions=False) as client: _change(client, _bearer(_login(client))) finally: _registries.clear() - app = create_app(settings=api_settings) + app = create_app_without_reauth(settings=api_settings) try: with TestClient(app, raise_server_exceptions=False) as client: body = _login(client, _OWN_PASSWORD) @@ -330,7 +330,7 @@ def _sample(exposition: str, name: str, labels: dict[str, str]) -> float | None: def test_a_refusal_is_counted_by_method_and_area(api_settings): manager = create_metrics("test", backend="prometheus", enable_auto_update=False) - app = create_app(settings=api_settings, metrics_manager=manager) + app = create_app_without_reauth(settings=api_settings, metrics_manager=manager) try: with TestClient(app, raise_server_exceptions=False) as client: headers = _bearer(_login(client)) @@ -350,7 +350,7 @@ def test_a_refusal_is_counted_by_method_and_area(api_settings): def test_a_floor_refusal_is_counted_by_route(api_settings): manager = create_metrics("test", backend="prometheus", enable_auto_update=False) - app = create_app(settings=api_settings, metrics_manager=manager) + app = create_app_without_reauth(settings=api_settings, metrics_manager=manager) short = _password_of(MIN_ADMIN_PASSWORD_LENGTH - 1) try: with TestClient(app, raise_server_exceptions=False) as client: diff --git a/tests/unit/test_api/test_recovery_account_passwords.py b/tests/unit/test_api/test_recovery_account_passwords.py index 9f2d96822..f597714e7 100644 --- a/tests/unit/test_api/test_recovery_account_passwords.py +++ b/tests/unit/test_api/test_recovery_account_passwords.py @@ -50,6 +50,7 @@ ) from tests.support.accounts import session_token from tests.support.orgs import name_your_org +from tests.support.reauth import waive_reauth MINTED_ADMIN = secrets.token_urlsafe(16) MINTED_BREAKGLASS = secrets.token_urlsafe(16) @@ -112,7 +113,7 @@ def _settings( @contextlib.contextmanager def _booted(settings: DFESettings) -> Generator[tuple[FastAPI, TestClient]]: """A started engine. Leaving the block stops it, as a pod being replaced does.""" - app = create_app(settings=settings) + app = waive_reauth(create_app(settings=settings)) try: with TestClient(app, raise_server_exceptions=False) as client: yield app, client diff --git a/tests/unit/test_api/test_repository_api.py b/tests/unit/test_api/test_repository_api.py index 683bbe148..2cd06d59d 100644 --- a/tests/unit/test_api/test_repository_api.py +++ b/tests/unit/test_api/test_repository_api.py @@ -72,7 +72,7 @@ def repo_setup(client: TestClient, app, fake_ch, admin_headers: dict[str, str]) account_store.create(username, f"pw-{username}") for name, roles, scope, members in ( - ("acme-admins", ["admin"], "org:acme", ["orgadmin"]), + ("acme-ops", ["admin"], "org:acme", ["orgadmin"]), ("acme-analysts", ["data_analyst"], "org:acme", ["orguser"]), ("globex-analysts", ["data_analyst"], "org:globex", ["globexuser"]), ): diff --git a/tests/unit/test_api/test_retire_admin.py b/tests/unit/test_api/test_retire_admin.py index 519dd4360..498d88d7b 100644 --- a/tests/unit/test_api/test_retire_admin.py +++ b/tests/unit/test_api/test_retire_admin.py @@ -21,7 +21,6 @@ import pytest from fastapi.testclient import TestClient -from dfe_engine.api.app import create_app from dfe_engine.api.deps import _registries from dfe_engine.auth import admin_retirement from dfe_engine.gitcrud import GitCrud, default_registry @@ -41,6 +40,7 @@ ) from tests.support.accounts import session_token from tests.support.orgs import name_your_org +from tests.support.reauth import create_app_without_reauth MINTED_ADMIN = secrets.token_urlsafe(16) MINTED_USER = secrets.token_urlsafe(16) @@ -109,7 +109,7 @@ def _complete_setup(app, *, admin_of_our_own: bool = True) -> None: def wired(tmp_path: Path): """A booted app on a local deploy repo, with setup complete and alice an admin.""" settings = _settings(tmp_path) - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: _complete_setup(app) @@ -200,7 +200,7 @@ def test_a_non_admin_caller_is_refused(self, wired, tmp_path): def test_refused_without_an_admin_of_the_deployments_own(self, tmp_path): settings = _settings(tmp_path) - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: _complete_setup(app, admin_of_our_own=False) @@ -222,7 +222,7 @@ def test_refused_without_an_admin_of_the_deployments_own(self, tmp_path): def test_refused_without_a_deploy_repo_to_record_it_in(self, tmp_path): """No gitops means nowhere durable for the fact, so the next boot would reseed.""" settings = _settings(tmp_path, gitops=False) - app = create_app(settings=settings) + app = create_app_without_reauth(settings=settings) try: with TestClient(app, raise_server_exceptions=False) as client: _complete_setup(app) @@ -252,7 +252,7 @@ def test_it_starts_with_the_minted_password_deleted(self, wired, tmp_path): rebuilt = _settings(tmp_path, auth_sub="rebuilt-auth") rebuilt.env = "production" rebuilt.auth.local.admin_password = "" - rebuilt_app = create_app(settings=rebuilt) + rebuilt_app = create_app_without_reauth(settings=rebuilt) try: with TestClient(rebuilt_app, raise_server_exceptions=False) as rebuilt_client: assert rebuilt_client.get("/api/v1/auth/setup-status").json()["admin_retired"] diff --git a/tests/unit/test_api/test_root_accounts.py b/tests/unit/test_api/test_root_accounts.py index 640a11021..5653fc7d2 100644 --- a/tests/unit/test_api/test_root_accounts.py +++ b/tests/unit/test_api/test_root_accounts.py @@ -14,8 +14,10 @@ from dfe_engine.settings import DFESettings from tests.support.accounts import session_token from tests.unit.test_api.root_accounts_cases import ( + ORG_DISPLAY_NAME_CASES, ORG_FILTER_CASES, SESSION_ORG_CASES, + OrgDisplayNameCase, OrgFilterCase, SessionOrgCase, ) @@ -79,3 +81,20 @@ def test_org( ).json() listed = {item["username"] for item in page["items"]} assert listed & {"acme-amy", "globex-bob", "root-kim"} == case["expected"] + + +class TestOrgDisplayName: + @pytest.mark.parametrize( + "case", ORG_DISPLAY_NAME_CASES, ids=[case["id"] for case in ORG_DISPLAY_NAME_CASES] + ) + def test_matches_expected( + self, + admin_headers: dict[str, str], + app: FastAPI, + client: TestClient, + case: OrgDisplayNameCase, + ): + _name_your_org(app=app, name=case["your_org"]) + _store_kim(app=app, org=case["account_org"]) + body = client.get("/api/v1/auth/accounts/kim", headers=admin_headers).json() + assert body["org_display_name"] == case["expected_org_display_name"] diff --git a/tests/unit/test_api/test_scoped_groups.py b/tests/unit/test_api/test_scoped_groups.py index 6e7ceac81..2a17dd188 100644 --- a/tests/unit/test_api/test_scoped_groups.py +++ b/tests/unit/test_api/test_scoped_groups.py @@ -44,7 +44,7 @@ def scoped_setup(client: TestClient, app, admin_headers: dict[str, str]): account_store.create(username, f"pw-{username}") for name, roles, members in ( - ("acme-admins", ["admin"], ["orgadmin"]), + ("acme-ops", ["admin"], ["orgadmin"]), ("acme-analysts", ["data_analyst"], ["orguser"]), ): resp = client.post( @@ -94,7 +94,8 @@ def test_org_admin_sees_own_org_groups(self, scoped_setup, api_settings): ) assert resp.status_code == 200 names = {g["name"] for g in resp.json()["items"]} - assert names == {"acme-admins", "acme-analysts"} + # Creating acme made its admin and viewer groups too. + assert names == {"acme-admins", "acme-analysts", "acme-ops", "acme-viewers"} class TestOrgLocalAdmin: diff --git a/tests/unit/test_api/test_system_bound_scoped_fence.py b/tests/unit/test_api/test_system_bound_scoped_fence.py index edfef4da1..09ebe3108 100644 --- a/tests/unit/test_api/test_system_bound_scoped_fence.py +++ b/tests/unit/test_api/test_system_bound_scoped_fence.py @@ -265,8 +265,6 @@ def test_a_read_it_does_not_hold_is_refused(self, viewer, path): # Each read gated on a system-scope role check that no handler holds to the caller's orgs. UNHELD_READS = [ - pytest.param("/api/v1/auth/accounts", id="accounts-list"), - pytest.param("/api/v1/auth/accounts/admin", id="account"), pytest.param("/api/v1/auth/accounts/admin/git-status", id="account-git-status"), pytest.param("/api/v1/auth/accounts/admin/attributes", id="account-attributes"), pytest.param("/api/v1/auth/accounts/admin/sensitive-attributes", id="account-sensitive"), @@ -296,6 +294,33 @@ def test_an_admin_is_not_refused(self, client, admin_headers, path): assert client.get(path, headers=admin_headers).status_code != 403 +class TestAccountReads: + """Account reads are held to the orgs a caller's grants reach, like the org routes.""" + + @pytest.fixture + def reader(self, app, api_settings, orgs) -> TestClient: + define_role(app, "tenant_reader", UNHELD_PERMISSIONS, scoped=True) + for username, org in (("ann-acme", "acme"), ("bob-beta", "beta")): + app.state.account_store.create(username, "", groups=[]) + app.state.account_store.update(username, org=org) + return caller_in_group( + app, api_settings, "reader-acme", roles=["tenant_reader"], org_ids=["acme"] + ) + + def test_the_list_shows_only_the_org_the_group_names(self, reader): + resp = reader.get("/api/v1/auth/accounts") + + assert resp.status_code == 200, resp.text + assert [item["username"] for item in resp.json()["items"]] == ["ann-acme"] + + @pytest.mark.parametrize("username", ["admin", "bob-beta"]) + def test_an_account_outside_it_is_not_found(self, reader, username): + assert reader.get(f"/api/v1/auth/accounts/{username}").status_code == 404 + + def test_an_account_of_the_org_the_group_names_is_read(self, reader): + assert reader.get("/api/v1/auth/accounts/ann-acme").status_code == 200 + + class TestSystemGroupWrite: def test_a_system_scope_group_it_creates_reaches_no_org( self, tenant, app, client, admin_headers diff --git a/tests/unit/test_api/test_system_status.py b/tests/unit/test_api/test_system_status.py index c06310dcf..6cecfe87c 100644 --- a/tests/unit/test_api/test_system_status.py +++ b/tests/unit/test_api/test_system_status.py @@ -15,10 +15,10 @@ from prometheus_client.parser import text_string_to_metric_families from scalo.metrics import create_metrics -from dfe_engine.api.app import create_app from dfe_engine.api.deps import _registries from dfe_engine.yaml_health import WRITE_FAILURES from tests.support.accounts import admin_on_its_own_password +from tests.support.reauth import create_app_without_reauth STATUS = "/api/v1/system/status" GROUPS = "/api/v1/auth/groups" @@ -67,7 +67,7 @@ def test_the_status_report_needs_system_read(client: TestClient, viewer_headers: def test_a_refused_write_is_counted_on_the_engines_metrics(api_settings, admin_headers): manager = create_metrics("test", backend="prometheus", enable_auto_update=False) - app = create_app(settings=api_settings, metrics_manager=manager) + app = create_app_without_reauth(settings=api_settings, metrics_manager=manager) try: with TestClient(app, raise_server_exceptions=False) as client: admin_on_its_own_password(app) diff --git a/tests/unit/test_api/test_token_cookie.py b/tests/unit/test_api/test_token_cookie.py index 60b3c8b15..dae9fc66f 100644 --- a/tests/unit/test_api/test_token_cookie.py +++ b/tests/unit/test_api/test_token_cookie.py @@ -33,7 +33,10 @@ def has_provider(self, name: str) -> bool: async def handle_callback(self, provider: str, request) -> NormalizedIdentity: return NormalizedIdentity( - subject="alice@example.com", email="alice@example.com", groups=["dfe-admins"] + email_verified=True, + subject="alice@example.com", + email="alice@example.com", + groups=["dfe-admins"], ) diff --git a/tests/unit/test_api/test_view_custom_role.py b/tests/unit/test_api/test_view_custom_role.py index 1a690abff..830825102 100644 --- a/tests/unit/test_api/test_view_custom_role.py +++ b/tests/unit/test_api/test_view_custom_role.py @@ -35,6 +35,8 @@ def test_a_custom_role_holding_query_execute_runs_a_view( assert ( client.post("/api/v1/orgs", json={"name": "acme"}, headers=admin_headers).status_code == 201 ) + # An org account holds only its org's admin or viewer group, so the runner is a root account of your org. + app.state.org_registry.home.set(actor="test", name="acme") role = client.post( "/api/v1/auth/roles", json={"name": "view_runner", "permissions": ["query:execute"], "scoped": True}, @@ -45,7 +47,12 @@ def test_a_custom_role_holding_query_execute_runs_a_view( app.state.group_store.update("runners", org_ids=["acme"]) created = client.post( "/api/v1/auth/accounts", - json={"username": "runner", "password": PASSWORD, "groups": ["runners"], "org": "acme"}, + json={ + "name": "Test User", + "username": "runner", + "password": PASSWORD, + "groups": ["runners"], + }, headers=admin_headers, ) assert created.status_code == 201, created.text diff --git a/tests/unit/test_api/test_view_execute_options.py b/tests/unit/test_api/test_view_execute_options.py index ea8ca4ad1..34f1997c1 100644 --- a/tests/unit/test_api/test_view_execute_options.py +++ b/tests/unit/test_api/test_view_execute_options.py @@ -36,8 +36,8 @@ def _install(app, params: list[ViewParameter]) -> None: catalog=OneViewCatalog(view_definition(params)), # ty: ignore[invalid-argument-type] # a stand-in catalog serving one view database="dfe", ) - # The view is held to the session's org, so the admin account is bound to one. - app.state.account_store.update("admin", org="test-org") + # The view is held to the session's org, so the root admin is bound to your org. + app.state.org_registry.home.set(actor="test", name="test-org") @pytest.fixture diff --git a/tests/unit/test_auth/factories.py b/tests/unit/test_auth/factories.py index d7db03501..bf32c63b4 100644 --- a/tests/unit/test_auth/factories.py +++ b/tests/unit/test_auth/factories.py @@ -14,8 +14,10 @@ from authlib.integrations.starlette_client import OAuth -from dfe_engine.auth.accounts import AccountStore +from dfe_engine.auth.accounts import Account, AccountStore, LinkedIdentity from dfe_engine.auth.groups import Group, GroupStore +from dfe_engine.auth.identity_links import LinkTicket +from dfe_engine.auth.jit import JitProvisioner from dfe_engine.auth.oidc.adapters.entra import GraphCredentials from dfe_engine.auth.oidc.field_rules import FieldProblem from dfe_engine.auth.oidc.models import OIDCProvider @@ -27,6 +29,16 @@ # The env var an Okta provider from make_okta_directory_provider reads its API token from. OKTA_API_TOKEN_ENV = "DFE_TEST_OKTA_API_TOKEN" +# What an account with no usable password stores, so verify_password never matches it. +PASSWORDLESS_HASH = "!" + + +def make_account( + *, username: str, password_hash: str = PASSWORDLESS_HASH, **kwargs: object +) -> Account: + """Build an auth.accounts.Account, passwordless unless a hash is given.""" + return Account.model_validate({"password_hash": password_hash, "username": username, **kwargs}) + def make_account_store(*, directory: Path) -> AccountStore: """Build an auth.accounts.AccountStore over a directory of account files.""" @@ -55,6 +67,29 @@ def make_group_store(*, directory: Path) -> GroupStore: return GroupStore(directory) +def make_jit_provisioner(*, account_store: AccountStore, group_store: GroupStore) -> JitProvisioner: + """Build an auth.jit.JitProvisioner with no HyperDX client and no provider bindings.""" + return JitProvisioner(account_store, group_store) + + +def make_link_ticket( + *, account: str, email: str, provider: str, subject: str, **kwargs: object +) -> LinkTicket: + """Build an auth.identity_links.LinkTicket.""" + return LinkTicket.model_validate( + {"account": account, "email": email, "provider": provider, "subject": subject, **kwargs} + ) + + +def make_linked_identity( + *, key: str, provider: str, subject: str, **kwargs: object +) -> LinkedIdentity: + """Build an auth.accounts.LinkedIdentity.""" + return LinkedIdentity.model_validate( + {"key": key, "provider": provider, "subject": subject, **kwargs} + ) + + def make_local_idp() -> LocalIdp: """Build a tests.unit.test_auth.test_oidc.local_idp.LocalIdp (not yet started).""" return LocalIdp() diff --git a/tests/unit/test_auth/jit_cases.py b/tests/unit/test_auth/jit_cases.py new file mode 100644 index 000000000..22ca02b0f --- /dev/null +++ b/tests/unit/test_auth/jit_cases.py @@ -0,0 +1,247 @@ +# Project: dfe-engine +# File: tests/unit/test_auth/jit_cases.py +# Purpose: Case tables for linking a first IdP login to an account by its email +# Language: Python +# +# License: BUSL-1.1 +# Copyright: (c) 2026 HYPERI PTY LIMITED + +"""Case tables for linking a first IdP login to an account by its email.""" + +from typing import Any, TypedDict + +from dfe_engine.auth.accounts import Account +from dfe_engine.auth.jit import ( + JitAccountUnavailableError, + JitEmailHeldError, + JitEmailUntrustedError, + JitLinkRequiredError, + JitNoRoleError, +) +from dfe_engine.auth.models import AuthenticationError +from tests.unit.test_auth.factories import make_account + +ENTRA_SUBJECT = "oid-0001" +"""The entra login every row makes. It sanitises to itself, so it is also the sign-in's key.""" + +JANE = "jane@corp.com" + +LINK_REQUIRED_MESSAGE = "Sign in with this account's password to link your identity provider to it" + +EMAIL_UNTRUSTED_MESSAGE = ( + "OIDC login refused: this identity provider did not verify an email in a domain it " + "is trusted for. Ask a DFE administrator to trust your email domain on it." +) + +EMAIL_HELD_MESSAGE = ( + "OIDC login refused: another DFE account already uses this email. Ask a DFE " + "administrator to trust your email domain on this identity provider." +) + +NO_ROLE_MESSAGE = ( + "OIDC login refused: no DFE group with a role is linked to your identity provider " + "groups. Ask a DFE administrator to link one." +) + + +def _local(*, email: str = JANE, username: str = "kaz", **kwargs: Any) -> Account: + """A local account holding *email*.""" + return make_account(email=email, username=username, **kwargs) + + +def _okta( + *, email: str = JANE, email_verified: bool = True, username: str = "jane-okta", **kwargs: Any +) -> Account: + """An account an okta login created, holding *email*.""" + return make_account( + email=email, + email_verified=email_verified, + external=True, + source_provider="okta", + subject="00u1", + username=username, + **kwargs, + ) + + +class EnsureAccountLinkCase(TypedDict): + id: str + email: str + email_verified: bool | None + expected_identity_keys: list[str] + expected_linked_to: str + expected_username: str + stored: list[Account] + + +ENSURE_ACCOUNT_LINK_CASES: list[EnsureAccountLinkCase] = [ + { + "id": "an_idp_account_links_at_once", + "email": JANE, + "email_verified": True, + "expected_identity_keys": [ENTRA_SUBJECT], + "expected_linked_to": "jane-okta", + "expected_username": "jane-okta", + "stored": [_okta()], + }, + { + "id": "emails_match_ignoring_case", + "email": JANE, + "email_verified": True, + "expected_identity_keys": [ENTRA_SUBJECT], + "expected_linked_to": "jane-okta", + "expected_username": "jane-okta", + "stored": [_okta(email=" Jane@Corp.COM")], + }, + { + "id": "a_proxied_login_never_links", + "email": JANE, + "email_verified": None, + "expected_identity_keys": [], + "expected_linked_to": "", + "expected_username": ENTRA_SUBJECT, + "stored": [_okta()], + }, + { + "id": "a_recovery_credential_is_no_match", + "email": JANE, + "email_verified": True, + "expected_identity_keys": [], + "expected_linked_to": "", + "expected_username": ENTRA_SUBJECT, + "stored": [_local(groups=["dfe-admins"], username="admin")], + }, + { + "id": "a_soft_deleted_account_is_no_match", + "email": JANE, + "email_verified": True, + "expected_identity_keys": [], + "expected_linked_to": "", + "expected_username": ENTRA_SUBJECT, + "stored": [_local(previous_username="kaz", username="0b9f-deleted")], + }, + { + "id": "a_self_set_local_email_is_no_match", + "email": JANE, + "email_verified": True, + "expected_identity_keys": [], + "expected_linked_to": "", + "expected_username": ENTRA_SUBJECT, + "stored": [_local(email_verified=False)], + }, + { + "id": "a_link_record_is_no_match", + "email": JANE, + "email_verified": True, + "expected_identity_keys": [], + "expected_linked_to": "", + "expected_username": ENTRA_SUBJECT, + "stored": [_local(linked_to="someone", username="00u9")], + }, +] + + +class EnsureAccountLinkRefusedCase(TypedDict): + id: str + email_verified: bool + expected_error: type[AuthenticationError] + expected_message: str + oidc_groups: list[str] + stored: list[Account] + + +ENSURE_ACCOUNT_LINK_REFUSED_CASES: list[EnsureAccountLinkRefusedCase] = [ + { + "email_verified": True, + "id": "a_local_account_needs_its_password", + "expected_error": JitLinkRequiredError, + "expected_message": LINK_REQUIRED_MESSAGE, + "oidc_groups": ["dfe-analysts"], + "stored": [_local()], + }, + { + "email_verified": True, + "id": "a_disabled_match_refuses", + "expected_error": JitAccountUnavailableError, + "expected_message": "Account disabled", + "oidc_groups": ["dfe-analysts"], + "stored": [_local(enabled=False)], + }, + { + "email_verified": True, + "id": "a_blocked_match_refuses", + "expected_error": JitAccountUnavailableError, + "expected_message": "Account blocked", + "oidc_groups": ["dfe-analysts"], + "stored": [_okta(blocked=True)], + }, + { + "email_verified": True, + "id": "a_match_left_holding_no_role_refuses", + "expected_error": JitNoRoleError, + "expected_message": NO_ROLE_MESSAGE, + "oidc_groups": ["unlinked-team"], + "stored": [_local()], + }, + { + "email_verified": True, + "id": "two_vouched_holders_refuse", + "expected_error": JitEmailHeldError, + "expected_message": EMAIL_HELD_MESSAGE, + "oidc_groups": ["dfe-analysts"], + "stored": [_local(), _local(username="kaz2")], + }, + { + "email_verified": False, + "id": "an_untrusted_email_another_account_holds_refuses", + "expected_error": JitEmailUntrustedError, + "expected_message": EMAIL_UNTRUSTED_MESSAGE, + "oidc_groups": ["dfe-analysts"], + "stored": [_local()], + }, + { + "email_verified": False, + "id": "an_untrusted_email_nobody_holds_refuses", + "expected_error": JitEmailUntrustedError, + "expected_message": EMAIL_UNTRUSTED_MESSAGE, + "oidc_groups": ["dfe-analysts"], + "stored": [], + }, + { + "email_verified": True, + "id": "an_unvouched_idp_account_holding_it_refuses", + "expected_error": JitEmailHeldError, + "expected_message": EMAIL_HELD_MESSAGE, + "oidc_groups": ["dfe-analysts"], + "stored": [_okta(email_verified=False)], + }, +] + + +class CompleteLinkStaleCase(TypedDict): + """A store that changed after a ticket naming the local account kaz was issued.""" + + id: str + stored: list[Account] + + +COMPLETE_LINK_STALE_CASES: list[CompleteLinkStaleCase] = [ + {"id": "the_account_changed_its_email", "stored": [_local(email="kaz@other.example")]}, + {"id": "a_second_account_holds_the_email", "stored": [_local(), _local(username="kaz2")]}, + { + "id": "an_idp_now_owns_the_account", + "stored": [_okta(username="kaz")], + }, + { + "id": "the_sign_in_has_its_own_account", + "stored": [ + _local(), + make_account( + external=True, + source_provider="entra", + subject=ENTRA_SUBJECT, + username=ENTRA_SUBJECT, + ), + ], + }, +] diff --git a/tests/unit/test_auth/membership_cases.py b/tests/unit/test_auth/membership_cases.py index 5ff97dfaa..a852899bc 100644 --- a/tests/unit/test_auth/membership_cases.py +++ b/tests/unit/test_auth/membership_cases.py @@ -10,6 +10,10 @@ from typing import TypedDict +from dfe_engine.auth.accounts import Account +from dfe_engine.auth.groups import Group +from tests.unit.test_auth.factories import make_account, make_group, make_linked_identity + class MembershipMirrorCase(TypedDict): id: str @@ -68,3 +72,83 @@ class MembershipMirrorCase(TypedDict): "expected_groups": [], }, ] + + +class GroupsHeldLinkedCase(TypedDict): + id: str + account: Account + bindings: dict[str, str] + expected_groups: list[str] + + +LINKED_SIGN_IN_GROUPS: list[Group] = [ + make_group(name="entra-admins", roles=["admin"], source_id="g-entra", source_provider="entra"), + make_group( + name="okta-analysts", roles=["data_analyst"], source_id="g-okta", source_provider="okta" + ), + make_group(name="scim-viewers", roles=["viewer"], source_id="g-scim", source_provider="scim"), +] + +GROUPS_HELD_LINKED_CASES: list[GroupsHeldLinkedCase] = [ + { + "id": "a_local_person_holds_its_linked_sign_ins_groups", + "account": make_account( + identities=[ + make_linked_identity(groups=["g-okta"], key="00u1", provider="okta", subject="00u1") + ], + username="kaz", + ), + "bindings": {}, + "expected_groups": ["okta-analysts"], + }, + { + "id": "a_linked_assertion_links_only_under_its_own_provider", + "account": make_account( + identities=[ + make_linked_identity( + groups=["g-entra"], key="00u1", provider="okta", subject="00u1" + ) + ], + username="kaz", + ), + "bindings": {}, + "expected_groups": [], + }, + { + "id": "a_local_persons_own_list_still_holds_nothing", + "account": make_account( + groups=["g-okta"], + identities=[make_linked_identity(key="00u1", provider="okta", subject="00u1")], + username="kaz", + ), + "bindings": {}, + "expected_groups": [], + }, + { + "id": "a_binding_joins_a_linked_sign_in_to_its_stamp", + "account": make_account( + identities=[ + make_linked_identity( + groups=["g-scim"], key="oid-1", provider="entra", subject="oid-1" + ) + ], + username="kaz", + ), + "bindings": {"scim": "entra"}, + "expected_groups": ["scim-viewers"], + }, + { + "id": "an_idp_person_holds_its_own_and_its_linked_assertions", + "account": make_account( + external=True, + groups=["g-entra"], + identities=[ + make_linked_identity(groups=["g-okta"], key="00u1", provider="okta", subject="00u1") + ], + source_provider="entra", + username="jane-corp-com", + ), + "bindings": {}, + "expected_groups": ["entra-admins", "okta-analysts"], + }, +] diff --git a/tests/unit/test_auth/test_accounts.py b/tests/unit/test_auth/test_accounts.py index 4bba7aea7..765414d02 100644 --- a/tests/unit/test_auth/test_accounts.py +++ b/tests/unit/test_auth/test_accounts.py @@ -566,6 +566,40 @@ def test_block_sets_a_new_timestamp(self, store): # --------------------------------------------------------------------------- +class TestLinkRecords: + def test_a_link_record_lives_under_links_until_it_is_unlinked(self, store, tmp_path): + accounts = tmp_path / "accounts" + store.create("00u1", "") + store.update("00u1", linked_to="kaz") + linked = ( + sorted(path.name for path in accounts.glob("*.yaml")), + sorted(path.name for path in (accounts / "links").glob("*.yaml")), + store.get("00u1").linked_to, + [account.username for account in store.scan()], + ) + store.update("00u1", linked_to="") + freed = ( + sorted(path.name for path in accounts.glob("*.yaml")), + sorted(path.name for path in (accounts / "links").glob("*.yaml")), + ) + assert (linked, freed) == ( + ([], ["00u1.yaml"], "kaz", ["00u1"]), + (["00u1.yaml"], []), + ) + + def test_a_link_records_name_cannot_be_created_again(self, store): + store.create("00u1", "") + store.update("00u1", linked_to="kaz") + with pytest.raises(ValueError, match="Account already exists: 00u1"): + store.create("00u1", "") + + def test_deleting_a_link_record_removes_its_file(self, store, tmp_path): + store.create("00u1", "") + store.update("00u1", linked_to="kaz") + store.delete("00u1") + assert (store.get("00u1"), list((tmp_path / "accounts" / "links").iterdir())) == (None, []) + + class TestResetPassword: def test_new_password_works(self, store): store.create("alice", "oldpass") diff --git a/tests/unit/test_auth/test_hyperdx_role.py b/tests/unit/test_auth/test_hyperdx_role.py index 2f959c471..abf9696b0 100644 --- a/tests/unit/test_auth/test_hyperdx_role.py +++ b/tests/unit/test_auth/test_hyperdx_role.py @@ -31,6 +31,7 @@ "infra_admin": (ADMIN, VIEWER), "infra_viewer": (VIEWER, VIEWER), "ingest_admin": (VIEWER, VIEWER), + "org_admin": (VIEWER, VIEWER), "org_viewer": (VIEWER, VIEWER), } diff --git a/tests/unit/test_auth/test_jit.py b/tests/unit/test_auth/test_jit.py index 4d9cc4664..d6e1f88ca 100644 --- a/tests/unit/test_auth/test_jit.py +++ b/tests/unit/test_auth/test_jit.py @@ -9,6 +9,7 @@ import asyncio import gc import json +import re import warnings import pytest @@ -32,6 +33,17 @@ from tests.support.loopback import CountingListener from tests.support.present import present from tests.support.racing_stores import RacingAccountStore +from tests.unit.test_auth.factories import make_jit_provisioner, make_link_ticket +from tests.unit.test_auth.jit_cases import ( + COMPLETE_LINK_STALE_CASES, + ENSURE_ACCOUNT_LINK_CASES, + ENSURE_ACCOUNT_LINK_REFUSED_CASES, + ENTRA_SUBJECT, + JANE, + CompleteLinkStaleCase, + EnsureAccountLinkCase, + EnsureAccountLinkRefusedCase, +) NO_LOOP_EVENT = "JIT HyperDX invite skipped - no running event loop" @@ -253,6 +265,176 @@ def test_blocked_account_is_refused_and_left_untouched(self, stores): ) +def _linked_jane(*, accounts: AccountStore, groups: GroupStore) -> JitProvisioner: + """Store an okta account for jane, link an entra sign-in to it, and return the provisioner.""" + accounts.create("jane-okta", "", email=JANE) + accounts.update( + "jane-okta", email_verified=True, external=True, source_provider="okta", subject="00u1" + ) + jit = make_jit_provisioner(account_store=accounts, group_store=groups) + jit.ensure_account(ENTRA_SUBJECT, ["dfe-analysts"], "entra", email=JANE, email_verified=True) + return jit + + +class TestEnsureAccountLinks: + @pytest.mark.parametrize( + "case", ENSURE_ACCOUNT_LINK_CASES, ids=[case["id"] for case in ENSURE_ACCOUNT_LINK_CASES] + ) + def test_matches_expected(self, stores, case: EnsureAccountLinkCase): + accounts, groups = stores + for account in case["stored"]: + accounts.put(account=account, allow_protected=True) + jit = make_jit_provisioner(account_store=accounts, group_store=groups) + returned = jit.ensure_account( + ENTRA_SUBJECT, + ["dfe-analysts"], + "entra", + email=case["email"], + email_verified=case["email_verified"], + ) + record = accounts.get(ENTRA_SUBJECT) + assert ( + returned.username, + [identity.key for identity in returned.identities], + record.linked_to, + ) == (case["expected_username"], case["expected_identity_keys"], case["expected_linked_to"]) + + @pytest.mark.parametrize( + "case", + ENSURE_ACCOUNT_LINK_REFUSED_CASES, + ids=[case["id"] for case in ENSURE_ACCOUNT_LINK_REFUSED_CASES], + ) + def test_refused(self, stores, case: EnsureAccountLinkRefusedCase): + accounts, groups = stores + for account in case["stored"]: + accounts.put(account=account) + jit = make_jit_provisioner(account_store=accounts, group_store=groups) + with pytest.raises(case["expected_error"], match=re.escape(case["expected_message"])): + jit.ensure_account( + ENTRA_SUBJECT, + case["oidc_groups"], + "entra", + email=JANE, + email_verified=case["email_verified"], + ) + assert accounts.list() == case["stored"] + + def test_a_linked_session_binds_the_account(self, stores): + accounts, groups = stores + _linked_jane(accounts=accounts, groups=groups) + assert account_for_session_subject(accounts, ENTRA_SUBJECT).username == "jane-okta" + + def test_a_later_login_records_its_groups_on_its_entry(self, stores): + accounts, groups = stores + jit = _linked_jane(accounts=accounts, groups=groups) + returned = jit.ensure_account( + ENTRA_SUBJECT, ["dfe-admins", "dfe-analysts"], "entra", email=JANE + ) + assert (returned.username, returned.identities[0].groups, returned.groups) == ( + "jane-okta", + ["dfe-admins", "dfe-analysts"], + [], + ) + + def test_a_later_login_holding_no_role_ends_every_session(self, stores): + accounts, groups = stores + jit = _linked_jane(accounts=accounts, groups=groups) + before = accounts.get("jane-okta").session_generation + with pytest.raises(JitNoRoleError, match=re.escape(NO_ROLE_MESSAGE)): + jit.ensure_account(ENTRA_SUBJECT, ["unlinked-team"], "entra", email=JANE) + assert accounts.get("jane-okta").session_generation == before + 1 + + def test_a_disabled_account_refuses_its_linked_sign_ins(self, stores): + accounts, groups = stores + jit = _linked_jane(accounts=accounts, groups=groups) + accounts.update("jane-okta", enabled=False) + with pytest.raises(JitAccountUnavailableError, match="Account disabled"): + jit.ensure_account(ENTRA_SUBJECT, ["dfe-analysts"], "entra", email=JANE) + + def test_another_providers_login_cannot_use_a_link_record(self, stores): + accounts, groups = stores + jit = _linked_jane(accounts=accounts, groups=groups) + with pytest.raises(JitIdentityCollisionError, match="OIDC login refused"): + jit.ensure_account(ENTRA_SUBJECT, ["dfe-analysts"], "google", email=JANE) + + def test_a_proxied_email_change_drops_the_proof(self, stores): + accounts, groups = stores + jit = make_jit_provisioner(account_store=accounts, group_store=groups) + jit.ensure_account( + ENTRA_SUBJECT, ["dfe-analysts"], "entra", email=JANE, email_verified=True + ) + returned = jit.ensure_account( + ENTRA_SUBJECT, ["dfe-analysts"], "entra", email="evil@corp.com" + ) + assert (returned.email, returned.email_verified) == ("evil@corp.com", False) + + def test_a_link_record_nothing_lists_starts_again(self, stores): + accounts, groups = stores + jit = _linked_jane(accounts=accounts, groups=groups) + accounts.delete("jane-okta") + returned = jit.ensure_account(ENTRA_SUBJECT, ["dfe-analysts"], "entra", email=JANE) + assert (returned.username, returned.linked_to, returned.source_provider) == ( + ENTRA_SUBJECT, + "", + "entra", + ) + + +class TestCompleteLink: + def test_links_the_local_account(self, stores): + accounts, groups = stores + accounts.create("kaz", "", email=JANE) + jit = make_jit_provisioner(account_store=accounts, group_store=groups) + ticket = make_link_ticket( + account="kaz", + email=JANE, + groups=["dfe-analysts"], + provider="entra", + subject=ENTRA_SUBJECT, + ) + returned = jit.complete_link(ticket=ticket) + bound = account_for_session_subject(accounts, ENTRA_SUBJECT) + assert (returned.username, [i.key for i in returned.identities], bound.username) == ( + "kaz", + [ENTRA_SUBJECT], + "kaz", + ) + + def test_a_repeated_redemption_keeps_one_link(self, stores): + accounts, groups = stores + accounts.create("kaz", "", email=JANE) + jit = make_jit_provisioner(account_store=accounts, group_store=groups) + ticket = make_link_ticket( + account="kaz", + email=JANE, + groups=["dfe-analysts"], + provider="entra", + subject=ENTRA_SUBJECT, + ) + jit.complete_link(ticket=ticket) + returned = jit.complete_link(ticket=ticket) + assert (returned.username, [i.key for i in returned.identities]) == ("kaz", [ENTRA_SUBJECT]) + + @pytest.mark.parametrize( + "case", COMPLETE_LINK_STALE_CASES, ids=[case["id"] for case in COMPLETE_LINK_STALE_CASES] + ) + def test_stale(self, stores, case: CompleteLinkStaleCase): + accounts, groups = stores + for account in case["stored"]: + accounts.put(account=account) + jit = make_jit_provisioner(account_store=accounts, group_store=groups) + ticket = make_link_ticket( + account="kaz", + email=JANE, + groups=["dfe-analysts"], + provider="entra", + subject=ENTRA_SUBJECT, + ) + with pytest.raises(JitIdentityCollisionError, match="OIDC login refused") as refused: + jit.complete_link(ticket=ticket) + assert (refused.value.reason, accounts.list()) == ("link_stale", case["stored"]) + + class TestALoginThatWouldHoldNoRole: """The linked DFE groups are the allowlist: an IdP user in none of them gets no account.""" diff --git a/tests/unit/test_auth/test_local_provider.py b/tests/unit/test_auth/test_local_provider.py index d6ebafb97..a62d79013 100644 --- a/tests/unit/test_auth/test_local_provider.py +++ b/tests/unit/test_auth/test_local_provider.py @@ -4,6 +4,7 @@ from collections.abc import Callable, Generator from contextlib import contextmanager from pathlib import Path +from typing import TypedDict import bcrypt import pytest @@ -17,6 +18,7 @@ from dfe_engine.auth.groups import GroupStore from dfe_engine.auth.local_provider import LocalAuthProvider from tests.support.present import present +from tests.unit.test_auth.factories import make_account # --------------------------------------------------------------------------- # Fixtures @@ -67,6 +69,81 @@ def provider( return LocalAuthProvider(account_store, group_store) +KAZ = "kaz@corp.com" + + +class AccountNameCase(TypedDict): + id: str + expected: str + identifier: str + stored: list[Account] + + +ACCOUNT_NAME_CASES: list[AccountNameCase] = [ + {"id": "an_account_name_is_itself", "identifier": "viewer", "stored": [], "expected": "viewer"}, + { + "id": "a_vouched_local_email", + "identifier": KAZ, + "stored": [make_account(email=KAZ, email_verified=True, username="kaz")], + "expected": "kaz", + }, + { + "id": "case_and_spaces_are_ignored", + "identifier": "KAZ@Corp.com", + "stored": [make_account(email=f" {KAZ} ", email_verified=True, username="kaz")], + "expected": "kaz", + }, + { + "id": "a_local_email_from_before_the_flag", + "identifier": KAZ, + "stored": [make_account(email=KAZ, username="kaz")], + "expected": "kaz", + }, + { + "id": "a_self_set_email_names_nobody", + "identifier": KAZ, + "stored": [make_account(email=KAZ, email_verified=False, username="kaz")], + "expected": KAZ, + }, + { + "id": "two_holders_name_nobody", + "identifier": KAZ, + "stored": [ + make_account(email=KAZ, email_verified=True, username="kaz"), + make_account(email=KAZ, email_verified=True, username="kaz2"), + ], + "expected": KAZ, + }, + { + "id": "an_idp_accounts_email_names_nobody", + "identifier": KAZ, + "stored": [ + make_account( + email=KAZ, + email_verified=True, + external=True, + source_provider="okta", + username="00u1", + ) + ], + "expected": KAZ, + }, + {"id": "an_unknown_email_names_nobody", "identifier": KAZ, "stored": [], "expected": KAZ}, +] + + +class TestAccountName: + @pytest.mark.parametrize( + "case", ACCOUNT_NAME_CASES, ids=[case["id"] for case in ACCOUNT_NAME_CASES] + ) + def test_matches_expected(self, stores: tuple[AccountStore, GroupStore], case: AccountNameCase): + account_store, group_store = stores + for account in case["stored"]: + account_store.put(account=account) + provider = LocalAuthProvider(account_store, group_store) + assert provider.account_name(case["identifier"]) == case["expected"] + + # --------------------------------------------------------------------------- # Authentication success # --------------------------------------------------------------------------- diff --git a/tests/unit/test_auth/test_membership.py b/tests/unit/test_auth/test_membership.py index e91aaf6b9..51d4699c8 100644 --- a/tests/unit/test_auth/test_membership.py +++ b/tests/unit/test_auth/test_membership.py @@ -29,7 +29,13 @@ ) from tests.support.present import present from tests.unit.test_auth.factories import make_account_store -from tests.unit.test_auth.membership_cases import MEMBERSHIP_MIRROR_CASES, MembershipMirrorCase +from tests.unit.test_auth.membership_cases import ( + GROUPS_HELD_LINKED_CASES, + LINKED_SIGN_IN_GROUPS, + MEMBERSHIP_MIRROR_CASES, + GroupsHeldLinkedCase, + MembershipMirrorCase, +) class TestSyncAccountGroupsForMembershipChange: @@ -204,6 +210,15 @@ def test_membership_and_linked_groups_are_both_held(self): ] assert groups_held(account, groups, bindings={}) == ["by-hand", "by-link"] + @pytest.mark.parametrize( + "case", GROUPS_HELD_LINKED_CASES, ids=[case["id"] for case in GROUPS_HELD_LINKED_CASES] + ) + def test_linked_sign_ins(self, case: GroupsHeldLinkedCase): + held = groups_held( + account=case["account"], bindings=case["bindings"], groups=LINKED_SIGN_IN_GROUPS + ) + assert held == case["expected_groups"] + class TestGroupsHeldAfter: def test_an_idp_accounts_new_list_is_its_assertion_and_its_membership(self): diff --git a/tests/unit/test_auth/test_oidc/rp_cases.py b/tests/unit/test_auth/test_oidc/rp_cases.py index a48a6a9b3..69854b739 100644 --- a/tests/unit/test_auth/test_oidc/rp_cases.py +++ b/tests/unit/test_auth/test_oidc/rp_cases.py @@ -290,6 +290,58 @@ class NeedsDirectoryGroupsCase(TypedDict): issuer="https://login.microsoftonline.com/tid/v2.0", type="entra_id" ), }, + { + "id": "email_verified_vouches_for_the_email", + "claims": {"sub": "00u2", "email": "jane@corp.com", "email_verified": True}, + "expected_identity": make_normalized_identity( + email="jane@corp.com", email_verified=True, subject="00u2" + ), + "provider": make_oidc_provider(issuer="https://acme.okta.com", type="okta"), + }, + { + "id": "email_verified_sent_as_a_string", + "claims": {"sub": "00u2", "email": "jane@corp.com", "email_verified": " True "}, + "expected_identity": make_normalized_identity( + email="jane@corp.com", email_verified=True, subject="00u2" + ), + "provider": make_oidc_provider(issuer="https://acme.okta.com", type="okta"), + }, + { + "id": "email_verified_false", + "claims": {"sub": "00u2", "email": "jane@corp.com", "email_verified": False}, + "expected_identity": make_normalized_identity(email="jane@corp.com", subject="00u2"), + "provider": make_oidc_provider(issuer="https://acme.okta.com", type="okta"), + }, + { + "id": "entra_xms_edov_vouches_for_the_email", + "claims": {"sub": "pairwise-sub", "email": "jane@corp.com", "xms_edov": True}, + "expected_identity": make_normalized_identity( + email="jane@corp.com", email_verified=True, subject="pairwise-sub" + ), + "provider": make_oidc_provider( + issuer="https://login.microsoftonline.com/tid/v2.0", type="entra_id" + ), + }, + { + "id": "entra_email_without_xms_edov_is_unverified", + "claims": {"sub": "pairwise-sub", "email": "jane@corp.com"}, + "expected_identity": make_normalized_identity( + email="jane@corp.com", subject="pairwise-sub" + ), + "provider": make_oidc_provider( + issuer="https://login.microsoftonline.com/tid/v2.0", type="entra_id" + ), + }, + { + "id": "username_fallback_is_never_verified", + "claims": {"sub": "pairwise-sub", "email_verified": True, "upn": "jane@corp.com"}, + "expected_identity": make_normalized_identity( + email="jane@corp.com", subject="pairwise-sub" + ), + "provider": make_oidc_provider( + issuer="https://login.microsoftonline.com/tid/v2.0", type="entra_id" + ), + }, ] FILL_FROM_USERINFO_ENDPOINT_CASES: list[FillFromUserinfoEndpointCase] = [ @@ -392,6 +444,30 @@ class NeedsDirectoryGroupsCase(TypedDict): "id_token_claims": {"sub": "s", "aud": "dfe"}, "userinfo_claims": {"sub": "s"}, }, + { + "id": "userinfo_email_brings_its_proof", + "expected_claims": {"sub": "s", "email": "jane@corp.com", "email_verified": True}, + "id_token_claims": {"sub": "s", "email_verified": False}, + "userinfo_claims": {"sub": "s", "email": "jane@corp.com", "email_verified": True}, + }, + { + "id": "userinfo_email_without_proof_drops_the_token_proof", + "expected_claims": {"sub": "s", "email": "jane@corp.com"}, + "id_token_claims": {"sub": "s", "xms_edov": True}, + "userinfo_claims": {"sub": "s", "email": "jane@corp.com"}, + }, + { + "id": "userinfo_fills_the_proof_of_the_same_email", + "expected_claims": {"sub": "s", "email": "Jane@corp.com", "email_verified": True}, + "id_token_claims": {"sub": "s", "email": "Jane@corp.com"}, + "userinfo_claims": {"sub": "s", "email": "jane@corp.com", "email_verified": True}, + }, + { + "id": "id_token_email_keeps_its_own_proof", + "expected_claims": {"sub": "s", "email": "a@corp.com", "email_verified": False}, + "id_token_claims": {"sub": "s", "email": "a@corp.com", "email_verified": False}, + "userinfo_claims": {"sub": "s", "email": "b@corp.com", "email_verified": True}, + }, ] MERGE_USERINFO_CLAIMS_SUBJECT_MISMATCH_CASES: list[MergeUserinfoClaimsSubjectMismatchCase] = [ diff --git a/tests/unit/test_auth/test_oidc/test_models.py b/tests/unit/test_auth/test_oidc/test_models.py index bc3fda248..28c1738ea 100644 --- a/tests/unit/test_auth/test_oidc/test_models.py +++ b/tests/unit/test_auth/test_oidc/test_models.py @@ -46,6 +46,11 @@ def test_defaults(self): assert provider.last_sync_status == "" assert provider.sync_error == "" assert provider.groups == GroupResolutionConfig() + assert provider.trusted_email_domains == [] + + def test_a_stored_provider_loads_its_trusted_domains_folded(self): + provider = OIDCProvider.model_validate({"trusted_email_domains": ["Corp.COM ", "corp.com"]}) + assert provider.trusted_email_domains == ["corp.com"] GOOGLE_SCOPES = ( diff --git a/tests/unit/test_auth/test_oidc/test_rp.py b/tests/unit/test_auth/test_oidc/test_rp.py index 9be35fad2..5fc9c6869 100644 --- a/tests/unit/test_auth/test_oidc/test_rp.py +++ b/tests/unit/test_auth/test_oidc/test_rp.py @@ -73,6 +73,21 @@ class TestNeedsUserinfo: def test_matches_expected(self, claims: dict, expected: bool): assert needs_userinfo(claims=claims) is expected + @pytest.mark.parametrize( + ("claims", "expected"), + [ + ({"sub": "u1", "name": "Ada", "email": "ada@example.com"}, True), + ( + {"sub": "u1", "name": "Ada", "email": "ada@example.com", "email_verified": False}, + False, + ), + ({"sub": "u1", "name": "Ada", "email": "ada@example.com", "xms_edov": True}, False), + ], + ids=["no-proof", "email-verified-false", "xms-edov"], + ) + def test_a_trusted_provider_wants_email_proof(self, claims: dict, expected: bool): + assert needs_userinfo(claims=claims, wants_email_proof=True) is expected + class TestMergeUserinfoClaims: @pytest.mark.parametrize( diff --git a/tests/unit/test_auth/test_roles.py b/tests/unit/test_auth/test_roles.py index 6fab850b1..96b747b64 100644 --- a/tests/unit/test_auth/test_roles.py +++ b/tests/unit/test_auth/test_roles.py @@ -329,7 +329,7 @@ def test_load_builtin_succeeds(self): config = RoleConfig.load_builtin() assert config is not None - def test_load_builtin_has_all_nine_roles(self): + def test_load_builtin_has_every_role(self): config = RoleConfig.load_builtin() expected_roles = { "admin", @@ -339,6 +339,7 @@ def test_load_builtin_has_all_nine_roles(self): "infra_admin", "infra_viewer", "ingest_admin", + "org_admin", "org_viewer", "dfe_operator", } diff --git a/tests/unit/test_names.py b/tests/unit/test_names.py index e49120925..d392c2e68 100644 --- a/tests/unit/test_names.py +++ b/tests/unit/test_names.py @@ -79,7 +79,10 @@ def test_every_store_object_is_created_under_exactly_the_store_names(name, accep assert _accepted(lambda: validate_store_name(name)) is accepted assert _accepted(lambda: CreateRoleRequest(name=name, permissions=[])) is accepted assert _accepted(lambda: CreateGroupRequest(name=name, roles=[])) is accepted - assert _accepted(lambda: CreateAccountRequest(username=name, password=_PASSWORD)) is accepted + assert ( + _accepted(lambda: CreateAccountRequest(name="Test User", password=_PASSWORD, username=name)) + is accepted + ) assert _accepted(lambda: CreateAPIKeyRequest(name=name)) is accepted assert ( _accepted(lambda: CreateProviderRequest.model_validate({"name": name, **provider})) diff --git a/tests/unit/test_orgs/test_lifecycle.py b/tests/unit/test_orgs/test_lifecycle.py index 310d8afa8..cf800261f 100644 --- a/tests/unit/test_orgs/test_lifecycle.py +++ b/tests/unit/test_orgs/test_lifecycle.py @@ -21,6 +21,7 @@ from dfe_engine.orgs.lifecycle import OrgLifecycleManager from dfe_engine.orgs.registry import OrgRegistry +from tests.unit.test_auth.factories import make_group_store class FakeFork: @@ -160,3 +161,31 @@ async def test_an_answer_with_no_team_is_audited_as_such(registry, audit_events) (event,) = [e for e in audit_events if e["event"] == "org.hyperdx.provision_failed"] assert (event["org_name"], event["reason"]) == ("acme", "no_team") + + +def _group_shapes(*, store) -> dict[str, tuple[list[str], str]]: + """Every stored group's roles and scope, by name.""" + return {group.name: (group.roles, group.scope) for group in store.list()} + + +@pytest.mark.asyncio +async def test_create_org_makes_its_admin_and_viewer_groups(registry, tmp_path): + groups = make_group_store(directory=tmp_path / "groups") + manager = OrgLifecycleManager(registry, group_store=groups, hyperdx_client=None) + await manager.create_org("acme", admin_id="admin") + assert _group_shapes(store=groups) == { + "acme-admins": (["org_admin"], "org:acme"), + "acme-viewers": (["org_viewer"], "org:acme"), + } + + +@pytest.mark.asyncio +async def test_delete_org_drops_its_groups_and_keeps_anothers(registry, tmp_path): + groups = make_group_store(directory=tmp_path / "groups") + manager = OrgLifecycleManager(registry, group_store=groups, hyperdx_client=None) + await manager.create_org("acme", admin_id="admin") + await manager.create_org("globex", admin_id="admin") + groups.add_member("acme-viewers", "kim") + await manager.delete_org("acme", admin_id="admin") + left = (sorted(_group_shapes(store=groups)), registry.get("acme")) + assert left == (["globex-admins", "globex-viewers"], None)