Microsoft Entra ID — setup manual

How to register this console in Microsoft Entra ID so your directory accounts can sign in with Microsoft. Everything below is done once, by a directory administrator. This page works offline.

0What must reach what

A frequent objection is “our instance sits in a private network with no inbound access”. That is fine. Entra ID never connects to this application. Sign-in is a browser redirect; the only server-to-server call is outbound from here to Microsoft.

  (1) browser  ---------------->  this console          user opens the sign-in page
  (2) console  --- 302 ------->   browser               "go to login.microsoftonline.com"
  (3) browser  ---------------->  Entra ID              password / MFA / Conditional Access
  (4) Entra    --- 302 -------->  browser  ---------->  this console  /signin-oidc
  (5) console  === HTTPS OUT ==>  Entra token endpoint  redeem the code        [outbound]
  (6) console  === HTTPS OUT ==>  Entra JWKS            validate the signature [outbound]

Egress allow-list: login.microsoftonline.com, login.microsoft.com, aadcdn.msftauth.net. Nothing else. Group provisioning (SCIM) and back-channel logout would need inbound access — this console deliberately uses neither.

1Register the application

Entra admin center → App registrations → New registration.

Afterwards copy the Application (client) ID and Directory (tenant) ID from the Overview page.

2Redirect & logout URLs

Entra matches these character for character — scheme, host, port, path, trailing slash. These are the exact values for this instance:

Under Authentication, set the front-channel logout URL:

• Leave every implicit grant checkbox unticked — this console uses Authorization Code + PKCE.
• https:// is required in production (http://localhost is the only exception Entra allows). The console enforces this itself: a Microsoft sign-in started over plain HTTP is upgraded to HTTPS first.
• The URL only has to resolve for your users’ browsers. An internal-only hostname is fine; Entra never resolves or probes it.

3Create the App Roles

App Roles let Entra gate who may sign in (with step 5’s “assignment required”) and label assignments meaningfully. Their values are plain strings, identical in every tenant.

Create them individually under App roles, or paste this into Manifest (replace the "appRoles": [] line) and save — one action instead of three forms:

"appRoles": [
  {
    "allowedMemberTypes": [ "User" ],
    "description": "Full control of the console.",
    "displayName": "Administrator",
    "id": "1f4d4d3a-2f7a-4a2e-9a5c-1c9a9d4e0001",
    "isEnabled": true,
    "value": "Administrator"
  },
  {
    "allowedMemberTypes": [ "User" ],
    "description": "Standard non-administrator user.",
    "displayName": "User",
    "id": "1f4d4d3a-2f7a-4a2e-9a5c-1c9a9d4e0002",
    "isEnabled": true,
    "value": "User"
  },
  {
    "allowedMemberTypes": [ "User" ],
    "description": "Read-only access.",
    "displayName": "Read only",
    "id": "1f4d4d3a-2f7a-4a2e-9a5c-1c9a9d4e0003",
    "isEnabled": true,
    "value": "ReadOnly"
  }
]

The id values are arbitrary but must be unique GUIDs within the application. Keep the ones above and every deployment stays consistent.

4Create a client secret

Certificates & secrets → Client secrets → New client secret. Choose an expiry your rotation process can meet.

Store it outside source control: an environment variable, a secrets manager, or a file with restricted permissions. Never commit it.

5Require assignment

Enterprise applications → your app → Properties:

6Assign people

Enterprise applications → your app → Users and groups → Add user/group: pick the account, then pick a role.

• Every assigned account also needs an active console user whose username equals the account’s UPN (e.g. sample@email.com) — create it under Users in the console if it does not exist yet.
• Guest (B2B) accounts: the UPN in the token is the guest form, e.g. name_theirdomain.com#EXT#@yourtenant.onmicrosoft.com — the console username must match that string, not the guest’s home address.
• Assignment changes take effect on the account’s next sign-in.

The My Apps tile

With Visible to users = Yes the console appears in each assigned user’s My Apps portal. Selecting the tile opens the console and signs them in silently, because the browser already holds an Entra session.

7Configure this instance

Provide three values in appsettings.json under AzureAd (the section ships empty), or as environment variables:

"AzureAd": {
  "Instance": "https://login.microsoftonline.com",
  "TenantId": "<Directory (tenant) ID>",
  "ClientId": "<Application (client) ID>",
  "ClientSecret": "<the secret Value from step 4>"
}

AzureAd__TenantId=<Directory (tenant) ID>
AzureAd__ClientId=<Application (client) ID>
AzureAd__ClientSecret=<the secret Value from step 4>

Recycle the console’s IIS application pool (or restart the site). The sign-in page’s Sign in with Microsoft button appears once both the tenant and client IDs are present.

Multiple instances or an extra proxy

• This console runs in-process under IIS and reads the request scheme natively — no X-Forwarded-Proto setup is needed unless an additional TLS-terminating proxy is placed in front.
• Running more than one instance behind one address? The Data Protection key ring must be shared (file share or equivalent). The OIDC correlation and nonce cookies are encrypted with it; unshared keys cause intermittent “Correlation failed” errors that look like an Entra fault but are not.

8Verify

1. Open the sign-in page and choose Sign in with Microsoft.
2. Approve the consent prompt on first use. It requests openid profile email only — no mail, files, or directory access.
3. You should land on the console as the console user named after your UPN, with that user’s permissions. Open /console/Account/Whoami to see the mapping: the console user, the sign-in source, and the Microsoft account’s UPN / oid / tid.
4. Sign in with an assigned Microsoft account that has no console user of that username: the console must refuse it and name the exact username an administrator needs to create.
5. Remove an account’s assignment in Entra (step 6): with “assignment required” on, Microsoft must refuse the sign-in before the console is ever reached.
6. Sign out: the console session ends and the browser round-trips Microsoft’s sign-out page.

?Troubleshooting

Username/password access

Local console sign-in remains available alongside Entra — the console stays reachable when Entra is unreachable or before it is configured. Local and Microsoft sign-ins land on the same console user and the same permissions.