hass-oidc-auth/docs/provider-configurations/microsoft-entra.md

Microsoft Entra ID

Warning

Microsoft Entra ID does not support public clients that are not Single Page Applications (SPA's). Therefore, you will have to use a client secret.

Basic configuration

1. Go to app registrations in Entra ID.
2. Create a new app, use the "Web" type for the redirect URI and fill in your URL: <ha url>/auth/oidc/callback. Note that you either have to use localhost, or HTTPS.
3. Copy the 'Application (client) ID' on the overview page of your app and use it as your client_id.
4. Create the discovery URL:
   • If you selected 'own tenant only' use the 'Directory (tenant) ID' on the overview page of your app and create the discovery URL using: https://login.microsoftonline.com/<tenant id>/v2.0/.well-known/openid-configuration.
   • If you selected any Azure AD account (would not recommend this) or also personal accounts, use https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.
5. Go to Certificates & Secrets and create a client secret. Make sure to copy the 'Value' and not the Secret ID. Use this value for client_secret in the HA config.
   • Make sure to renew this secret in time. It will expire in two years.
6. Go to API Permissions and click 'Add permission'. Add the openid and profile permissions from Microsoft Graph. You can remove User.Read.

Now configure Home Assistant with the following:

auth_oidc:
   client_id: < client id from the 'Application (client) ID field' >
   discovery_url: < discovery URL you made in step 4 >
   client_secret: < client seret from step 5 >
   features:
      include_groups_scope: False

Caution

Be careful! Configuring Entra ID wrong may leave your Home Assistant install open for anyone with a Microsoft account. Please use "Single tenant" account types only. Do not enable "Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant)" or personal account modes without enabling the mode to only allow specific accounts first!

Configuring user roles

If you like to configure the Home Assistant users roles based on your Entra ID settings, you have to create 2 roles within your Entra ID app registration. Go to "App registrations" and select app roles. Create two new roles for admins and users, giving them sensible names and values (the example uses users and admins), that you will need later in your HA configuration.

Then you need to create the users and assign them a role of your choice. Go to "Enterprise apps" chose your app registration again and select "Users and groups" within the manage section. Add users, or groups from your tenant or AD-sync and assign them a role, from the ones you created before.

Last thing to do is to include

  claims:
    groups: "roles"
  roles:
    admin: "admins"
    user: "users"

in your auth_oidc config, where the roles values correspond to the ones you chose in your Entra ID roles. Make sure, you keep the "include_groups_scope: False" from the basic configuration, as the claim needed for Entra ID is "roles".

Newly created users will get the role assigned in Entra ID, but there is no update to user roles. A user created with user role in HA will not get the admin role, if you change the assignment later on in Entra ID.