Skip to content

Conversation

@fstau
Copy link

@fstau fstau commented Jan 14, 2026

Add tutorial: Microsoft Entra ID Group Name Sync

Summary

This PR adds a community tutorial explaining how to configure Microsoft Entra ID to return human-readable group names instead of GUIDs when using OAuth group synchronization with Open WebUI.

Background

I am working with a couple of organisations deploying Open WebUI internally that have run into issues with Microsoft Entra ID group synchronisation leading to GUIDs as Open WebUI group names when following default setup instructions. There are issues / discussions on the open-webui repository that describe troubleshooting steps and solutions. I have verified that those work to unblock my own deployments and created this writeup of the required steps to aid others trying to solve this issue via better discoverability in the docs.
This information was gathered from community discussion in open-webui/open-webui#13657.

Content

The tutorial covers:

  • Step-by-step configuration of App Registration token claims
  • Manifest modifications to enable cloud_displayname
  • Enterprise Application group assignment requirements
  • Required Open WebUI environment variables for OAuth group management
  • Verification steps using jwt.ms
  • Troubleshooting common issues (GUIDs still appearing, groups not syncing, JIT creation not working)
  • Example Docker Compose configuration

Documentation Standards

  • Includes community contribution warning
  • Uses terminology consistent with official docs ("Microsoft Entra ID", "Just-in-Time (JIT) group creation")
  • Cross-references relevant feature documentation (/features/auth/sso, /features/rbac/groups)

@pr-validator-bot
Copy link

ℹ️ Documentation PR Guidelines

👋 Welcome! This is an automated message posted on all new documentation PRs to help guide our contributors. Just because this comment appeared doesn't mean you have done anything wrong!

Please ensure you're using the correct branches:

Target branch (where you're merging TO):

  • dev branch: For documentation related to upcoming Open WebUI releases (new features, new environment variables, anything dependent on unreleased versions and unreleased features/fixes/changes)
  • main branch: For content that can go live immediately (fixes, tutorials, documentation not dependent on unreleased features)

Source branch (where you're merging FROM):

  • If targeting dev, create your branch from your fork's dev branch
  • If targeting main, create your branch from your fork's main branch
  • ⚠️ Mismatched branches can and will result in unwanted file changes being included in your PR!

If your docs PR depends on a pending PR in open-webui/open-webui:

  • Convert this PR to DRAFT mode!
  • Link to the related main repo PR in your description for clarity
  • We'll review both together once the PR on the main repo is merged

Please adjust your PR target branch, source branch, and/or draft status accordingly if needed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants