Documentation

Permission to create an application registration in the corporate directory.
Platform administrator access, and the external FQDN finalised.
The group-to-role mapping decided in advance.
A place to store the client secret. It is shown once at creation, and it expires.

Create a new application registration in the directory.
Name it identifiably: the name appears on the consent screen users will see.
Set the supported account types to single tenant unless there is a specific reason otherwise.
Record the application (client) identifier and the directory (tenant) identifier.

Add a web platform redirect URI pointing at the platform broker endpoint on the external FQDN.
The URI must match exactly, including scheme and any trailing path. A mismatch produces an explicit redirect URI error, which is at least a clear failure.
Enable the ID token issuance required by the flow in use.
Add a front-channel logout URL if single logout is wanted.

Create a new client secret and record its value immediately — it is not retrievable afterwards.
Set an expiry consistent with the customer credential rotation policy, and record the expiry date somewhere that will be reviewed. An expired client secret breaks login for everyone with no other symptom, and it will happen on a date nobody has in a calendar unless this step is taken.

Grant the directory read permissions the sign-in flow requires, and grant administrator consent so users are not individually prompted.
Configure a groups claim so that group membership is present in the token. Without it there is nothing to map roles from.
Configure optional claims for email, given name and surname so user records populate.
Note whether groups are emitted as identifiers or as names, and configure the platform mapping to match. This detail is the most common cause of a working login with the wrong role.

In the platform authentication settings, add the OIDC provider.
Supply the discovery document URL for the tenant, the client identifier and the client secret.
Configure scopes to include those needed for the identity and group claims.
Configure the group-claim-to-role mapping.
Save, then test in a private browser session.

Client secret expiry: track it and rotate before expiry. Create the new secret, update the platform configuration, verify login, then remove the old secret. In that order, so there is no window without a valid secret.
Redirect URIs: update these whenever the external FQDN changes, at the same time as the certificate and platform configuration.
Group changes: a group renamed or re-identified at the directory breaks role mapping while login continues to work, so the symptom is wrong permissions rather than failed access.

Redirect URI mismatch: the registered URI does not match what the platform sent. Compare them character by character.
User not found: the user authenticated at the directory but has no platform user record and automatic provisioning is not configured, or the email claim is absent.
Unauthorized or permission denied: the group claim is absent or maps to no role.
Invalid client secret: the secret is wrong or has expired.
No sign-in button on the login page: the provider is configured but not enabled, or the frontend has not picked up the configuration change. Reload after a configuration change.