Connect your identity provider
Register AIOE in Microsoft Entra ID, give people roles, and set the values the API reads at start.
People sign in to the console and the mobile app with your organisation's identity provider. AIOE never sees a password: it checks the signature of the access token your identity provider issues, and the token's issuer tells it which organisation the person belongs to. A token from any other issuer is refused.
Microsoft Entra ID is the identity provider the console and the mobile app are built and tested with. Workbenches do not sign in to the identity provider directly: a person approves each workbench in the console while signed in, and the workbench then holds a token AIOE issued (see Enrol workbenches).
Before you start
- The public address of your API (for example
https://aioe.example.com) and of your console (for examplehttps://console.aioe.example.com). - Permission to create app registrations in your Entra tenant, and to grant tenant-wide admin consent.
- Your Entra tenant ID (Entra admin centre, Overview).
Register AIOE in Entra ID
You create two app registrations: one that represents the AIOE API, and one public client that the console and the mobile app sign in with.
Register the API
In the Entra admin centre, open App registrations, New registration, and name it, for example, "AIOE API". Single tenant is enough. Note its Application (client) ID: this is the API's audience.
Ask for version 2 access tokens
Open the registration's Manifest and set requestedAccessTokenVersion to 2. Version 2 tokens carry the issuer https://login.microsoftonline.com/<tenant-id>/v2.0 and the API's client ID as their audience, which is what AIOE checks.
Expose a scope
Under Expose an API, set the Application ID URI (for example api://aioe.example.com) and add a scope named access. The full scope, api://aioe.example.com/access, is the API scope.
Add the app roles
Under App roles, create these roles, allowed for users and groups:
| Value | Who holds it |
|---|---|
admin | Administrators: policy, catalogue, tools, secrets, roles, projects, and every workbench. |
operator | Operators: see and control every workbench and node, read the audit trail. |
portfolio-manager | Optional. People who manage business areas, enterprise projects and enterprise teams. |
A person with no role is a member: they see and control only the workbenches they enrolled. People and roles describes each role in full.
Register the public client
Create a second registration, for example "AIOE Client". Under Authentication, add:
- a Single-page application platform with the redirect URI of your console's root, with the trailing slash:
https://console.aioe.example.com/; - a Mobile and desktop applications platform with the redirect URI
mju-aioe://auth, for the mobile app.
Note its Application (client) ID: this is the client ID.
Pre-authorise the client
Back on the API registration, under Expose an API, Add a client application, enter the client's ID and tick the access scope. People then sign in without a consent prompt.
Give people their roles
Open Enterprise applications, find the API registration, and under Users and groups assign the admin, operator and portfolio-manager roles to people or groups. Roles take effect at a person's next sign-in.
Optional: groups and the people pickers
- Groups. To make Entra groups members of projects, or to grant them memory compartments, add a groups claim under the API registration's Token configuration. AIOE remembers a person's groups at each sign-in, so a group change takes effect at their next sign-in. When a person belongs to more groups than Entra puts in a token, Entra leaves the claim out.
- People pickers. The console's pickers (project members, owners, node assignments, compartments and clearances) search your directory through Microsoft Graph, from the browser, with the person's own sign-in. Give the client registration the delegated Microsoft Graph permissions
User.ReadBasic.AllandGroupMember.Read.All, and grant admin consent for the tenant. Without them, a picker takes an object ID instead of a name.
Set the API's values
Your organisation is created, or updated, from these variables every time the API starts. Set them on the API container (in your .env file for Docker Compose, in bootstrapTenant for Helm, or in the Azure template's parameters).
| Variable | Value | Example |
|---|---|---|
AIOE_BOOTSTRAP_TENANT | A short, lower-case name for your organisation. Setting it makes the other five required. | example |
AIOE_BOOTSTRAP_ORGANISATION | The name people see when they sign in. Defaults to the short name. | Example Pty Ltd |
AIOE_BOOTSTRAP_DOMAINS | Your email domains, and the API's host name if it is not under one of them, separated by commas. A host matches a domain when it is the domain or ends with . and the domain. | example.com,example.com.au |
AIOE_BOOTSTRAP_OIDC_ISSUER | Your Entra issuer. | https://login.microsoftonline.com/<tenant-id>/v2.0 |
AIOE_BOOTSTRAP_OIDC_AUDIENCE | The API registration's Application (client) ID. | a GUID |
AIOE_BOOTSTRAP_OIDC_CLIENT_ID | The client registration's Application (client) ID. | a GUID |
AIOE_BOOTSTRAP_API_SCOPE | The full API scope. | api://aioe.example.com/access |
The domains do two jobs: AIOE answers its discovery document only for a host that matches them, and it is how the API knows that a request arriving at its own host name is for your organisation. If the API's host name is outside your email domains (for example aioe.example-hosting.net), add it to the list.
The full list of settings is in Environment variables.
Check that sign-in works
- Restart the API so it reads the new values. Its log says
bootstrap tenant readywith your domains. - Open
https://<api-host>/.well-known/aioe.json. It names your organisation, your issuer, the client ID and the API scope. - Open the console and sign in. Settings shows your organisation, its tenant name and its identity provider.
- A person with the
adminrole sees Roles under Settings. If they do not, sign out and in again, and check the role assignment in Entra.
Let AIOE act for people in Azure DevOps (optional)
People can link Azure DevOps "through Entra", so the platform reads work items and pull requests, and gives agents git credentials, as that person, without anyone pasting a personal token. This needs the API registration to act on a person's behalf.
Grant the Azure DevOps permission
On the API registration, under API permissions, add the Azure DevOps delegated permission user_impersonation, and grant admin consent for the tenant. Your Azure DevOps organisation must be connected to the same Entra tenant.
Create a client secret
Under Certificates & secrets, create a client secret for the API registration. Put it in your secret store and set it on the API as AIOE_ENTRA_CLIENT_SECRET. Note when it expires: renew it before then (see Platform keys and rotation).
Link
People open Settings, Source control in the console and choose Connect through Entra. Without the secret, the console says the platform cannot act on their behalf, and Azure DevOps links with a personal token only.
Linked accounts are sealed with AIOE_SECRETS_KEY, so that key must be set too. GitHub works differently, through a GitHub App your organisation registers: see Source control.
Other OpenID Connect providers
The API itself is not tied to Entra ID. It accepts an access token from your configured issuer when:
- the token is signed with RS256, and the issuer publishes its keys at
<issuer>/.well-known/jwks.json; - the token's
audis the value ofAIOE_BOOTSTRAP_OIDC_AUDIENCE; - the person is identified by an
oidclaim, or elsesub; - roles arrive as an array in a
rolesclaim, and groups (if you use them) in agroupsclaim.
The console and the mobile app sign in with Microsoft's authentication library, and are built and tested against Entra ID. Before you plan on Okta or another provider, talk to Mojo Up about your provider.