Identity and sessions

intrnl is the identity broker

Each organization configures Entra once.

Hosted applications do not each receive a separate Entra integration, client secret, redirect URI, or raw Microsoft token.

Microsoft Entra ID
        ↓
intrnl identity broker
        ↓
normalized intrnl identity
        ↓
console, MCP and hosted apps

Microsoft’s identity platform supports OIDC-based SSO using tenant-scoped endpoints and signed ID tokens, making OIDC the initial identity integration for the pilot. Microsoft Entra OIDC

Organization Entra configuration

Use a single-tenant Entra application/enterprise application for the pilot organization in intrnl.

Authentication flow:

• Authorization Code flow
• PKCE
• state and nonce
• Tenant-specific issuer validation
• Audience validation
• Signature/JWKS validation
• Short authorization-code lifetime
• Redirect allowlist
• Rotated client secret or certificate credential

User identity is keyed by an immutable external identifier such as:

provider_id
entra_tenant_id (tid)
entra_object_id (oid) or stable subject

Never use email address as the primary identity key.

Email, display name, and department are mutable profile attributes.

Group and role handling

For the pilot organization, prefer:

1. Entra application roles for broad intrnl roles.
2. Groups assigned specifically to the intrnl enterprise application.
3. SCIM-managed group membership for complete lifecycle synchronization.
4. Microsoft Graph lookup only when genuinely needed.

Do not blindly emit every group in a user’s tenant. Entra can omit groups when token limits are exceeded; Microsoft documents limits of 200 groups for JWTs and 150 for SAML assertions and recommends application roles for new application authorization where appropriate. Microsoft group claims and app roles

Example mappings:

Entra app role: Intrnl.Creator
→ intrnl organization role: Creator

Entra app role: Intrnl.SecurityAdmin
→ intrnl organization role: Security Admin

Entra group: SG-Intrnl-Operations-Pilot
→ intrnl group: Operations Pilot

JIT provisioning

V1 supports just-in-time provisioning.

On the first valid organization login:

1. Validate the Entra identity.
2. Ensure the user is assigned to the enterprise application or approved group.
3. Create or update the intrnl user profile.
4. Create the organization membership.
5. Apply mapped roles/groups.
6. Issue an intrnl session.

JIT makes the pilot simple without preloading every employee.

SCIM

SCIM follows shortly after JIT and is part of the v1 enterprise architecture.

Implement:

/scim/v2/Users
/scim/v2/Groups

SCIM handles:

• User creation
• Attribute updates
• Activation/deactivation
• Group creation
• Group membership changes
• User and group deletion semantics

Microsoft Entra’s provisioning service can automate both provisioning and deprovisioning of users and groups through SCIM 2.0. Microsoft Entra SCIM provisioning

When an organization deactivates a user:

• Disable the organization membership.
• Revoke active console sessions.
• Revoke MCP grants.
• Disable direct Git access.
• Reassign or flag owned applications.
• Preserve their audit attribution.

Platform sessions

After upstream SSO, intrnl issues its own short-lived session.

Benefits:

• Consistent sessions across IdPs
• Central revocation
• No raw Entra tokens in app runtimes
• Easier multi-IdP support
• Stable authorization model
• Independent app-session lifetime

Refresh tokens or equivalent server-side session extensions should be rotated and revocable.

App authentication flow

Applications use a gateway-managed, host-specific session:

1. Browser requests equipment.example-org.<runtime-apex>
2. Gateway sees no app session
3. Browser redirects to auth.intrnl.cloud
4. Auth broker uses the existing intrnl/Entra session
5. Broker returns a one-time signed code
6. Runtime gateway establishes a host-only app session
7. Gateway evaluates app access policy
8. Request reaches workerd

Use cookies with properties equivalent to:

Secure
HttpOnly
Path=/
No Domain attribute
__Host- prefix

The gateway reserves and strips intrnl session-cookie names from application responses.

Application code cannot create, replace, or inspect the gateway’s authentication cookie.

Runtime identity assertion

The app does not receive the Entra token.

The gateway passes a short-lived, app-audience-bound assertion containing normalized identity:

{
  "sub": "usr_01K...",
  "org": "org_01K...",
  "aud": "app_01K...",
  "email": "user@example.com",
  "display_name": "Jane Smith",
  "groups": ["operations"],
  "roles": ["member"],
  "iat": 1789958300,
  "exp": 1789958360
}

Inbound user-supplied X-Intrnl-* headers are always stripped.

The runtime adapter verifies the assertion and exposes:

const user = context.user;

or in Nuxt:

const user = useIntrnlUser();

Platform access versus application authorization

The gateway determines:

May this person enter the app?

The application determines:

What can this person do once inside?

For example:

Gateway:
- Organization member
- Operations group
- approved network

Application:
- requester may create
- manager may approve
- finance may view cost

Generated app templates must include clear application-level authorization patterns rather than assuming SSO alone protects every record.

Break-glass access

Maintain a very small number of intrnl-native break-glass administrators.

Requirements:

• WebAuthn/passkey MFA
• No routine use
• Separate recovery process
• Highly visible audit events
• Alerting on every login
• Optional fixed-network restriction
• Periodic access review

Related documentation

• Governance
• Access policies