Table of Contents

Impersonation

Learn how to manage the service principals that are allowed to impersonate the caller identity when they call FoundationaLLM APIs.

Overview

Some trusted services call FoundationaLLM APIs on behalf of end users. For example, a service can authenticate with its own service principal and pass the end user's identity in the X-USER-IDENTITY HTTP header. FoundationaLLM accepts that substitute identity only from service principals that are on an allowlist.

The Impersonation page manages this allowlist. It is stored in the FoundationaLLM:Instance:IdentitySubstitutionSecurityPrincipalId application configuration setting as a comma-separated list of object IDs.

When an allowlisted service principal sends X-USER-IDENTITY, the API acts as the user in the header only if both of these conditions are met:

  • The UPN in the header matches the regular expression in the FoundationaLLM:Instance:IdentitySubstitutionUserPrincipalNamePattern setting. This page does not edit that setting.
  • The header contains a valid identity with a UPN.

Otherwise, the header is ignored and the request runs as the service principal itself.

Important: The allowlist does not control which principals can call the APIs. It only controls which principals can replace their identity with another user's. Add only services you fully trust, because an allowlisted service can act as any user whose UPN matches the pattern.

Prerequisites

  • Access to the Management Portal
  • The Configuration Contributor role, which is required to save application configuration settings

Open the Impersonation Page

  1. Sign in to the Management Portal.
  2. In the sidebar, select Security > Impersonation.

The API Identity Impersonation section lists the service principals that are currently allowed to impersonate the caller identity.

Column Description
Name The service principal display name. If the name cannot be resolved, the object ID is shown.
ID The service principal object ID.
(Remove) The trash icon that removes the service principal from the list.

When the list is empty, the table shows "No service principals configured."

Add a Service Principal

  1. In Search for service principal, type part of the service principal name.
  2. Pick the service principal from the results. Each result shows the display name and the object ID.
  3. Select Add.

The change is saved immediately, and the portal shows "Impersonation settings saved successfully." If the service principal is already in the list, the portal shows "This service principal is already in the list." and does not add it again.

Remove a Service Principal

  1. Find the service principal in the table.
  2. Select the trash icon (Remove service principal).

The change is saved immediately. There is no confirmation dialog.

Troubleshooting

Issue Resolution
"Failed to save impersonation settings." Confirm you have the Configuration Contributor role. The list reloads with the saved values.
The service principal does not appear in search Search returns service principals only. Confirm the name and that the principal exists in Microsoft Entra ID.
An allowlisted service still runs as itself Confirm that FoundationaLLM:Instance:IdentitySubstitutionUserPrincipalNamePattern is set and that the UPN in X-USER-IDENTITY matches it.