Using authentik as the identity provider for Microsoft 365 sign-in
authentik publishes two separate Microsoft 365 guides, one for SAML and one for WS-Federation, so the first decision is which protocol path your tenant will use. Either way, federation moves the password check for Microsoft 365 sign-in from Entra ID to authentik, while the Microsoft 365 licenses, mailboxes and admin roles stay where they are. Users sign in through authentik's login page, admins manage the federated domain from the Microsoft side, and the domain itself must be prepared so that Microsoft recognizes authentik as the authority for it. Plan for that change in your own environment before any user is moved.
The SAML guide relies on two property mappings that must be correct before testing: one that supplies the user's immutable identifier and one that supplies the IDPEmail claim. Errors in either tend to surface as sign-in failures or mismatched accounts, so confirm the attribute source for each user in authentik and test with a small pilot group first. The WS-Federation guide is different. It requires authentik 2026.8 and an Enterprise license, and it is limited to browser-based passive sign-in because the WS-Trust and MEX endpoints are not part of the flow. Confirm both requirements against the current guide and your authentik version before you choose a path.
Ask your DeployOpen or internal team to confirm the license tier you need before scoping the work, because the WS-Federation path depends on it. Also confirm which Microsoft 365 plan and Entra ID tier your tenant holds, since that determines which sign-in and MFA features are available on the Microsoft side. Record these decisions in writing so the pilot, cutover and rollback steps can be checked against them.
What you need before federating a Microsoft 365 domain
Federating a Microsoft 365 domain to authentik touches four things at once: the authentik release and license, the Microsoft 365 plan and user count, the Entra ID tenant that holds the domain, and the DNS and admin accounts that make the change. Confirm each one before the build starts, because several of them decide which federation method is possible at all.
authentik version and Enterprise license
The WS-Federation guide requires authentik 2026.8 and an Enterprise license. The SAML guide does not carry the same requirement, so the choice of protocol decides whether a license is needed. Confirm the exact version against the supported release list before you plan the upgrade window, and confirm with authentik which license tier covers your user count. Enterprise features sit in the enterprise directory under a separate license.
Microsoft 365 plan and user count
Business plans, including Business Basic, Business Standard, Business Premium and Apps for business, are capped at 300 users per tenant across the family. Enterprise plans such as E3 and E5 have no user limit. Confirm the plan in the Microsoft 365 admin center before you pick a design, because a tenant that outgrows the cap will need a plan change, and the desktop Office apps only start with Business Standard.
Entra ID tenant and data location
Every Microsoft 365 tenant sits on an Entra ID tenant, and its data location comes from the country or region chosen when the tenant was created. That setting cannot be changed later. Check the tenant's region, and confirm whether the organization bought Multi-Geo Capabilities, because that changes which EU Data Boundary commitments apply. Confirm these with your Microsoft account team and your data protection owner before you send any sign-in traffic through a new identity path.
Domain ownership and DNS records
Federating a domain requires the domain to be verified in the tenant and the federation settings to point at the authentik endpoints. Someone with DNS control must add or confirm the TXT verification record and must be ready to change the domain's authentication type. Confirm who owns the registrar and DNS zone, how long changes take to propagate in your DNS provider, and whether any other service, such as email routing, depends on the same domain.
Global and hybrid admin accounts
Domain federation changes need a Global Administrator in the tenant, and the sign-in path must be tested with a break-glass account that does not depend on authentik. If Entra Connect or Entra Cloud Sync already synchronizes Active Directory, check which tool owns the immutable identifier before you set the mapping. Confirm which named admins can make the change and who signs off on rollback.
Immutable ID and IDPEmail mapping
The SAML guide needs property mappings for the user's immutable identifier and the IDPEmail claim. Entra ID matches the federated user to a cloud account through these values, so a wrong or missing mapping can create a second account or block sign-in. Export the user list from the Entra admin center first and compare the identifiers, mail and userPrincipalName attributes against the authentik user records you plan to use.
SAML 2.0 or WS-Federation: which guide fits your environment
The SAML guide is the path to start with when you want authentik to sign users in to Microsoft 365 through the standard SAML 2.0 federation model. It relies on two property mappings: one that carries the user's immutable identifier and one that sends the IDPEmail claim, which Microsoft uses to match the federated account to the right cloud identity. Because the mappings are the core of the setup, the team doing the work needs to understand how the Microsoft identity is matched before the first test sign-in.
- Licensing: The guide's requirements are the ones your team already has for authentik, so you do not need to add a WS-Federation specific Enterprise license to the decision.
- Identity matching: The immutable identifier and IDPEmail mappings decide which account a user lands in, so mismatched values are the most likely source of failed sign-ins.
- Rules out: Teams that need a non-browser or legacy client path that depends on WS-Trust or MEX endpoints should not expect this path to cover them.
- Fit: Organizations that want a standard federation pattern and are willing to verify mappings carefully suit this path.
- Change control: Mapping changes after go-live can break existing matches, so record the values before you change them.
Before you commit, confirm the current requirements in the authentik integration guide for Microsoft 365 (SAML) and check the mapping values against a test user in your own tenant.
The WS-Federation guide is built around browser-based passive authentication. Microsoft 365 sends the user to authentik in the browser, authentik signs the user in, and the session returns to Microsoft. The guide requires authentik 2026.8 and an Enterprise license, and it does not support WS-Trust or MEX endpoints. That combination makes it a narrower fit, and it is the path to choose only when the Enterprise licensing and the browser-only model are acceptable.
- Licensing: Plan for an authentik Enterprise license before the build, since the guide requires one. Ask your procurement team to confirm the license terms for your environment.
- Version: The guide requires authentik 2026.8, so confirm your target version against the supported release list before you start.
- Rules out: Any client or workflow that needs WS-Trust or MEX endpoints is not covered by this guide.
- MFA claim: The guide's MFA mapping tells Entra ID that authentik performed MFA, so every user in the flow must be required to complete MFA.
- Fit: Organizations with browser-only sign-in needs that already run authentik Enterprise suit this path.
Before you choose it, confirm with your Microsoft 365 administrators that every sign-in method they need is browser-based and check the authentik WS-Federation guide for the current version requirement.
The right guide often follows from the environment rather than from a feature list. A team with a single authentik deployment, a standard Microsoft 365 tenant and no Enterprise license tends to start from the SAML path. A team that already runs authentik Enterprise, targets version 2026.8 or later, and only needs browser sign-in can evaluate WS-Federation. The factors below are the ones that usually settle the question.
- Existing license: Whether you already hold authentik Enterprise is the first filter for the WS-Federation path.
- Client types: Inventory every Microsoft 365 client and sign-in method, including desktop and mobile clients, before you pick a guide.
- Version plan: Compare your authentik version with the version named in the WS-Federation guide and the supported release list.
- Tenant data residency: Note the tenant's location, since it is fixed at tenant creation and is not changed by your choice of federation guide.
- Ownership: Name who will own the mapping values, the MFA policy and the license renewal.
Before you decide, document these answers and ask your authentik and Microsoft 365 administrators to confirm them in a test tenant.
Both guides hand the sign-in decision to authentik, so the security posture of the flow depends on the policies you attach to it. The WS-Federation guide makes the MFA risk explicit: its MFA mapping tells Entra ID that authentik performed MFA, and Entra ID will trust that statement. If some users can reach the flow without a second factor, Entra ID will accept a claim that is not true for them. The SAML path also needs the MFA decision made deliberately, even though its guide does not carry the same warning.
- Enforce MFA for every user: Attach an MFA stage to every user who can reach the WS-Federation flow, with no exceptions for service or administrative accounts unless they use a separate flow.
- Test exception paths: Verify that a user in a group without MFA cannot complete sign-in through the federated flow.
- Passive only: Expect that clients depending on active WS-Trust sign-in will fail, and test each client class before go-live.
- Audit the claim: Review the MFA mapping after every authentik upgrade, since mapping behavior is part of the security boundary.
- Recovery access: Keep a documented break-glass path that does not depend on the federated flow.
Before go-live, confirm the MFA behavior with a test user in each group and record the results for your security review.
How to federate the domain to authentik step by step
This sequence moves a Microsoft 365 domain from cloud-managed sign-in to federated sign-in through authentik, with a check at each stage. It ends with a verified pilot sign-in and a clear point to decide whether to move production users.
Choose the federation protocol and confirm prerequisites
The Microsoft 365 owner decides between the SAML and WS-Federation guides before anything is built. WS-Federation requires authentik 2026.8 and an Enterprise license, and it supports browser-based passive authentication only, with no WS-Trust or MEX endpoints. Confirm the authentik version you run against the supported versions in the security policy, and confirm the license before choosing WS-Federation. This step is done when the choice, the target version and the license status are written down and approved.
Create the authentik provider and application
An authentik administrator creates the provider and application using the chosen Microsoft 365 guide, entering the endpoint values that guide specifies. Leave the MFA mapping disabled for now, because the WS-Federation guide warns that this mapping tells Entra ID that authentik performed MFA. The step is complete when the provider metadata or endpoint URLs load in a browser and the application appears in authentik for a test group.
Configure the immutable ID and IDPEmail mappings
The SAML guide requires property mappings for the user's immutable identifier and the IDPEmail claim. Choose the authentik user attribute that will supply the immutable ID, and confirm it is stable and unique for every user in scope, because Entra ID matches federated accounts against this value. Map IDPEmail to the sign-in address the Microsoft 365 user account expects. The step is done when a test user's assertion, checked in the authentik event log or browser developer tools, shows both claims with the values you planned.
Add and verify the domain in Microsoft 365
A Microsoft 365 global administrator adds the domain to the tenant and completes verification with the DNS record Microsoft provides. The domain stays cloud-managed at this stage, so user sign-in does not change yet. Confirm that user principal names on the domain match the identifiers you mapped in the previous step. The step is complete when the domain shows as verified in the Microsoft 365 admin center.
Convert the domain to federated sign-in
The administrator converts the verified domain to federated sign-in using the commands in the authentik guide and Microsoft's current domain federation documentation. Confirm the cmdlets and module versions in Microsoft's documentation before running anything, because supported tooling changes over time. Before this step, confirm that the authentik flow requires MFA for every user in scope, as the WS-Federation guide requires. Also confirm with Microsoft how to reverse the conversion. The step is done when the domain shows as federated and a test sign-in is redirected to authentik.
Test sign-in with a pilot user
Select a pilot user whose immutable ID, IDPEmail and MFA enrollment in authentik are confirmed. Sign in to Outlook on the web, the Microsoft 365 app launcher and at least one desktop Office app. Include a user without MFA enrollment to confirm that authentik denies access. Because the flow is passive-only, also test any client that depends on legacy authentication. The step is complete when the sign-in succeeds through authentik, MFA is enforced at the authentik step, and the Entra ID sign-in logs show the federated authentication.
Mapping immutable IDs and IDPEmail between authentik and Entra ID
This table compares the identity values authentik sends to Microsoft 365 with the values Entra ID stores for each account. Read each row as a question to answer before you create the federated domain, since the immutable identifier is hard to change once users have signed in. The main takeaway is that the immutable ID and the sign-in name must be decided and checked before any user is matched to an existing cloud account.
| Identity value | What it is for | What to check before go-live |
|---|---|---|
| Immutable identifier | Lets Entra ID match a federated sign-in to one cloud account even when names change. authentik sends it through a property mapping described in the SAML guide. | Confirm which authentik attribute holds a value that never changes for the person, and that every user has one before the first sign-in. |
| IDPEmail claim | Tells Microsoft 365 which email address the identity provider asserts for the user, so the sign-in can be matched to the right account. | Confirm the value matches the email the user already has in Entra ID, including case and any alias differences. |
| User principal name (UPN) | The sign-in name users type at Microsoft 365. It must sit on a domain that is verified and federated in the tenant. | Confirm the UPN suffix is the federated domain and that renames in authentik will not silently change it. |
| Mail attribute | The primary SMTP address shown on the mailbox. It is separate from the sign-in name and can differ from it. | Compare the mail value in the Entra admin center download with the authentik email attribute for a sample of users. |
| On-premises identifiers | Fields such as the on-premises immutable ID that show a cloud account was synchronized from directory data, if such a sync exists. | Confirm whether any existing account was created by directory sync, since that changes which identifier must match. |
| Checking current values | The Entra admin center lets you download the user list as CSV from Users, All users, Download users, including userPrincipalName, mail and on-premises identifiers. | Export the list before changes, save it as a baseline, and compare it after the test sign-in with a pilot user. |
| Stability rule | The identifier used for matching must not change for the life of the account, even if a person changes name, department or email. | Choose the attribute with your identity team and document it, since changing it later means re-matching accounts. |
Security decisions for the MFA claim and admin access
The WS-Federation flow hands Entra ID a claim that authentik performed MFA, so trust in that claim decides who can reach Microsoft 365. The cards below cover the MFA enforcement, the lockout safeguards, the admin rights over the federated domain and the authentik version you run.
Force MFA for every federated user
The WS-Federation guide warns that its MFA mapping tells Entra ID that authentik performed MFA. Every user who can reach this flow must be forced through an authentik MFA stage, with no exceptions for service accounts, executives or legacy users. Check each authentication flow bound to the Microsoft 365 application and test a user without an enrolled factor to confirm enrollment is forced rather than skipped.
Scope the MFA claim to this flow
Because Entra ID trusts the claim it receives, a flow that skips MFA while still sending the mapping would overstate assurance for every session. Review which applications and flows share the mapping and remove it from any path that does not enforce MFA. Document the decision so an auditor can trace the claim to the control that backs it.
Keep a cloud-only break-glass admin
If authentik, its database or its certificate fails, a domain federated to authentik cannot sign administrators in. Keep at least one cloud-only Global Administrator account that is not federated, protected with phishing-resistant MFA and stored under a documented break-glass procedure. Test that it signs in while the federated path is switched off, in a scheduled exercise.
Limit who changes domain federation
Changing the federation settings of a domain, or converting a domain between managed and federated, can break sign-in for the whole tenant. Restrict these changes to a small named group of Entra administrators, use privileged role assignment with approval where your licensing allows it, and alert on any change to the domain's authentication type. Confirm the audit log retention your tenant provides before relying on it.
Track the authentik release line
The authentik security policy lists 2026.5.x and 2026.8.x as the supported versions receiving security fixes, and security releases are announced at least 24 hours in advance. The WS-Federation guide requires authentik 2026.8, so a federation running an older line may be outside both the requirement and the support window. Schedule upgrades, subscribe to the release feed and plan a staging test for each security release.
Common Microsoft 365 federation failures and their fixes
This table lists the failures teams most often hit when federating a Microsoft 365 domain to authentik, with the likely cause and the check or fix for each. Read it during pilot testing, before users are moved, and keep it open during cutover.
| Failure | Likely cause | Check or fix |
|---|---|---|
| Duplicate accounts after sign-in | The immutable ID mapping in authentik does not match the value Entra ID stored for the existing user, so Entra ID creates a second identity. | Compare the immutable ID claim sent for a test user with the ImmutableId on that user in Entra ID. Correct the property mapping, then remove the duplicate cloud account before retrying. |
| Sign-in fails for a user with a valid password | The IDPEmail claim does not match the user's UPN in Microsoft 365, so the federated sign-in cannot be matched to the cloud account. | Confirm the authentik user's email and the UPN in the tenant are identical, including case and domain suffix. Fix the source attribute or the UPN rather than editing claims per user. |
| WS-Trust or MEX request errors in logs | A client or tool is calling WS-Trust or MEX endpoints, which the passive-only WS-Federation flow does not provide. | Confirm which client sends the request. Browser-based sign-in should not need those endpoints. Use the authentik WS-Federation guide for the supported flow and check client versions that still use active authentication. |
| Users stuck at a Microsoft error after login | The WS-Federation flow reached Entra ID without the expected response, often because the relying party trust or endpoint URLs do not match the tenant configuration. | Compare the endpoint and identifier values in authentik with the domain federation settings in the tenant. Retest in a private browser session after each correction. |
| MFA claim accepted without a real second factor | The MFA mapping tells Entra ID that authentik performed MFA, so any user who reaches the flow without a second factor is trusted as if they had one. | Enforce MFA for every user in authentik before go-live, and test a account without an enrolled factor to confirm it is blocked. Review the mapping whenever authentication stages change. |
| Users cannot reach the authentik login page | The authentik endpoint is not reachable from the user's network, the reverse proxy blocks the redirect path, or the certificate chain is incomplete for the client. | Test the sign-in URL from a user network and a remote network. Check the proxy routes and TLS chain, and confirm that browsers on managed devices trust the internal certificate authority. |
| Federation breaks after an authentik upgrade | The release notes for the upgrade changed providers, mappings or the flow, or the Enterprise license is missing or expired. | Confirm the authentik version is 2026.8 or later and the Enterprise license is active before upgrading. Review the mappings and test sign-in in a staging copy first. |
| Mail or Teams sign-in works but admin portal does not | Administrative access depends on separate cloud accounts or conditional access rules that were not tested through the same federated path. | Test administrator accounts separately, confirm break-glass accounts remain outside federation, and document which sign-in path each role uses. |
Questions buyers ask before federating Microsoft 365 to authentik
Does federating Microsoft 365 to authentik require an Enterprise license?
For the WS-Federation route, yes. authentik's Microsoft 365 WS-Federation guide requires an Enterprise license and authentik 2026.8. The SAML guide is listed in the integrations catalog without that requirement, but you should confirm the license position for your exact edition with authentik before you commit. The Enterprise edition is listed at $5 per user per month billed annually, plus $0.02 per external user per month, according to the authentik pricing page. Enterprise also unlocks the Microsoft Entra ID integration, which is a separate feature from the federation itself. Ask for the license count in writing, because the per-user basis drives the recurring cost.
Should we choose SAML or WS-Federation for Microsoft 365?
Choose SAML unless you have a specific reason to use WS-Federation and can meet its requirements. The WS-Federation guide requires authentik 2026.8 and an Enterprise license, supports only browser-based passive sign-in without WS-Trust or MEX endpoints, and adds an MFA mapping that tells Entra ID authentik performed MFA. The SAML guide needs property mappings for the user's immutable identifier and the IDPEmail claim. Confirm with your Microsoft 365 administrators which clients rely on legacy authentication flows, because those clients will not work through passive-only sign-in.
How much effort and time does a Microsoft 365 federation take?
Effort depends on the number of domains, the state of your directory, the sign-in clients in use and whether your MFA policies already cover every user. The main work items are the authentik provider and property mappings, the Microsoft 365 domain conversion and testing with pilot users, and the rollout plan for each client type. No duration is set by the supplied sources, so ask any partner, including DeployOpen, for a timeline built from a written scope. Most engagements are fixed-scope, so the timeline and deliverables are agreed in writing before work starts.
What do we need to provide before the federation work starts?
You need a working authentik deployment that meets the version and license requirements, a list of Microsoft 365 domains, and an inventory of users with their on-premises identifiers. Microsoft Entra ID lets administrators download the user list as a CSV from the Entra admin center (Users, All users, Download users), which includes attributes such as userPrincipalName, mail, department and on-premises identifiers. You also need an owner for the Microsoft 365 global admin role, an agreed MFA policy that covers every user, and a test group. Confirm which Microsoft 365 plan each user holds, since that affects licensing.
Can our internal team federate Microsoft 365 to authentik alone?
A capable identity team can do it, provided it has authentik and Microsoft 365 administration experience and time to test. The SAML and WS-Federation guides cover the mapping steps, but the risk sits in details such as immutable ID matching, the MFA claim and what happens to existing sign-ins during cutover. Consider a partner if your team has no one who has tested federation against Entra ID, or if you need a fixed scope with written deliverables. DeployOpen plans, implements, hardens, documents and supports self-hosted platforms in your own infrastructure, and its engagements are fixed-scope.
How does the Business user limit affect our Microsoft 365 plan choice?
Microsoft 365 Business plans, including Business Basic, Business Standard, Business Premium and Apps for business, are limited to 300 users per tenant across the Business family. Enterprise plans such as Microsoft 365 E3 and E5 have no user limit. If your headcount may grow past 300, plan for an Enterprise tenant before federation, because moving tenants later adds scope. Business Basic does not include the desktop Office apps, which start with Business Standard. Entra ID P1 is included in Microsoft 365 E3 and Business Premium, and P2 in E5, so plan choice also affects which identity features you pay for separately.
What happens to our data and sign-in if the Microsoft 365 subscription ends?
When a Microsoft 365 for business subscription ends, it moves from Active to Expired (30 days), then to Disabled (90 days, admins only), then to Deleted. After a cancellation, data left behind might be deleted after 90 days and will be deleted no later than 180 days, according to Microsoft. Because authentik is the sign-in source, a lapsed subscription also ends sign-in to Microsoft 365 services through federation. Before any renewal decision, export what you need. Microsoft Purview eDiscovery can export Exchange items as PST or .msg files and SharePoint and OneDrive content as native documents, but exporting requires an E3 or E5 license, and export packages expire 14 days after creation.
Which MFA claim settings need care when federating Microsoft 365?
The WS-Federation MFA mapping tells Entra ID that authentik performed multifactor authentication. authentik's guide warns that the flow must therefore require MFA for every user. If any account can sign in without a second factor, Entra ID will still trust the claim. Review every authentication stage and policy binding before enabling the mapping, and test with accounts that have no MFA enrolled. Confirm with your security team whether Entra ID's own Conditional Access policies will still be applied on top of the federated sign-in.
Running and reversing the federation after go-live
Once the federation is live, authentik becomes a sign-in dependency for every Microsoft 365 user in the domain, so its availability is the first operational control to design. Monitor the authentik server and worker containers and the PostgreSQL database behind them, and set alerts on failed sign-ins through the WS-Federation or SAML endpoints, not only on container health. Plan upgrades inside the versions authentik still supports with security fixes, which the project lists as 2026.5.x and 2026.8.x, and note that the project announces security releases at least 24 hours in advance. Because the WS-Federation guide requires authentik 2026.8 and an Enterprise license, confirm the minimum version against that guide before each upgrade window and test the Microsoft 365 trust on a staging instance first.
The rollback path must be written and tested before go-live, because switching a domain back to cloud authentication is a change to the Entra tenant, not to authentik. Keep the original cloud-only sign-in configuration documented, record the federated domain settings, and confirm with Microsoft how a domain is converted back to managed authentication and how long that takes. Plan for users to be reachable during the switch, including administrator accounts that can sign in without authentik. Also confirm that the Entra ID tenant's data location was chosen at creation and cannot be changed afterward, so the rollback plan does not assume a residency change is possible.
Licensing decides which Entra controls remain available when authentik is unavailable or being changed. Entra ID Free is included with Microsoft cloud subscriptions and provides MFA, SSO to SaaS apps and basic reports, while Entra ID P1 and P2 add conditional access and identity protection features. Confirm with Microsoft which sign-in logs, risk signals and conditional access policies your tenant can use during an authentik outage, because some depend on P1 or P2 licensing. Document these checks as part of the operations runbook so the team does not discover a missing control during an incident.
How DeployOpen scopes and delivers a Microsoft 365 federation
DeployOpen plans, implements, tests and documents authentik as the identity provider for your Microsoft 365 tenant inside your own infrastructure. Each engagement starts with a written, fixed scope that settles the protocol choice, the identity mappings and the MFA position before any configuration begins.
How we scope
- Written scope covers the chosen protocol, SAML or WS-Federation, and the reasons for that choice.
- Scope records the authentik version, the Enterprise license position and the tenant plan on the Microsoft side.
- Scope names the immutable ID and IDPEmail mapping rules and who signs off on the user population.
How we build
- We deploy authentik in your infrastructure and configure the Microsoft 365 provider and its property mappings.
- Test users cover passive sign-in, domain verification, MFA enforcement and sign-out across browsers and clients.
- Configuration is checked against the MFA claim behavior before any user outside the pilot group is moved.
How we hand over
- Handover includes configuration records, mapping definitions, a runbook for certificate and metadata renewal, and test evidence.
- Documentation explains how to add users, handle leavers and reverse the federation if needed.
- Your team receives a walkthrough of the operating procedures before the engagement closes.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainers can cover authentik version upgrades, including checks on the supported release lines.
- Confirm the support terms, response expectations and included testing in the written agreement before starting.
