🔐 How to Integrate Authentik with WordPress Using the miniOrange OAuth Plugin

Authentik is a powerful identity provider — but when you use it with WordPress via the miniOrange OAuth/OpenID Connect (OIDC) plugin, you can hit a couple of common issues:

• Missing Email Verification
• Username not received
• Authentik sending "email_verified": false

This guide walks through the exact steps to make Authentik talk cleanly to WordPress with the miniOrange plugin.

---

🚦 Background: What WordPress & miniOrange Expect

The WordPress OAuth/OIDC workflow expects certain claims in the ID token:

Claim	Required?	Expected Format
email	✔	true email
email_verified	✔	boolean (not string)
preferred_username or username	✔	string

Authentik defaults email_verified to false for safety, because it doesn’t assume verification is real unless you explicitly confirm it.

Many apps (including WordPress plugins) consider an unverified email to be untrustworthy — and won’t create or authorize users if the claim is false.

---

✅ Step 1 — Create a Custom Scope Mapping for Email

Authentik’s default email scope sets:

"email_verified": False

We need to flip that.

In Authentik:

🔹 Go to:

Customizations → Property Mappings → Create

📌 Choose Scope Mapping

Fill the form:

Save.

This mapping ensures the email_verified claim is always sent back as a real boolean, which WordPress expects.

---

✅ Step 2 — Update the WordPress OIDC Provider

Now that you have a custom email mapping:

1. Go to:

Applications → Providers → (your WordPress provider)

2. Click Edit
3. Expand Advanced Protocol Settings
4. In Scopes, update like so:

5. Update the provider

---

✅ Step 3 — Verify Your Claims

The ID token now needs to contain:

{
  "email": "user@example.com",
  "email_verified": true,
  "preferred_username": "user@example.com"
}

If you’re unsure what is being returned:

• Log into Authentik Admin
• Navigate to the Events view
• Look for the token issuance event
• Decode the JWT (e.g. via jwt.io)

You can also enable token preview in the provider screens.

---

✅ Step 4 — Ensure WordPress Gets a Username

If WordPress reports:

Username not received. Check your Attribute Mapping configuration.

Then make sure the profile scope is included in the provider:

✔ openid
✔ profile
✔ your new email mapping

The profile scope (the default mapping) ensures you will get:

• preferred_username
• name
• other user profile claims

miniOrange needs username-like claims to create accounts.

---

💡 WordPress miniOrange Plugin SETTINGS

In the miniOrange plugin settings in WordPress:

OIDC / OAuth Configuration:

• Client ID and Client Secret: supplied from Authentik provider
• Redirect URL: must match Authentik’s configured redirect
• Scopes: openid profile email
• User Attribute Mapping:
  • Username → preferred_username
  • Email → email

This mapping works with the claims we’re sending.

---

✅ Test the Flow

1. Open a new private browser window
2. Start the login from WordPress
3. You should be redirected to Authentik
4. After login, WordPress should:
   • Accept the callback
   • Create the user if new
   • Log in the user automatically

---

🎯 Why the email_verified Change Matters

As documented in the Authentik 2025.10 release, the default mapping now deliberately sends:

"email_verified": false

That’s a security decision — but many apps block account creation if email isn’t verified.

By creating a custom scope mapping that returns true, you signal to WordPress that this email can be trusted.

If you want a conditional version (only true if Authentik truly verified the email via a flow), you can expand the mapping:

return {
    "email": request.user.email,
    "email_verified": bool(request.user.attributes.get("email_verified", False))
}

---

🧠 Summary Checklist

☑ Create Scope Mapping for email with email_verified: True
☑ Replace the default email mapping in your provider
☑ Ensure openid and profile scopes are selected
☑ Map preferred_username → Username in miniOrange
☑ Test login in private window

---

📌 References

• miniOrange error codes & fixes:
  https://faq.miniorange.com/knowledgebase/fix-wpo01-wpo02-wpo04-admin-sso-login-errors/
• Authentik default OAuth scope changes (2025.10)