Admin portal with Microsoft Entra ID

The admin portal can be pointed at your Microsoft Entra ID tenant, so administrators sign in with their existing work accounts. OSIE keeps no identity state for them — accounts, credentials, and MFA stay in Entra, and each request is authorized from the token it carries (see Single Sign-On for what this mode implies).

The client portal is configured independently and can keep using the built-in identity service.

Three things are involved:

An app registration in Entra — the admin portal's identity at Microsoft.
Helm values pointing the admin portal and the API at that registration.
Optionally, app roles in Entra mapped to OSIE admin roles, so admin access follows role assignments in your tenant.

1. Create the app registration

In the Entra admin center → App registrations → New registration:

Name: e.g. OSIE Admin Portal.
Supported account types: Accounts in this organizational directory only (single tenant).
Platform: Single-page application, with the redirect URI:
```
https://osie.mycompany.com/osie_admin/
```
The admin portal completes the login at its base path — keep the trailing slash.

Note the Application (client) ID and the Directory (tenant) ID from the Overview page; the Helm values below use both.

2. Expose an API

The admin portal requests an access token for the app itself, and the OSIE API accepts only tokens issued for this app — a Microsoft Graph token would be rejected. That requires the registration to expose an API:

Expose an API → Set the Application ID URI (the default api://<client-id> is fine).
Add a scope — e.g. access, enabled, admins and users. The scope's name is not referenced by OSIE, but at least one must exist.
API permissions → Add a permission → My APIs → select this same app → check the scope → Grant admin consent.

3. Require version 2 tokens

In App registrations → your app → Manifest, set:

"requestedAccessTokenVersion": 2

OSIE validates tokens against the v2 issuer (https://login.microsoftonline.com/<tenant-id>/v2.0). Without this setting Entra issues v1 access tokens carrying a sts.windows.net issuer, and every API call fails — the visible symptom is a successful Microsoft sign-in followed by 401 responses from OSIE.

4. Configure the Helm values

values.yaml
admin:
  oauth2:
    issuerUri: "https://login.microsoftonline.com/<tenant-id>/v2.0"
    clientId: "<client-id>"
    scope: "openid profile email offline_access <client-id>/.default"

Use the bare client ID in the scope

Entra resolves the token's audience from the scope, and only accepts the GUID-based form when an app requests a token for itself:

Scope form	Result
`api://<client-id>`	`AADSTS500011` — resource principal `api:/` not found
`api://<client-id>/.default`	`AADSTS90009` — application requesting a token for itself
`<client-id>/.default`	works

Apply with the usual upgrade:

helm upgrade osie osie/osie -n osie -f values.yaml

5. Restrict who gets admin access

By default, every user in the tenant who can sign in to the app has full administrator access. Admin accounts are not stored in OSIE, so there is no per-user grant to edit on the OSIE side — control access in Entra, with either or both of:

Require assignment

Enterprise applications → your app → Properties → set Assignment required to Yes, then assign the intended users or groups under Users and groups. Unassigned users can no longer sign in to the admin portal at all.

App roles mapped to OSIE admin roles

App roles let Entra decide not just who signs in, but which OSIE admin role they get.

In App registrations → your app → App roles → Create app role:

Display name: e.g. OSIE administrators
Value: e.g. osie-admins — this string appears in the token's roles claim
Allowed member types: Users/Groups

Assign the role to users or groups under Enterprise applications → your app → Users and groups. Then map the role values to OSIE admin roles (requires chart version 26.4.1 or later):

values.yaml
admin:
  oauth2:
    rolesClaim: roles
    roleMappings:
      osie-admins: SUPER_ADMIN
      osie-support: SUPPORT

With mappings configured, only tokens carrying a mapped role value get admin access — everyone else is denied, even if they can sign in. When several values match, the first mapping in declaration order wins. The role names on the right are OSIE admin roles: the built-in SUPER_ADMIN, ADMIN, SUPPORT, BILLING_ADMIN and VIEWER, or the name of a custom role defined in the admin portal.

Role changes in Entra take effect on the next sign-in or token refresh — no OSIE-side action needed.

Troubleshooting

Symptom	Cause	Fix
`AADSTS500011` — resource principal `api:/` not found	Scope uses `api://<client-id>` without `/.default`	Use `<client-id>/.default` in the scope
`AADSTS90009` — application requesting a token for itself	Scope uses `api://<client-id>/.default`	Use the bare `<client-id>/.default` form
`AADSTS650053` — scope does not exist	The registration doesn't expose an API	Complete step 2
Sign-in succeeds, every API call returns 401	v1 access tokens (`sts.windows.net` issuer)	Set `requestedAccessTokenVersion: 2` (step 3)
"You do not have admin access" after sign-in	Role mappings configured, but the token carries no mapped value	Assign the app role to the user, or fix the `roleMappings` values

1. Create the app registration​

2. Expose an API​

3. Require version 2 tokens​

4. Configure the Helm values​

5. Restrict who gets admin access​

Require assignment​

App roles mapped to OSIE admin roles​

Troubleshooting​