Configuring an Identity Provider for Ed-Fi Admin App
The Ed-Fi Admin App uses an Open ID Connect (OIDC) compatible Identity Provider (IdP) for managing user accounts. In theory any OIDC-compatible IdP will suffice. The Ed-Fi Alliance has validated four providers end-to-end on the native Windows/IIS deployment: Keycloak (the default example), Microsoft Entra ID, Google Workspace, and Auth0. Each has its own guide, linked below.
General IdP Guidance and Configuration
Backend Configuration Settings
The Ed-Fi Admin App backend requires specific configuration settings to connect to your OIDC-compatible Identity Provider. These settings are typically configured in the application's environment variables or configuration files.
Key configuration parameters include:
- Authority URL: The base URL of your IdP (e.g.,
https://your-keycloak-server/realms/edfi) - Client ID: The client identifier registered in your IdP (e.g.,
edfiadminapp) - Client Secret: The confidential secret associated with the client
- Redirect URI: The callback URL where the IdP sends authentication responses (e.g.,
https://your-admin-app-api-url/api/auth/callback/<oidc-id>, where<oidc-id>is the id of theoidctable row) - Post Logout Redirect URI: Where users are redirected after logging out (e.g.,
https://your-admin-app-url/api/auth/post-logout) - Response Type: Typically set to
codefor authorization code flow - Scope: The OIDC scopes requested, typically
openid profile email
These settings must match the configuration in your IdP to ensure proper authentication flow.
Bootstrap User Concept
The Ed-Fi Admin App uses a bootstrap user mechanism to initialize the system with its first administrative user. This is necessary because:
- The application requires at least one user with administrative privileges to configure the system
- User permissions and roles are managed within the Admin App itself, separate from the IdP
- The bootstrap user provides the initial entry point to set up additional users and permissions
How it works:
- When the Admin App starts for the first time (or when the database is empty), it looks for a configured bootstrap user
- This user's email address or username is specified in the application configuration
- When this user first authenticates through the IdP, they are automatically granted administrative privileges in the Admin App
- Subsequent users who authenticate must be granted permissions by an existing administrator
Configure the bootstrap user email/username before deploying the application to production. This ensures you can immediately access the system after initial deployment.
Authentication and Authorization Architecture
The Ed-Fi Admin App implements a two-layer security model:
Authentication (IdP Layer):
- The Identity Provider handles user authentication and session management
- Users log in through the IdP interface (e.g., Keycloak login page)
- The IdP validates credentials and issues authentication tokens
- The application uses cookie-based authentication to maintain user sessions
Authorization (Admin App Layer):
- The Admin App maintains its own authorization system independent of the IdP
- User permissions, roles, and access controls are managed within the Admin App database
- The IdP does not need to provide Admin App roles or permissions; those are managed within the Admin App database
- The Admin App does require a populated
emailclaim for each user (typically via theemailscope; some providers require enabling the claim) - Users only need a valid IdP account; all authorization decisions are made by the Admin App
What this means for IdP configuration:
- Ensure your IdP issues the
emailclaim for users (Entra requires addingemailas an optional claim) - You do not need to map roles or permissions from the IdP to the Admin App
- Users simply need a valid account in the IdP with basic profile information (username, email, name)
- All permission management happens within the Admin App after successful authentication
This separation of concerns allows for flexible user management while maintaining security and simplifying IdP setup.
How Provider Settings Are Loaded
Admin App's OIDC integration is generic and table-driven. On startup the API reads the oidc table and registers one authentication strategy per provider, discovering each provider's endpoints automatically from {issuer}/.well-known/openid-configuration. Provider values reach that table through the API config file packages/api/config/production.js (the SAMPLE_OIDC_CONFIG block), which the API seeds into the oidc table on first startup when the table is empty.
Configuring any provider therefore follows the same five steps: (1) register an application with the provider, (2) put its values in production.js (SAMPLE_OIDC_CONFIG), (3) set the first admin's email (ADMIN_USERNAME), (4) set the frontend variables, and (5) sign in. No application code changes are required. The app uses the email claim as the username and matches it to a user that must already exist with a role.
On a fresh, single-provider install the oidc table starts empty, so the provider you configure lands at row id 1 — the frontend's default (VITE_OIDC_ID=1).
Provider Guides
Step-by-step guides for the four validated providers:
- Keycloak — the bundled default example.
- Microsoft Entra ID
- Google Workspace
- Auth0