Skip to content

Configure single sign-on

OIDC configuration is available only when the deployed managed application exposes an approved single-sign-on action. If the action is absent, do not change managed resources or Elasticsearch configuration directly; request an availability review.

Before you begin

Coordinate with a Microsoft Entra application administrator and an Elasticsearch security administrator. Record:

  • tenant identity;
  • application client ID;
  • approved redirect URI shown by the deployment;
  • OpenID Connect metadata or issuer value required by the action;
  • claims used for user identity and group or role mapping;
  • groups and Elastic roles approved for the first test;
  • break-glass access and rollback owner.

Store the client secret in the secret mechanism required by the managed action. Do not put it in a deployment tag, wiki, screenshot, or ticket.

OpenID Connect supports interactive Kibana sign-in. It is not the authentication method for normal Elasticsearch REST clients. Keep a separate approved authentication method for API access and break-glass administration.

Microsoft Entra OIDC flow showing a Kibana user, Entra application registration, authentication and group claims, Kibana callback, Elasticsearch OIDC realm, role mapping, and authorized data access.

Microsoft Entra authenticates the user. Elasticsearch role mappings determine what the authenticated user can access.

Register the application in Microsoft Entra

  1. In the Microsoft Entra admin center, open App registrations.
  2. Create a single-tenant registration unless the approved service design explicitly requires another account type.
  3. Under Authentication, add a Web redirect URI.
  4. Copy the exact redirect URI from the managed application. Do not derive it from a hostname or example.
  5. Create the credential type required by the managed action and record its owner and expiration.
  6. Under Token configuration, configure only the approved claims.

The current managed-action source uses these defaults:

Managed field Default claim Purpose
Claims Principal upn User identity supplied to the Elastic realm
Claims Groups groups Group values available for role mapping
Claims Name name Display name
Claims Mail email Email attribute

Confirm the live action uses the same defaults. Microsoft Entra can omit the complete group list when a user belongs to many groups. Test a representative high-membership account and use an approved alternative mapping design when group overage occurs.

Recognize the expected URI formats

Use the values exposed by the managed application. The following patterns help an Entra administrator recognize them; they are not substitutes for deployment-provided values.

Value Expected pattern
Kibana callback ${KIBANA_URL}/api/security/oidc/callback for the authorization-code flow
Entra issuer https://login.microsoftonline.com/${TENANT_ID}/v2.0 for a tenant-specific v2 endpoint
Discovery document ${ENTRA_ISSUER}/.well-known/openid-configuration

The callback must use the externally visible Kibana URL and must match the Web redirect URI in Entra exactly, including scheme, host, path, port when present, and trailing-slash behavior. Do not reconstruct it when the managed application supplies a different value.

Apply the managed OIDC configuration

  1. Open the deployed managed application.
  2. Open Resources > My Deployment > Configure Deployment.
  3. Enable Change SSO OIDC Settings.
  4. Enter the verified client ID and credential through the protected password control.
  5. Confirm the principal, groups, name, email, and optional principal-pattern fields.
  6. Submit the change and wait for the managed action and synchronization to complete.

Map users to Elastic roles

Authentication does not grant Elasticsearch privileges. Create least-privilege Elastic roles first, then map an approved Entra group or other stable claim to those roles through Kibana or the role-mapping API.

For example, a mapping rule can match one approved group identifier:

{
  "roles": ["kibana_reader"],
  "enabled": true,
  "rules": {
    "field": {
      "groups": "<approved-entra-group-object-id>"
    }
  },
  "metadata": {
    "owner": "identity-team"
  }
}

Replace the role and group with approved values. Do not map all authenticated users to a broad administrator role.

Validate and recover

  1. Test with a non-administrator account in a private browser session.
  2. Confirm the user receives only the intended Elasticsearch and Kibana privileges.
  3. Test a user with no mapped group and confirm access is denied or limited as designed.
  4. Test logout and a new session.
  5. Test the documented break-glass path before closing the change.
  6. Record the client credential's expiration and rotation owner.

Do not disable the last working administrative authentication method until OIDC sign-in and role mapping have been validated.

Rotate the client credential

  1. Confirm break-glass access works and schedule a supported configuration window.
  2. Create a second Entra credential before the current credential expires.
  3. Submit the new credential through Configure Deployment without deleting the working credential.
  4. Wait for managed synchronization to complete.
  5. Test sign-in and least-privilege role mapping in a private browser session.
  6. Remove the old Entra credential only after the new credential works.
  7. Record the new expiration, owner, and validation evidence.

Do not paste either credential into screenshots, browser developer tools, tickets, or documentation.

Diagnose common sign-in failures

Symptom Check
AADSTS50011 The callback sent by Kibana must exactly match a registered Entra Web redirect URI
Invalid or expired client credential Confirm the managed action received the secret value, the credential is current, and synchronization completed
Entra sign-in succeeds but Kibana denies access Confirm the principal or groups claim and the Elastic role mapping
A high-membership user has no groups claim Check for Entra group-overage behavior and use an approved mapping alternative
Redirect loop or immediate return to sign-in Check the issuer, callback, browser cookies, time synchronization, and managed realm status

Successful validation ends with Kibana loading for the test user and exposing only the spaces, indices, and actions assigned by the approved Elastic roles.

For a redirect mismatch, compare the value sent by Kibana with the Web redirect URI in Entra. For missing roles, inspect the identity and groups received by the Elastic realm without copying tokens into a ticket. Use Microsoft Entra OIDC guidance and Elastic OpenID Connect authentication for protocol and role-mapping behavior.