How to configure authentication with Entra ID¶

Entra ID is an Identity and Access Management offering from Microsoft. It is commonly used as a central location for managing users, groups, roles, and their privileges across many applications and deployments.

LXD supports authentication via OpenID Connect (OIDC) (see OpenID Connect authentication). Entra ID is an OIDC provider; however, some aspects of the Entra ID OIDC service are non-standard. In particular, the access_token that is returned when a user successfully authenticates using the device authorization grant flow is an opaque string, and not a JSON Web Token (JWT).

The LXD CLI uses the device authorization grant flow to obtain an access token. When a command is issued, the CLI adds this token to all requests to the LXD API. For Entra ID, since the token is opaque, LXD is unable to verify it and the command will fail. Therefore, authentication with Entra ID is only directly supported for the user interface (LXD UI) and not the CLI.

We are working toward full Entra ID support for LXD. In the meantime, it is possible to use Entra ID if OIDC is only required for the LXD UI. Alternatively, it is possible to use Entra ID for both the CLI and the user interface by deploying an identity broker such as Keycloak.

This how-to guide covers configuring Entra ID for authentication in the LXD UI only, and cover configuring Keycloak to act as a broker for Entra ID. In both cases, it is assumed that LXD has been initialized and is available remotely via the HTTPS API on port 8443 (see How to expose LXD to the network for instructions). It is also assumed that you have access to an Entra ID tenant.

Using Entra ID directly (LXD UI only)¶

In your Entra ID tenant, go to Identity > Applications > App registrations in the left panel.

Entra ID App registrations¶
Click + New registration. Then choose a name for the application (for example LXD).

Entra ID set application name¶
Under Redirect URI (optional), select Public client/native (mobile & desktop) and type:
```
https://<your-LXD-hostname>/oidc/callback
```
Entra ID set redirection URI¶
Click Register.
In the configuration page for your new application, go to Authentication in the Manage menu.

Entra ID authentication¶
Scroll down to Advanced settings. Under Allow public client flows, toggle Yes and click Save.

Entra ID enable public client flows¶
In the configuration page for your new application, go to API permissions in the Manage menu.

Entra ID API permissions¶
Go to Configured permissions and click + Add a permission.

Entra ID add a permission¶
Click Microsoft Graph in the right panel.

Entra ID Graph API permissions¶
Click Delegated permissions.

Entra ID Graph API delegated permissions¶
Select all OpenId permissions, then click Add permissions.

Entra ID OpenID permissions¶
Above the Manage menu, go to Overview and copy the Application (client) ID.

Entra ID copy client ID¶

Set this as the client ID in LXD:

lxc config set oidc.client.id <your-client-id>

While still in Overview, click Endpoints and copy the URL under OpenID Connect metadata document.

Entra ID tenant discovery URL¶
Navigate to the URL that you copied. This URL will display some output in JSON format.

Copy the URL from the issuer field. Then set this as the oidc.issuer in LXD:

lxc config set oidc.issuer <your-issuer>

Alternatively, execute this command:

lxc config set oidc.issuer "$(curl <URL that you copied> | jq -r .issuer)"

You can now navigate to the LXD UI in your browser. When you click Login with SSO, you will be redirected to Entra ID to authenticate.

Using Keycloak as an Identity Broker for Entra ID¶

If you plan to use Keycloak as an identity provider for your production systems, you should follow their guide on configuring Keycloak for production. For this guide, it is assumed that Keycloak is available over HTTPS and that you have created a Keycloak realm with default settings.

In your Keycloak realm, go to Identity providers.

Keycloak realm Identity providers¶
Click Microsoft.

Keycloak Microsoft provider¶
On this page, copy the Redirect URI. Keep the tab open so that you can return to this page to continue setting up Keycloak.

Keycloak broker redirect URI¶
In your Entra ID tenant, go to Identity > Applications > App registrations in the left panel.

Entra ID App registrations¶
Click + New registration. Then choose a name for the application (for example Keycloak).

Entra ID App name¶
Under Redirect URI (optional), select Web and paste the URL that you copied from Keycloak. Then click Register.

Entra ID set redirection URI¶
Go to Certificates & secrets under Manage in your Entra ID tenant.

Entra ID certificates and secrets¶
Click + New client secret.

Entra ID client secret¶
In the right panel, click Add. A new client secret will be displayed. Copy the value.

Entra ID copy client secret¶

Note

After navigating away from this page, you will no longer be able to view or copy the secret. If you forget to copy it, you can delete it and create another one.
In the Keycloak identity provider configuration tab, paste the secret into the Client secret field.

Keycloak paste client secret¶
In Entra ID, go to the app Overview and copy the Application (client) ID.

Entra ID copy client ID¶
Paste the value into the Client ID field in the Keycloak tab.

Keycloak paste client ID¶
In Entra ID, go to the app Overview and copy the Directory (tenant) ID.

Entra ID copy tenant ID¶
Paste the value into the Tenant ID field in the Keycloak tab.

Keycloak paste tenant ID¶
Click Add.
Follow steps 7 to 11 in the above guide. This allows Keycloak to request the required OpenID scopes.

We have now configured Keycloak to act as a broker for Entra ID. The remaining steps configure Keycloak as the OIDC provider for LXD.
In your Keycloak realm, go to Clients.

Keycloak clients¶
Click Create client.

Keycloak create client¶
Set a Client ID and a name for the client, then click Next. The client ID in this example is a random value. You can type any value, but it must be unique within the Keycloak realm.

Keycloak client name and ID¶
In Authentication flow, check the OAuth 2.0 Device Authorization Grant setting, then click Next.

Keycloak device flow¶
In Valid redirect URIs, type https://<your-LXD-hostname>/oidc/callback, then click Save.

Keycloak redirect URI¶
Go to Realm settings under Configure in the left panel.

Keycloak realm settings¶
Next to Endpoints, click OpenID Endpoint Configuration. This will display some output in JSON format. Copy the URL from the issuer field, and set this in LXD:
```
lxc config set oidc.issuer <your-issuer>
```
Alternatively, execute this command:
```
lxc config set oidc.issuer "$(curl <configuration-url> | jq -r .issuer)"
```
Configure LXD with the client ID that you configured in Keycloak in step 19.
```
lxc config set oidc.client.id <client-id>
```

You can now log in to LXD via the user interface or via the CLI. LXD will redirect you to Keycloak to authenticate. A Microsoft logo will be displayed that will, when clicked, allow you to log in to Keycloak (and therefore LXD) with Entra ID.

Additional Keycloak settings¶

It is important to remember that Keycloak is an identity provider in its own right. Once a user has signed in to Keycloak, information about that user is stored and a session is created. By default, even with a brokered identity provider, a user may edit their profile details on first log in. This includes editing their email address.

The information that Keycloak stores about the user is configurable in realm settings. When using Keycloak as a broker, you should consider preventing users from editing their information in Keycloak. It might be necessary to configure mappers for the identity provider. Identity provider mappers configure Keycloak to automatically populate user profile information with fields from the brokered provider.

For more information on identity brokering with Keycloak, please see their documentation.