Repository navigation
Description
Problem or use case
External API consumers and automation need to authenticate to Scope without an interactive user login or Personal Access Tokens (PATs), and receive only their assigned project permissions. This may also provide a foundation for future non-interactive CLI authentication.
Establish whether the complete flow works:
Application credentials → Entra access token intended for Scope → API authentication → application identity resolution → project-level authorization.
Token acquisition or a single HTTP 200 response is not sufficient proof. The investigation must demonstrate permitted operations, role restrictions, project isolation, and rejection of invalid tokens and missing memberships.
Proposed change
Complete the following acceptance checklist in two phases. This is a feasibility investigation, not authorization to change Scope authentication, provision cloud resources, grant consent, or change project access. Obtain approval before those changes.
Phase 1: Complete local validation with the Entra emulator
“Production Scope token validation” below means exercising the production implementation in the approved test environment, not testing against production infrastructure.
- 1. Approve an emulator-only correction. Confirm the change belongs in the emulator and keep Scope's token validation and RBAC enforcement intact.
- 2. Correct the app-only identity claim. Model or configure a stable tenant-local service-principal object ID and emit it as
oid. It must be distinct from the application's client ID. Scope identifies callers using the verified(identity provider, tenant ID, object ID)tuple; do not substitutesubor client ID for a missingoid. - 3. Correct the v2 audience. A request for
api://<Scope API client ID>/.defaultshould resolve to the API's client-ID GUID as the v2 access-token audience. Add emulator contract tests for the identity and audience invariants rather than widening Scope's accepted audiences. - 4. Acquire a fresh emulator-issued app-only token. Use client credentials with no browser or developer login. Check only necessary claims locally, including issuer, audience, tenant, object ID, and expiry. Keep credentials and tokens out of logs, reports, and external JWT inspection services.
- 5. Verify production Scope token validation. Send the actual emulator-issued token through the production authentication path with authentication and RBAC enabled. Confirm the verified identity belongs to the application. Distinguish token rejection from a valid identity denied because it is not enrolled.
- 6. Establish explicit application onboarding. Confirm and document the supported way to create the application's stable Scope identity. The existing
POST /api/v1/users/meendpoint mechanically supports enrollment of a conformant app-shaped identity, but its documented contract is user login. Confirm the resulting Scope UUID is distinct from the developer's identity and enrollment grants no project membership automatically. Document the current ordinary-user representation and decide whether a first-class external-application principal is needed. - 7. Verify Reader permissions. An authorized administrator grants Reader on a disposable project using the application's Scope UUID. Wait for the audited operation to complete; a pending response is not an effective grant. Verify a protected read succeeds and a content write returns
403without persisting content. - 8. Verify Contributor and Administrator boundaries. Change the application to Contributor: a content write must persist and be readable, while membership/role management must return
403without changing access. Separately verify that a project Administrator can manage membership only within the authorized project and cannot promote platform administrators. Check the actual implementation's permission bundles rather than inferring them from role names. - 9. Verify isolation, missing membership, and revocation. Deny project content to an enrolled application with no membership. Deny access to another project without a grant. After warming the identity cache, verify demotion, revocation, and identity disablement take effect. An incomplete membership operation must not grant access.
- 10. Verify negative tokens and repeatability. Reject missing, malformed, wrongly signed, expired, wrong-audience, and untrusted-issuer tokens before identity resolution. Use clearly labelled isolated automated fixtures for cases impractical to issue through the emulator. Diagnose intermittent failures rather than treating a passing rerun as proof of reliability. Record actual emulator observations separately from synthetic-token evidence.
Before moving to Phase 2, also complete these local acceptance criteria:
- Stable identity across token renewal. Acquire a second token through client credentials and verify it resolves to the same Scope UUID and memberships. Automation must not require interactive login or create duplicate identities when obtaining a replacement token.
- Tenant and principal isolation. Verify two applications cannot share identities or memberships. Using isolated synthetic fixtures where necessary, verify that the same
oidin different tenants resolves to different Scope identities. Document the intended single-/multi-tenant admission policy; an untrusted-issuer rejection alone does not prove isolation between valid Entra identities. - Complete the role matrix. Explicitly verify Reader and Contributor cannot change project settings or access the privileged membership roster. Verify a project Administrator can change authorized project settings but cannot manage memberships in an unassigned project. Record expected results from the examined specification and code.
- App-only proof and admission policy. Establish that the token is app-only using client-credentials issuance evidence and relevant verified claims. Document whether Entra application roles are required for admission or role-less app tokens are intentionally supported. Document how application and delegated callers are represented; a first-class principal kind or new token gate is not assumed necessary without investigation and approval.
- Reusable, pinned local evidence. Preserve a sanitized runnable test harness, pin the tested Scope revision and emulator image digest, and record the effective authentication/RBAC configuration. Separate emulator-issued-token evidence from synthetic-token fixtures and ensure commands and configuration contain no credentials.
Phase 2: Confirm with real Entra in an approved non-production environment
- 11. Identify and approve the bounded environment. Record the authorized test API and deployed revision, expected tenant/issuer/audience/token version, approved test application and credential method, and designated projects and expected roles. Prefer existing approved resources. Ask before creating identities or credentials, granting consent, or changing cloud/project access. Do not use production without explicit authorization.
- 12. Verify Entra configuration. Confirm the API registration requests the intended access-token version and that Scope's issuer, signing-key, and audience configuration aligns with it. Establish any required application-role assignment, assignment-required policy, and administrator consent. Entra application permissions/app roles, Azure resource RBAC, and Scope project memberships are separate systems; none substitutes for another.
- 13. Repeat the matrix with a real app-only token. Obtain a Scope-targeted token using the approved client-credentials method, not a token for Microsoft Graph or Azure Resource Manager. Repeat identity resolution, onboarding, role restrictions, project isolation, and revocation against the approved deployed API. Confirm the caller resolves to the service principal rather than the developer's signed-in user.
Pass condition: a real Entra Service Principal completes authentication and receives exactly its assigned Scope project permissions without interactive login, PATs, blanket administrator privileges, weakened validation, or RBAC bypasses.
- Confirm renewal and isolation with real Entra. Repeat replacement-token identity stability and application separation using approved resources. Keep impractical cross-tenant negative cases in clearly labelled isolated fixtures unless additional tenant resources are explicitly approved. Confirm the selected Entra application-role/admission policy matches the observed real token and deployed Scope behavior.
- Clean up the bounded experiment. Record cleanup or approved retention of test-created credentials, memberships, applications, and infrastructure. Obtain any required approval before cleanup, target only resources created for this experiment, and leave pre-existing approved resources and unrelated access untouched. Discard temporary token/secret material without publishing it.
Deliver a concise verdict, exact examined/deployed revisions, authentication and authorization flow, expected-versus-observed test matrix with evidence sources, credential-free reproduction commands, and remaining gaps. If a Scope change is necessary, describe the smallest coherent fix and required tests, then stop for approval.
Alternatives
- Synthetic application JWTs are useful for isolating Scope authentication and RBAC behavior but cannot establish emulator compatibility, real Entra issuance, or administrator consent.
- A successful token request or isolated successful API call does not demonstrate project authorization.
- Interactive developer login does not meet the automation use case.
- Introducing PATs is outside this investigation and should not be inferred as necessary from an initial failure.
- Internal service-to-service authentication using Kubernetes ServiceAccounts is a separate workstream and must remain unchanged. Preserve Azure Workload Identity used for access to Azure resources.
Additional context
Implementation investigated: #1532 at d74db0dc9f7013df1cd5d5a2a605ad3c6e2a1850, including its inherited authentication implementation. Findings are tied to that examined revision, not an assertion about the current default branch or latest PR head.
Local observations with ghcr.io/cmaneu/entra-local:0.1.1:
- Client-credentials tokens omitted
oid; Scope correctly rejected them with401 missing_claimbefore identity resolution or enrollment. - API-URI scopes produced a URI audience while declaring token version
2.0; Scope configured for the API GUID correctly rejected them with401 invalid_audience. - Separately signed, claim-conformant application JWTs exercised production Scope authentication and project authorization with real isolated MongoDB/Redis. These checks support the RBAC mechanics but are not emulator-issued-token or real-Entra end-to-end proof.
- Some existing local regression runs failed intermittently before successful reruns; reliability remains a separate validation item.
Real Entra end-to-end success remains unproven. No Scope application/infrastructure changes or real Entra provisioning were made during the investigation. Do not weaken Scope's fail-closed behavior to compensate for emulator token differences.
Public tracking should use placeholders only. Do not attach raw credential-bearing output, tokens, private keys, internal deployment URLs, operational identifiers, or unreviewed investigation logs.
Activity