Overview

Bespoke WordPress plugin for Microsoft Entra ID (Azure AD) authentication on Avon and Somerset Police sites. Features are toggled via wp-config.php — no admin screens, no per-site plugin settings.

It follows the same packaging style as WP Core: Composer-installed and feature-flagged. The plugin speaks OpenID Connect (OIDC) only — not WS-Federation / SAML.

Typical outcomes:

Users sign in with an organisation Entra account
WordPress users are created or updated on first login (JIT)
An Entra security group can map to a WordPress role (for example administrator)
Everyone else receives a low-privilege default role (for example subscriber)

Product-level authorisation stays in the theme. This plugin answers “who are you?” and “may you use wp-admin?”.

Features

Feature	Default	Description
force_login	true	Redirects anonymous front-end visitors to Entra sign-in
login_ui	true	Adds a Microsoft button on `wp-login.php` and can auto-start Entra
disable_password_login	true	Blocks password login except for break-glass accounts

Always loaded when the plugin is active:

OIDC authorization code flow against a single Entra tenant
JIT WordPress user provisioning from ID token claims
Entra group object ID → WordPress role mapping
/wp-admin/ restricted to mapped roles and break-glass accounts

Public helpers: asp_entra_feature_enabled(), asp_entra_get_user_identity().

Requirements

WordPress 6.4+
PHP 8.2+
Composer (when installed as a dependency)
An Entra app registration (OIDC / Web platform)
OpenSSL PHP extension (for RS256 ID token validation)

Installation

Via Composer (recommended):

"require": {
  "policedigitalservices/asp-wp-entra": "^1.0"
}

Then:

composer update policedigitalservices/asp-wp-entra

Activate WP Entra, configure ASP_ENTRA / ASP_ENTRA_FEATURES, and flush permalinks once (Settings → Permalinks → Save) so the OIDC callback path resolves.

For local Docker development you can bind-mount the plugin instead of installing via Composer.

Configuration

Connection settings live in ASP_ENTRA (or matching environment constants). Optional behaviours are enabled through ASP_ENTRA_FEATURES.

define('ASP_ENTRA', [
    'tenant_id'     => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    'client_id'     => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
    'client_secret' => 'your-client-secret',
    'redirect_path' => '/auth/entra/callback',
    'default_role'  => 'subscriber',
    'group_roles'   => [
        // Entra group OBJECT ID => WordPress role
        'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' => 'administrator',
    ],
    'break_glass_logins' => [
        'breakglass',
    ],
    'login_button_text' => 'Sign in with Microsoft',
]);

define('ASP_ENTRA_FEATURES', [
    'force_login'            => true,
    'login_ui'               => true,
    'disable_password_login' => true,
]);

Common site patterns:

Entra-gated front end — force_login => true, group roles for admins
Public front end + Entra for staff/admin — force_login => false, group roles for admins

Break-glass password login (when enabled): https://your-site.example/wp-login.php?asp_entra_password=1

Full Entra app registration steps, token validation notes, and troubleshooting live in the repository README.

Hosting

Runs in consuming WordPress sites.

Tech stack

PHP
WordPress
OpenID Connect (Microsoft Entra ID)

Used by

WordPress products that require organisation SSO (for example ERP-style sites)
Other ASP WordPress sites that include the package via Composer

Integrations

In house applications

WP Core

Force IT

Active Directory (via Microsoft Entra ID)

Third party

Microsoft Entra ID

Contacts

Christian King – Development Team Lead

Repositories

asp-wp-entra

Resources

> TODO: Add backlog, board, or related docs.