Overview

The Linux Azure Login Policy allows users to sign in to a managed Linux device with their Microsoft Entra ID identity. Microsoft Entra ID was previously called Azure Active Directory or Azure AD.

The policy provides two configuration types:

Domain: Configures Entra ID domain authentication with optional Hello enrollment and local group assignment.
OAuth: Configures OAuth-based Entra ID authentication on Ubuntu using a Microsoft Entra app registration.

This policy can be used on company-owned and BYOD devices. Because it modifies the Linux authentication system, test it on a small device group before deploying it broadly.

Important: An incorrect domain, tenant ID, client ID, or user allowlist may prevent users from signing in. Maintain a tested local administrator account that does not depend on Entra ID before applying this policy.

Supported Platforms

Requirement	Support
Operating system	Linux
Architecture	x86_64
Ownership	Company-owned and BYOD
Domain configuration	Compatible x86_64 Linux distributions
OAuth configuration	Ubuntu 22.04 or later

OAuth also requires compatible authentication packages for the device’s exact Ubuntu release. A newly released Ubuntu version may not be supported immediately if the required repository or packages are not yet available.

Not supported

Architecture: arm64
Universal Blue (only supported Aurora Universal Blue)
KDE Plasma (SDDM) is not supported due to an issue in himmelblau. Please use the default GDM login manager for Azure SSO to work properly.

Before You Begin

Before configuring the policy:

Enroll the Linux device in Swif and confirm that the Swif agent is online.
Confirm that the device uses the x86_64 architecture:

uname -m

The expected output is:

x86_64

Retain a working local administrator account for recovery.
Confirm that the device has reliable internet access, working DNS, and accurate system time.
Identify the Entra ID domains and users that should be allowed to sign in.
Review the Microsoft Entra MFA and Conditional Access policies that apply to Linux users.
For OAuth, use an Entra administrator account that can create app registrations, configure API permissions, and grant admin consent.

Choose a Configuration Type

Configure Type	When to use it	Settings displayed
`domain`	Use domain-based Entra authentication and optional Hello enrollment. This is the default.	Domains, Enable Hello, Local Groups
`OAuth`	Use an Entra app registration with Ubuntu’s OAuth authentication service.	Issuer ID, Client ID, Force Provider Authentication, Allowed Users, Owner, Home Base Directory

Changing the configuration type changes the authentication components and settings applied to the device. Test the change before switching an existing production deployment.

Set Up Microsoft Entra ID for OAuth Login

Complete the following Microsoft Entra configuration before creating the OAuth policy in Swif.

Step 1: Create an App Registration

Sign in to the Microsoft Entra admin center.
Go to Identity > Applications > App registrations.
Select New registration.
Enter a recognizable application name, such as:
```
Linux Azure Login
```
Complete the registration.

After registration, open the application’s Overview page and record the following values:

Microsoft Entra value	Swif policy field
Application (client) ID	Client ID
Directory (tenant) ID	Issuer ID

Both values normally use a UUID format:

11111111-2222-3333-4444-555555555555

Do not use the Object ID or application display name in place of these values.

Step 2: Add the Required API Permissions

In the app registration, go to API permissions.
Select Add a permission.
Select Microsoft Graph.
Select Delegated permissions.
Add the following permissions:

Permission	Type	Purpose
`GroupMember.Read.All`	Delegated	Reads the signed-in user’s group memberships
`openid`	Delegated	Signs the user in with OpenID Connect
`User.Read`	Delegated	Signs the user in and reads the user’s basic profile

Select Grant admin consent for your organization.
Confirm that each permission shows a granted status.

Important: GroupMember.Read.All requires administrator consent. OAuth login or group retrieval may fail if the permission is configured but consent has not been granted.

Use delegated permissions, not application permissions, for the permissions listed above.

Step 3: Enable Public Client Flows

OAuth login uses a public-client device authentication flow. Enable this flow for the app registration:

In the app registration, go to Authentication. Depending on the Microsoft Entra interface, this page may appear as Authentication (Preview).
Open Settings if the page contains multiple tabs.
Find Allow public client flows.
Set it to Enabled.
Save the change if prompted.

If public client flows are disabled, the device authentication flow cannot complete.

Create the Policy in Swif

In the Swif dashboard, create a policy and select Linux Azure Login Policy.
Enter a descriptive policy name.
Select Domain or OAuth under Configure Type.
Complete the settings for the selected type.
Assign the policy to one test device or a small test device group.
Wait for the device to receive and install the policy.
Confirm that the retained local administrator account can still sign in.
Test sign-in with an allowed Entra ID user.
Verify that a user who is not allowed by the policy cannot sign in.
Expand the deployment only after the authentication and recovery tests succeed.

Recommended Configuration

Domain Configuration

Setting	Recommended value
Configure Type	`domain`
Domains	Explicitly list only trusted Entra ID domains
Enable Hello	Enabled after testing the enrollment flow
Local Groups	Only the minimum groups required

OAuth Configuration

Setting	Recommended value
Configure Type	`OAuth`
Issuer ID	Directory (tenant) ID from the Entra app registration
Client ID	Application (client) ID from the Entra app registration
Force Provider Authentication	Disabled unless an online provider check is required at every login
Allowed Users	`OWNER` with an explicit owner, or specific user principal names
Owner	Explicitly specify the assigned Entra user
Home Base Directory	`/home`

Avoid ALL on shared or high-risk devices unless every user who successfully authenticates in the tenant should be able to access the device.

Domain Setting Explanations

Domains

Specifies the Entra ID domains whose users may authenticate. This setting is required in Domain mode. If it is blank, Entra users cannot sign in.

Example:

example.com

Enter only verified domains owned and controlled by your organization.

Enable Hello

Controls whether users are enrolled in Hello authentication.

Enabled: Users complete the supported Hello enrollment flow and can use the resulting authentication method for later sign-ins.
Disabled: Users may be required to complete MFA more frequently, depending on the identity configuration.

Test initial enrollment, routine login, and account recovery before enabling this option across the organization.

Local Groups

A comma-separated list of existing local Linux groups to which Entra users should be added.

Example:

developers,docker

Groups such as sudo, wheel, and docker may provide administrative or equivalent high-impact access. Assign only the groups required for the user’s role.

First-Time Login with Domain configuration

After the Azure Login Policy is pushed to a device, the user's Azure AD account does not yet exist as a local user on the Linux device. On the first login:

On the login screen, click "Not listed?"
Enter log in email
Enter password
If Windows Hello is enabled, the Hello PIN should be configured after the initial password authentication. Once set up, the PIN will be used for subsequent logins and a password will no longer be required.

Note, for domain setting approach, there is no need to select broker during the sign in flow.

OAuth Setting Explanations

Issuer ID

Enter the Directory (tenant) ID recorded from the Entra app registration.

Example:

11111111-2222-3333-4444-555555555555

Do not enter the application’s Object ID, display name, or Client ID in this field.

Client ID

Enter the Application (client) ID recorded from the Entra app registration.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Confirm that the Client ID belongs to the intended application and the same tenant identified by the Issuer ID.

Force Provider Authentication

Controls whether the device must complete an access check with the identity provider during login.

Disabled: The authentication service checks with the provider when a working connection is available and may permit an eligible cached login when the provider cannot be reached.
Enabled: The provider access check is required. Login may fail when Entra ID or the network is unavailable.

For most deployments, leave this setting disabled. Enable it only when immediate enforcement of an account suspension or removal is more important than offline-login availability.

Test network-outage scenarios before enabling it broadly.

Allowed Users

Specifies which users may access the device after successfully authenticating with Entra ID. Separate multiple values with commas.

Value	Behavior
`OWNER`	Allows the user specified under Owner. This is the default behavior.
`ALL`	Allows every user who successfully authenticates with the configured provider.
User principal name	Allows a specific user, such as `user1@example.com`.

Example allowing an owner and one additional user:

OWNER,user1@example.com

Example allowing only named users:

user1@example.com,user2@example.com

Use explicit users wherever practical. ALL grants access much more broadly.

Owner

Specifies the Entra user assigned the owner role. The owner may sign in when OWNER is included in Allowed Users.

Example:

device.owner@example.com

If OWNER is allowed but no owner is configured, the first user who successfully signs in may be assigned as the owner. Set the owner explicitly to prevent an unintended user from claiming access.

Home Base Directory

Specifies the parent directory under which a new user’s home directory is created.

Recommended value:

/home

New directories use the following pattern:

<home-base-directory>/<username>

Changing this value affects new users at their first login. It does not automatically move an existing user’s home directory or files.

Example OAuth Configuration

The following configuration restricts the device to a designated owner:

Setting	Example value
Configure Type	`OAuth`
Issuer ID	`11111111-2222-3333-4444-555555555555`
Client ID	`aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`
Force Provider Authentication	Disabled
Allowed Users	`OWNER`
Owner	`device.owner@example.com`
Home Base Directory	`/home`

Use the actual Directory (tenant) ID and Application (client) ID from your Entra app registration.

First-Time Login with OAuth configuration

After the Azure Login Policy is pushed to a device, the user's Azure AD account does not yet exist as a local user on the Linux device. On the first login:

On the login screen, click "Not listed?"
Enter log in email
When the Azure Broker authentication workflow shows up, select Microsoft Entra ID broker.
If Enable Hello is configured, the user will be enrolled in Hello authentication during this step.
The broker authenticates the user and automatically creates the local user account on the device.

After the first successful login, the Azure AD account will appear as a listed user on the login screen for future sign-ins. The "Not listed?" step is only required once.

Mixed Identity Login Scenario on Linux

If you first login as a Google account (e.g., yoge@qasso.swifteam.co), then restart the device and login as an Azure account (e.g., yoge@swif.ai), you may be asked to provide the admin password. In Linux, both accounts will be seen as the same username (e.g., 'yoge'), but they have different IDs and groups. This can trigger a prompt: "Authentication required to change user data." This is a system behavior and cannot be changed. Please be aware of this scenario when using mixed identity providers on the same device.

Troubleshooting

Collect Swif Agent and authd Logs

Ask the device user or administrator to collect the following logs:

/var/log/swif-agent.log sudo journalctl -u authd.service

Share the output with Swif support. These logs help identify whether the issue is coming from the Swif agent, the Linux authentication service, or the Azure login broker.

Share Linux Distribution Information

Run the following command:

cat /etc/os-release

Share the output with Swif support to confirm OS-specific behavior and compatibility.

Allow Swif Support to Debug with Remote Terminal

If the issue continues, allow Swif support to access the device using Remote Terminal. This allows support to inspect the authentication configuration, review service status, and confirm whether the Azure login broker is installed and running correctly.

Azure account not appearing on the login screen after policy is applied

This is expected on the first login. The Azure Login Policy configures the authentication broker, but the user account is not created on the device until the first sign-in. Click "Not listed?" on the login screen to trigger the Azure Broker workflow, which will authenticate the user and create the account. On subsequent logins, the account will appear in the user list automatically.

Troubleshooting Aurora (Universal Blue)

For uBlue, the policy needs to be assigned to a Device Group and included in the image building phase. Could you help verify this first?

Is install_swifteam.sh running when building image?
- If it's already running but failed, can you try this install_himmelblaud.sh instead?
If the image is built successfully, please check if the package exists in device

$ sudo dnf list | grep himmelblaud

If the package exists in device, please check if himmelblaud service running

$ sudo systemctl status himmelblaud 
$ sudo systemctl status himmelblaud-tasks

If himmelblau service is running, please try this script to check if user exists?

$ id <AzureUser> 
$ getent passwd <AzureUser> 

// For example 
$ id xxx@xxx.onmicrosoft.com 
$ getent passwd xxx@xxx.ai.onmicrosoft.com 

// Or 
$ id xxx 
$ getent passwd yoge

OAuth Policy Remains Pending or Not Installed

Confirm that the device is online in Swif.
Verify that the policy is assigned to the correct device or device group.
Review the device’s policy command history.
Confirm the architecture and Ubuntu release:

uname -m 
cat /etc/os-release

Confirm that the required authentication packages support the installed Ubuntu release.
Check whether another PAM, NSS, domain-login, or identity policy is already managing the authentication system.

Repository Signature or GPG Key Error

Errors such as the following mean the package manager cannot verify a required authentication repository:

NO_PUBKEY 0CC0D4002C425E03

keyring filetype is unsupported

To troubleshoot:

Confirm the Ubuntu release:
```
cat /etc/os-release
```
Refresh the package repositories and capture the complete error:
```
sudo apt update
```
Confirm that the authentication repository supports the installed Ubuntu release.
Do not bypass signature verification or mark the repository as trusted.
Send Swif Support the OS release, architecture, policy command result, and complete repository error.

If the device uses a newly released Ubuntu version, the required package repository may not yet provide packages or signing metadata for it.

OAuth Authentication Fails

Verify the Microsoft Entra configuration:

Issuer ID matches the Directory (tenant) ID.
Client ID matches the Application (client) ID.
GroupMember.Read.All, openid, and User.Read are configured as delegated permissions.
Administrator consent has been granted.
Allow public client flows is enabled.
The application and user belong to the expected tenant.

Also review the Microsoft Entra sign-in logs for the user and app registration. Conditional Access may block the login because of the Linux platform, device state, location, authentication strength, or another tenant rule.

Public-Client or Device-Flow Authentication Error

Open the Entra app registration and confirm:

Authentication > Settings > Allow public client flows is enabled.
The change was saved.
The Client ID in Swif belongs to that same app registration.

Permission or Consent Error

Open App registration > API permissions and confirm:

All three required Microsoft Graph permissions are present.
Their type is Delegated.
The status shows that consent has been granted for the organization.

If GroupMember.Read.All is present but not granted, ask an authorized Entra administrator to grant tenant-wide admin consent.

Only the First User Can Sign In

The OAuth configuration may be using the default OWNER behavior.

Set Owner to the intended user.
Add more user principal names to Allowed Users.
Use ALL only if every successfully authenticated tenant user should be allowed.

Login Fails While the Device Is Offline

If Force Provider Authentication is enabled, the device may require Entra ID to be reachable.

Restore network access and test again.
Confirm that Entra ID is reachable.
If offline access is required, disable Force Provider Authentication after evaluating the security impact.

No Users Can Authenticate in Domain Mode

Confirm that Domains is not blank.
Verify that each domain is spelled correctly and belongs to the correct Entra tenant.
Confirm DNS, internet connectivity, and system time.
Test with the full user principal name, such as user@example.com.
Confirm that the user can satisfy the tenant’s MFA and Conditional Access requirements.

User Is Not Added to a Local Group

Confirm that the group exists:

getent group <group-name>

Confirm the user’s group membership after signing out and back in:

id '<user@example.com>'

Check the group spelling and comma-separated format. Do not add a user to a privileged group merely to work around a failed policy installation.

Login Is Unavailable After Applying the Policy

Try the retained local administrator account.
Restore network access and verify DNS and system time.
Use a local console or an approved recovery method when possible.
Review the Swif policy command result and authentication service logs.
Contact Swif Support before manually editing PAM or NSS files unless your Linux administrator has a tested recovery plan.

Security and Compliance Impact

The Linux Azure Login Policy can centralize identity-based access and reduce unmanaged local account creation. Its effectiveness depends on secure Entra tenant configuration, properly scoped delegated permissions, MFA and Conditional Access, and a restrictive user allowlist.

For a secure deployment:

Restrict the app registration to the intended organization.
Grant only the required Microsoft Graph permissions.
Review the app registration and granted consent periodically.
Use explicit users instead of ALL wherever practical.
Define the owner before deployment.
Avoid unnecessary privileged local groups.
Protect the local recovery administrator.
Test account suspension, network outage, policy removal, and recovery.

This policy supports identity and access-control objectives, but enabling it does not by itself establish compliance with a specific framework.

Summary

The Linux Azure Login Policy enables Microsoft Entra ID authentication on supported x86_64 Linux devices.

Domain mode uses approved Entra domains with optional Hello enrollment and local group assignment. OAuth mode uses a Microsoft Entra app registration and requires:

An Application (client) ID and Directory (tenant) ID.
The delegated Microsoft Graph permissions GroupMember.Read.All, openid, and User.Read, with the required administrator consent.
Allow public client flows enabled for the app registration.

For most deployments, retain a local recovery administrator, explicitly configure the owner or allowed users, keep Force Provider Authentication disabled unless continuous online verification is required, and validate the complete login and recovery flow on a test device before broader deployment.