[DRAFT] EDFI-2794 Document Entra ID and Google Workspace for Windows, Docker and Unix

[analiliagutierrez]

Draft until Admin APP v4.1 is released.

Summary

Adds provider-specific OIDC setup guides for Microsoft Entra ID and Google Workspace, restructures "Configuring an Identity Provider" into a category (one page per provider), and makes the surrounding Admin App docs identity-provider agnostic so they no longer read as Keycloak-only. Also adapts the Docker Compose and Unix-like install guides to the same generic OIDC structure (EDFI-2851).

Tickets

• [EDFI-2794] Document Microsoft Entra ID and Google Workspace as OIDC providers (Windows IIS path)
• [EDFI-2851] Extend the Docker and Unix-like install guides to the generic OIDC provider structure
• [EDFI-2795] Automate Entra ID App Registration via Microsoft Graph (PowerShell)

Dependency

Based on the EDFI-2779_Windows_Server_Installation_Guide branch (PR #537), not main — merge after #537. This branch builds on #537's Windows IIS guide restructure.

The EDFI-2795 content documents the idp-entra-setup.ps1 helper, which ships in Admin-App-Installation-Scripts PR #5. Merge these docs together with that PR so the documented script exists when the guide references it (both target the Admin App v4.1 release).

What changed

Identity provider docs restructured into a category (configuration/identity-provider/):

• Parent overview — general IdP guidance, the table-driven configuration model, and links to each provider guide.
• keycloak.md — the existing Keycloak content, moved unchanged, as the bundled default example.
• microsoft-entra-id.md — new: App Registration, client secret, API permissions, the required email optional claim, single-tenant vs. multitenant, production.js and frontend configuration, end-to-end validation and triage.
• google-workspace.md — new: Google Cloud project, OAuth consent screen (Internal audience), OAuth client, production.js and frontend configuration, end-to-end validation and triage.

Made the surrounding Admin App docs identity-provider agnostic:

• Present Keycloak as the bundled default example alongside Microsoft Entra ID and Google Workspace, with links to the provider guides (getting-started/readme, configuration/configuring-admin-app, user-guide/readme, and the Windows IIS pages).
• Generalized the VITE_IDP_ACCOUNT_URL guidance to all three providers.
• Added Microsoft Entra ID and Google Workspace install-all.ps1 examples to the Windows IIS Automated page.
• Documented the idp-entra-setup.ps1 helper (scripts PR #5) as an automated alternative to the manual Entra App Registration (a Part A tip), cross-referenced from the Automated install page; and split the Entra directory-role prerequisites (Cloud Application Administrator to create the app vs. Privileged Role Administrator / Global Administrator to grant admin consent).

Docker and Unix-like install guides (EDFI-2851):

• Adapted both guides to the generic OIDC structure while keeping Keycloak as the bundled example, with agnostic provider notes linking to the Entra ID and Google Workspace guides.
• Docker: added VITE_OIDC_ID to the .env example; documented pointing the API at a non-Keycloak provider (production.js-edfi + ./start-services.ps1 -Rebuild) and the deployment-specific redirect/callback URI.
• Unix-like: marked SAMPLE_OIDC_CONFIG as the Keycloak example, documented the callback URI and the build-time VITE_OIDC_ID / VITE_IDP_ACCOUNT_URL frontend variables.
• Aligned the Keycloak example scope to openid email profile across the configuration and install guides for consistency.

Validation

• markdownlint clean; Docusaurus build passes with onBrokenMarkdownLinks: 'throw' (no broken internal links or anchors); all 14 image URLs return 200.
• Both provider guides were validated end-to-end on a native Windows/IIS deployment.
• Docker/Unix guide changes validated by lint + build (no broken links or anchors). A Docker end-to-end sign-in with a non-Keycloak provider is tracked as follow-up under EDFI-2851.

Screenshots

[Copilot]

Pull request overview

This PR expands the Ed-Fi Admin App documentation to support multiple OpenID Connect identity providers by restructuring the identity-provider docs into a Docusaurus category and adding provider-specific setup guides for Microsoft Entra ID and Google Workspace, while updating surrounding Admin App docs to be IdP-agnostic (not Keycloak-only).

Changes:

• Restructured “Configuring an Identity Provider” into configuration/identity-provider/ with an overview page plus per-provider pages.
• Added new setup/validation guides for Microsoft Entra ID and Google Workspace OIDC configuration.
• Updated Admin App getting-started and Windows/IIS guidance to reference the new provider guides and generalized IdP-specific guidance (e.g., VITE_IDP_ACCOUNT_URL).

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/reference/5-admin-app/user-guide/readme.md	Updates login guidance to reference validated IdPs and link to the new IdP category.
docs/reference/5-admin-app/getting-started/windows-iis-installation/readme.md	Updates Windows/IIS prerequisites text and link to the new IdP docs location.
docs/reference/5-admin-app/getting-started/windows-iis-installation/manual.md	Updates IdP links to the new category path.
docs/reference/5-admin-app/getting-started/windows-iis-installation/automated.md	Adds Entra/Google install-all.ps1 examples and updates IdP links.
docs/reference/5-admin-app/getting-started/unix-installation.md	Updates “Next steps” link to the new IdP docs location.
docs/reference/5-admin-app/getting-started/readme.md	Generalizes authentication/provider language and updates IdP links.
docs/reference/5-admin-app/getting-started/docker-installation.md	Generalizes VITE_IDP_ACCOUNT_URL guidance across providers and updates IdP link.
docs/reference/5-admin-app/configuration/identity-provider/category.json	Introduces a Docusaurus category for provider-specific IdP docs.
docs/reference/5-admin-app/configuration/identity-provider/readme.md	New overview page describing the generic/table-driven OIDC model and linking to provider guides.
docs/reference/5-admin-app/configuration/identity-provider/keycloak.md	Rehomes Keycloak content under the new category and adjusts its sidebar ordering/title.
docs/reference/5-admin-app/configuration/identity-provider/microsoft-entra-id.md	New Entra-specific OIDC registration/config/validation guide.
docs/reference/5-admin-app/configuration/identity-provider/google-workspace.md	New Google Workspace OIDC registration/config/validation guide.
docs/reference/5-admin-app/configuration/configuring-admin-app.md	Updates authentication text and VITE_IDP_ACCOUNT_URL guidance to be provider-agnostic and links to the new IdP category.