> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/configure/auth/azure-id/configure-usernames/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure usernames in Azure AD

> How to use the usernameKey property in the Azure AD AAA adapter to configure which claim Itential Platform uses as the username.

Administrators who use the Itential Azure AD AAA adapter can use the `usernameKey` property field to configure a specific [claim](https://learn.microsoft.com/en-us/entra/identity-platform/access-token-claims-reference) in the AAA response for Itential Platform to use as the username. If the `usernameKey` field is not specified, the adapter uses the default claim `name` to set new users.

To configure the `usernameKey` field, navigate to **Admin Essentials**. Use the search bar in the left sidebar to locate "Azure" in the **Adapters** menu list. Under the **Configuration** tab on the **Properties** page, enter a specific claim in the `usernameKey` field.

![](/_fern-img/684a6c27737bf8b48d8f4b22146454af90d08b5d9c9d8dfdc00ddd74ed49a342.webp)

## Why this matters

The `usernameKey` provides administrators with a configurable option to specify a custom or optional claim in the AAA response for Itential Platform to authenticate a user. As long as the configured attribute is confirmed to be unique in the Azure/EntityID database, specifying the `usernameKey` as an attribute of a custom or optional claim also prevents multiple users from having the same Azure/EntityID display name in one Itential Platform account.

The custom attribute that is chosen **must contain a value**. It cannot be blank or not found; otherwise, the user is unable to log in to Itential Platform.

## Property schema

```json
"usernameKey": {
  "type": "string",
  "description": "Key of the user token to be utilized as the username",
  "default": "name"
}
```

> How to use the usernameKey property in the Azure AD AAA adapter to configure which claim Itential Platform uses as the username.