SSO with Microsoft Entra ID

Firezone supports authenticating users with Microsoft Entra ID using Firezone's public OAuth client. One Entra provider can accept users from multiple verified tenants, giving users from different organizations the same sign-in option. Each tenant must be verified by an administrator before its users can sign in through that provider.

Enable Entra authentication

To enable Entra authentication:

1. Go to Settings → Authentication in your admin portal.
2. Click Add Provider and select Entra.
3. Optionally name the provider — this is shown to users on the sign-in page.
4. Select the authentication context:
   • Client Applications and Admin Portal: Users can sign in to both the Firezone client applications and admin portal using Entra SSO.
   • Client Applications Only: Users can sign in to the Firezone client applications using Entra SSO but not the admin portal.
   • Admin Portal Only: Users can sign in to the admin portal using Entra SSO but not the Firezone client applications.
5. Portal session lifetime: (optional) Set a custom session lifetime for users signing in to the admin portal with Entra SSO. Leave blank to use the default session lifetime.
6. Client session lifetime: (optional) Set a custom session lifetime for users signing in to the Firezone client applications with Entra SSO. Leave blank to use the default session lifetime.
7. Click Verify Now to complete an authentication flow. This captures your Entra tenant ID in the Verified tenants table. Check that it is the correct tenant before proceeding. At least one verified tenant is required.
8. To allow users from additional tenants, click Verify another tenant and complete verification for each tenant.
9. Click Save.

Users will now see this provider as an option on the Firezone sign-in page.

How it works

Firezone uses a public OAuth client to authenticate users with Microsoft Entra ID. When a user signs in:

1. They're redirected to Microsoft's sign-in page.
2. After authenticating with Microsoft, they're redirected back to Firezone.
3. Firezone verifies that the signed token's tenant ID (tid) matches one of the provider's verified tenants and that its issuer (iss) matches that tenant. Tokens from other tenants are rejected.
4. Firezone matches the user using the iss and sub claims from Entra. For users provisioned via directory sync, this identity already exists. For manually created users, Firezone matches by email on first sign-in and saves the Entra identity for subsequent sign-ins.

No app registration or client secret setup is required on your end.

Data accessed

Firezone requests the following scopes from Microsoft:

• openid — Required for authentication
• email — Used to match users on first sign-in
• profile — Used for the user's display name

Firezone does not read your email, calendar, or files.

Manage verified tenants

To add another tenant to an existing provider:

1. Go to Settings → Authentication and edit the Entra provider.
2. Click Verify another tenant.
3. Complete verification with an administrator account from the additional tenant. Check that the new row in Verified tenants has the intended tenant ID.
4. Repeat for any other tenants, then click Save.

Users from all listed tenants use the same sign-in option, authentication context, and session lifetimes. For example, an MSP can verify customer tenants on one provider without adding a sign-in option for every customer.

To remove an additional tenant, click the delete button next to its row, then click Save. Users whose tokens are issued by that tenant will no longer be able to sign in through this provider. The first verified tenant cannot be removed, so the provider always retains at least one verified tenant.

Each tenant can belong to only one Entra provider within a Firezone account, including disabled providers. The same tenant can be used in other Firezone accounts.

The REST API and MCP return the verified tenants in tenant_ids, an array of tenant UUIDs, instead of a single issuer. Add tenants through the portal's verification flow.

Restricting access to specific users or groups

Entra admins can control which users and groups are allowed to sign into Firezone by configuring user assignment on the Firezone Enterprise Application in your tenant.

To restrict access:

1. Sign in to the Azure portal.
2. Go to Microsoft Entra ID → Enterprise applications.
3. Search for and select the Firezone application.
4. Go to Users and groups.
5. Click Add user/group to assign specific users or groups.
6. Go to Properties and set Assignment required? to Yes.

With assignment required enabled, only users and groups explicitly assigned to the Firezone application will be able to sign in.

Provisioning users

Users must exist in Firezone before they can sign in with Entra. You can:

• Create users manually in the admin portal or via the REST API
• Enable Entra directory sync (Business and Enterprise plans) to automatically provision users and groups from Microsoft Entra ID

Troubleshooting

User not found

If a user sees a "user not found" or similar error when signing in, it means no matching user exists in Firezone. The user must be created manually or provisioned via directory sync before they can sign in.

Access denied by Entra admin

If a user sees "AADSTS50105" or "You cannot access this application", it means the Entra admin has enabled user assignment and the user is not assigned to the Firezone application. See Restricting access above.

Wrong tenant

If a user authenticates with an account whose token is issued by an unlisted tenant, they'll see an error. Check Verified tenants in the provider settings. If the tenant should have access, click Verify another tenant, complete verification for that tenant, and save the provider.

A user may belong to multiple tenants. The tenant that issues the ID token must be in the provider's verified list; an email domain or an existing Firezone user account does not establish that match. Renaming the provider does not change which tenants it accepts.

Revoking access

Users can revoke Firezone's access to their Microsoft account from their Microsoft account security settings. Revoking access does not delete the user from Firezone or end their active sessions, but they will need to re-authorize on their next sign-in.

Need help? See all support options.