Connect Open WebUI to Azure AD (Entra ID): Authentication Your SMB Already Has

In the last post, we got Open WebUI and Ollama running in Docker. It works. You can chat with your local model. But there is a fundamental problem with our setup: we set WEBUI_AUTH=false, which means anyone who can reach the server has full, unauthenticated access.

That is not a minor configuration detail. That is a production security liability.

You have invested in a local LLM to keep your data private. You have configured the models, the tools, the integrations. But if any person on your network or worse, the public internet, can open the URL and start asking questions, all that effort is meaningless. Your AI is no more secure than an open door.

This post fixes that. We are going to connect Open WebUI to your company’s Azure AD (Entra ID) the identity system your business likely already pays for through Microsoft 365. No new software to install. No separate identity server to manage. Just authentication that matches what your team already uses every day.

The setup takes about 20 minutes from start to finish, and by the end, you will have a fully authenticated Open WebUI instance with role-based access control through Azure AD groups.

What Azure AD Brings to Your AI Deployment

Before we touch any configuration, let us be clear about what we are actually solving.

The Cost of No Authentication

When WEBUI_AUTH is set to false, Open WebUI presents a blank login screen. No credentials required. No session management. Anyone with the URL gets in. For a personal deployment on your home network, that might be acceptable. For a business deployment, that is a compliance nightmare.

The risk is worse than you think. According to ShareGate, 85%+ of Microsoft 365 users experience credential-related security incidents, according to recent security research. Your AI instance sitting on an internal network is not immune. A compromised workstation, a misconfigured firewall rule, or a curious colleague; they all become entry points.

Why Azure AD Makes Sense for SMBs

Here is the strategic advantage: over 3.7 million companies globally already use Microsoft 365, which includes Entra ID (formerly Azure AD) as part of the subscription. For a small or mid-sized business, that means your identity infrastructure already exists. You are not buying a new system. You are connecting one system to another.

The numbers back this up. Microsoft 365 Business Premium which bundles productivity tools with enterprise-grade identity and security is specifically targeted at SMBs up to 300 users. SMB revenue from Microsoft 365 grew 22% year-over-year in 2025, outpacing enterprise growth.

MFA reduces account compromise risk by over 90% when enabled. By routing your AI authentication through Azure AD, you inherit that protection automatically. Your team uses the same login they use for email, Teams, and SharePoint. Same credentials. Same security policies. Same multi-factor authentication prompts they already accept every morning.

What You Get Beyond Basic Login

Azure AD gives you more than just authentication. It gives you:

Role-based access control map Azure AD groups to Open WebUI user roles (admin, editor, viewer)
Automatic provisioning new hires get access when you add them to a group
Automatic deprovisioning departed employees lose access when you remove them
Conditional Access policies require MFA, restrict by device compliance, block from certain locations
Audit logging every login attempt is recorded in your Microsoft 365 audit trail

This is the same identity layer that protects your financial systems, your customer databases, and your intellectual property. Your AI deserves the same protection.

Prerequisites

Before we begin, make sure you have the following:

An Open WebUI instance running in Docker If you have not set this up yet, follow the previous post first
A Microsoft 365 tenant If your business uses Outlook, Teams, or SharePoint, you likely already have one
Global Administrator or Application Administrator role in your Entra ID tenant you need this to create app registrations
Access to your Azure AD tenant’s admin portal at https://entra.microsoft.com

If you are not sure whether your business has an Entra ID tenant, ask your IT administrator. If you are the IT administrator, log in to the Azure Portal and look for “Azure Active Directory” or “Microsoft Entra ID” in the left sidebar.

Step 1: Create the App Registration in Entra ID

The first step is telling Azure AD that Open WebUI is a trusted application. We do this by creating an App Registration.

Navigate to App Registrations

App registrations > New registration

Configure the Registration

Fill in the following fields:

Name: Open WebUI (or whatever name makes sense for your organization)
Supported account types: Select “Accounts in this organizational directory only” (Single tenant)
Redirect URI: Set the Platform to Web and the URI to http://<your-openwebui-host>/auth/login

For example, if your Open WebUI instance is running at https://ai.yourcompany.com, the redirect URI would be https://ai.yourcompany.com/auth/login.

Important: The redirect URI must use https if your Open WebUI is behind TLS. If you are testing locally without HTTPS, use http://localhost:8080/auth/login.

Click Register.

Record Your Credentials

After registration completes, you will see the Overview page. Record the following three values you will need them in the next step:

Application (client) ID This is your client identifier
Directory (tenant) ID This is your tenant identifier
Client Secret You will need to create this under Certificates & secrets > New client secret

Create a Client Secret

Under Certificates & secrets, click New client secret. Fill in:

Description: Open WebUI Authentication
Expires: Choose 12 months (or longer if you prefer)

Click Add, then immediately copy the secret value. You will not be able to see it again after you leave this page. This is your client secret treat it like a password.

Understanding What We Just Created

Here is what each identifier represents:

Application (Client) ID This is the unique name of your application in Azure AD. Think of it as your app’s username. Azure AD uses this to identify Open WebUI when it requests authentication.
Directory (Tenant) ID This identifies your organization’s Azure AD instance. If your company has multiple Azure AD tenants (common in larger organizations), this ensures Open WebUI talks to the right one.
Client Secret This is the proof that Open WebUI is really who it says it is. When Open WebUI requests a token from Azure AD, it presents both the Client ID and this secret. Without a valid secret, Azure AD will reject the request.

The Web platform type (not SPA or Mobile) is intentional. We will explain why in the troubleshooting section below.

Step 2: Update Your Docker Compose Configuration

Now we update the Open WebUI container to use Azure AD instead of the disabled authentication we set up previously.

Here is the updated web service section from your docker-compose.yml:

services:
  web:
    image: ghcr.io/open-webui/open-webui:v0.8.12
    depends_on:
      - llm
    environment:
      - OLLAMA_BASE_URLS=http://llm:11434
      - WEBUI_AUTH=true
      - WEBUI_SECRET=<your-secret>
      # Azure AD / Entra ID Authentication
      - OAUTH_PROVIDERS=true
      - MICROSOFT_CLIENT_ID=<CLIENT_ID>
      - MICROSOFT_CLIENT_SECRET=<CLIENT_SECRET>
      - MICROSOFT_CLIENT_TENANT_ID=<TENANT_ID>
      - MICROSOFT_REDIRECT_URI=http://localhost:8080/oauth/microsoft/callback
      - MICROSOFT_SCOPE=openid profile email
      - OPENID_PROVIDER_URL=https://login.microsoftonline.com/<TENANT_ID>/v2.0/.well-known/openid-configuration
      - MICROSOFT_OAUTH_SCOPE=openid email profile offline_access
      - ENABLE_OAUTH_SIGNUP=true
      # Optional: Group-based access control
      - ENABLE_OAUTH_GROUP_MANAGEMENT=true
      - ENABLE_OAUTH_GROUP_CREATION=true
      - OAUTH_GROUP_CLAIM=groups
      - DEFAULT_ROLE=viewer
    restart: unless-stopped
    ports:
      - 8080:8080
    volumes:
      - ~/openweb-ui:/app/backend/data

Let me break down every new environment variable.

Authentication Core Variables

Variable	Purpose
`WEBUI_AUTH=true`	Enables authentication. This flips the switch from “open to anyone” to “login required”
`OAUTH_PROVIDERS=true`	Tells Open WebUI to enable OAuth-based login providers
`MICROSOFT_CLIENT_ID`	The Application (Client) ID from your App Registration
`MICROSOFT_CLIENT_SECRET`	The secret value you copied when creating the client secret
`MICROSOFT_CLIENT_TENANT_ID`	The Directory (Tenant) ID from your App Registration

Redirect and Scope Variables

Variable	Purpose
`MICROSOFT_REDIRECT_URI`	Where Azure AD sends the user after successful login. Must exactly match what you configured in the App Registration
`MICROSOFT_SCOPE`	What information Open WebUI requests from Azure AD. `openid` enables OAuth 2.0, `profile` gets the user’s name, `email` gets their email address

Group Management Variables (Optional)

Variable	Purpose
`ENABLE_OAUTH_GROUP_MANAGEMENT=true`	Allows Open WebUI to manage users based on Azure AD group membership
`ENABLE_OAUTH_GROUP_CREATION=true`	Automatically creates Open WebUI user accounts when Azure AD users log in for the first time
`OAUTH_GROUP_CLAIM=groups`	Tells Open WebUI to look at the `groups` claim in the Azure AD token to determine group membership
`DEFAULT_ROLE=viewer`	Sets the default role for users who are not in any designated admin or editor groups. Options are `admin`, `editor`, or `viewer`

The group management variables are where this setup moves from simple login to actual access control. Without them, every person who can log in with your Azure AD gets the same default role. With them, you can create Azure AD groups like Open WebUI Admins and Open WebUI Contributors, add people to those groups, and have their Open WebUI permissions changed automatically.

Step 3: Restart and Verify

From the directory containing your docker-compose.yml:

docker compose down
docker compose up -d

Give it about 60 seconds. Open WebUI needs to restart with the new authentication configuration.

Navigate to your Open WebUI instance URL. You should see a login page with a Sign in with Microsoft button.

Click it. You will be redirected to your organization’s Microsoft login page. Enter your credentials (and complete MFA if enabled), and you should be redirected back to Open WebUI, logged in and ready to go.

If you are in the Open WebUI Admins Azure AD group (or whichever group you designate), you will also see the Admin Panel in the sidebar.

The April 2025 PKCE Bug and How to Work Around It

Here is the thing that is going to trip you up if you are not prepared: Open WebUI’s Microsoft OAuth provider has a documented bug that prevents login from working correctly in certain configurations.

The Problem: AADSTS9002325

When attempting to log in, you may encounter an error like:

AADSTS9002325: The request body must contain the parameter code_challenge and code_challenge_method for the PKCE flow

This error, AADSTS9002325, was first reported in a GitHub Discussion in April 2025. The root cause is that Open WebUI’s Microsoft OAuth provider does not implement PKCE (Proof Key for Code Exchange), which is a security requirement for public clients like single-page applications.

The Workaround

The workaround is straightforward: when creating your App Registration, set the platform type to Web (confidential client) instead of SPA (Single Page Application).

This is exactly what I configured in Step 1 above, so if you followed those instructions, you should be fine. The Web platform type uses client secrets for authentication (which is what we created), so PKCE is not required. The SPA platform type uses a different flow that Open WebUI does not currently implement.

What This Means Going Forward

The bug is known and documented by the Open WebUI community. A code fix has been proposed in the same GitHub discussion, but as of May 2026, the workaround remains the recommended approach. Keep this in mind if you are reading tutorials that suggest using the SPA platform type—it will not work.

Troubleshooting Common Issues

Even with the correct configuration, you may hit a few snags. Here are the most common ones and their fixes.

Issue: Email Address Not Showing

After logging in, your profile shows your name but no email address. This is a known configuration issue with Azure AD.

The cause: Azure AD does not include the email claim in the ID token by default for many tenant configurations. Open WebUI needs this claim to associate your Azure AD identity with an Open WebUI user account.

The fix: Go to your App Registration in the Entra admin center:

Navigate to Token configuration > Add optional claim
Select ID as the token type
Add the following claims: email, given_name, preferred_username
Save the configuration

Wait approximately 5 minutes for the change to propagate, then try logging in again. The email should now appear in your profile.

Issue: Groups Appear as GUIDs in Open WebUI

When Azure AD groups are synced to Open WebUI, they show up as long hexadecimal strings (GUIDs) instead of readable names like “Open WebUI Admins.”

The cause: By default, Azure AD tokens contain the raw group GUIDs. To get human-readable names, you need to modify your Azure AD application manifest.

The fix: In the Azure Portal, navigate to your App Registration, then click Manifest. Search for the groupMembershipClaims property and set it to:

"groupMembershipClaims": "All"

Additionally, you need to configure the cloud_displayname mapping. Follow the Open WebUI Entra ID Group Name Sync tutorial for the complete step-by-step process.

Issue: Redirect URI Mismatch Error

After clicking “Sign in with Microsoft,” you are immediately redirected back to Open WebUI with an error about the redirect URI not matching.

The cause: The redirect URI you configured in the Docker Compose file does not exactly match what you configured in the App Registration.

The fix: Compare the two URIs character by character. They must match exactly, including:

Protocol (http vs https)
Domain and subdomain
Port number (if specified)
Path (/auth/login)
Trailing slash (none is correct no trailing slash)

For example, https://ai.yourcompany.com/auth/login in the App Registration must match https://ai.yourcompany.com/auth/login in MICROSOFT_REDIRECT_URI. No variations allowed.

Issue: Users Cannot See Models After Login

Users log in successfully but cannot see any models in the chat interface.

The cause: This is usually a permission issue with the Open WebUI API. When authentication is enabled, the API requires a valid session cookie. If your Open WebUI instance is behind a reverse proxy, the proxy may be stripping or modifying cookies.

The fix: Ensure your reverse proxy (if you use one) passes through all cookies and does not set X-Forwarded-Proto incorrectly. If you are using Nginx, your location block should include:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass_header Set-Cookie;

Issue: Open WebUI Still Shows the Old Login Screen

You updated the environment variables and restarted, but Open WebUI still shows the old authentication behavior (no login page, or the old blank login).

The cause: Open WebUI persists configuration settings to its database. If WEBUI_AUTH was previously set to false, that persisted setting may take priority over your environment variable.

The fix: Either update the setting through the Admin Panel UI (if you can access it), or temporarily set ENABLE_PERSISTENT_CONFIG=false in your environment variables to force the environment variable to take priority. After the setting updates, you can remove the ENABLE_PERSISTENT_CONFIG override.

Organizing Access with Azure AD Groups

This is where the real power comes in. With group management enabled, you do not manage individual users in Open WebUI. You manage them in Azure AD, and Open WebUI automatically syncs their permissions.

How Group Mapping Works

Here is the flow:

You create an Azure AD group (e.g., “Open WebUI Admins”)
You add members to that group
When those members log into Open WebUI, the app reads their Azure AD group membership from the OAuth token
Based on the group membership, Open WebUI assigns the appropriate role

Setting Up Admin Access

To give admin access to a specific group:

In the Entra admin center, create a new group:
- Type: Security
- Group type: Assigned
- Name: Open WebUI Admins
- Description: Members get admin access to Open WebUI
Add your administrators to this group
In Open WebUI, go to Admin Panel > User Management and set the role of your initial user to admin
Then, in Open WebUI’s Admin Panel > Settings > OAuth, configure the mapping. You will need to set the ADMIN_GROUP to the name of your Azure AD admin group:
```
- ADMIN_GROUP=Open WebUI Admins
```

This tells Open WebUI: “Anyone in the ‘Open WebUI Admins’ Azure AD group gets admin privileges.”

Setting Up Viewer-Only Access

For team members who should only be able to use chat features (not modify models, settings, or other users):

Create an Azure AD group called Open WebUI Viewers
Add your team members to it
Set DEFAULT_ROLE=viewer in your environment variables (as shown in Step 2)

Users in this group will log in with full functionality but without admin access. They can chat, use tools, and manage their own settings but they cannot touch the administration panel.

The Maintenance Advantage

Here is the operational benefit that IT teams appreciate: when someone leaves the company, you remove them from Azure AD, and their Open WebUI access is gone too. There is no separate “decommission AI account” step. The identity lifecycle you already manage for email, file shares, and the rest of your IT infrastructure automatically covers your AI deployment.

This is not a minor convenience. For businesses managing employee turnover, it eliminates a whole class of security gaps the “forgot to revoke AI access” scenario that plagues ad-hoc tool deployments.

Wrapping Up

You have just done something that most SMBs never think about: you have connected your local AI to the same identity system that protects the rest of your business.

This is not a small thing. By routing Open WebUI authentication through Azure AD, you get:

Enterprise-grade security MFA, conditional access, risk-based authentication, all inherited from your existing Microsoft 365 investment
Automated user management add people to groups in Azure AD, and their Open WebUI permissions update automatically
Audit and compliance every login attempt is logged in your Microsoft 365 audit trail
Zero additional cost if you already use Microsoft 365, this authentication layer costs nothing extra

The total time investment was roughly 20 minutes. The security improvement is permanent. And your IT team does not have to manage another credential system.

If you just set this up, I want to know how it went. Did you hit the PKCE bug? Did the group sync work on the first try? Drop a comment below.

Next Steps

Add Google OAuth Open WebUI supports multiple OAuth providers simultaneously. You can run both Microsoft and Google authentication side by side using the dual OAuth configuration guide
Explore Conditional Access If your Azure AD has Conditional Access policies configured, your AI instance automatically inherits them. Check with your IT admin about policies like “require compliant device” or “block legacy authentication”
Monitor login activity Use the Microsoft 365 audit log to track who is accessing your AI instance and when
Setup MCP Servers Once authentication is set up, connect your Open WebUI instance to MCP servers to give it real-world tools.

Resources: