The bundled Facebook driver hard-codes v12.0 authorization, token, and Graph
profile endpoints. Its configuration overwrites the authorization/token URLs;
changing base_auth_url does not upgrade those calls. This page preserves the
integration reference, but it does not establish compatibility with Meta's
current Graph API. Verify support with Meta before relying on it for a new
production deployment. A parser check cannot resolve this upstream limitation.
Application and callback reference
For a compatible deployment, register a server-side Facebook Login application in the Meta developer dashboard, keep its App Secret on the server, and use the exact authorized redirect:
https://auth.example.com/auth/oauth2/facebook/authorization-code-callback
The App Secret is the confidential OAuth credential. A Client Token or browser
SDK app identifier is not a substitute. The named driver calculates an
appsecret_proof for the Graph profile request. Consult
Meta's web login guide
and API version policy
for current application, permission, and version requirements. The old wizard's
app-type labels are historical.
Preserved Facebook setup and consent screens
Released configuration reference
# caddy-security v1.3.0 / go-authcrunch v1.3.8. Replace auth.example.com.
{
admin off
persist_config off
security {
oauth identity provider facebook {
realm facebook
driver facebook
client_id {env.FACEBOOK_CLIENT_ID}
client_secret {env.FACEBOOK_CLIENT_SECRET}
scopes email
}
authentication portal myportal {
enable identity provider facebook
crypto default token lifetime 900
crypto key sign-verify {env.AUTHCRUNCH_SIGNING_KEY}
ui {
links {
"Example app" /app
"My identity" /auth/whoami
}
}
transform user {
match realm facebook
action overwrite role authp/user
}
transform user {
match realm facebook
match sub {$FACEBOOK_ALLOWED_SUB}
action add role app/member
}
}
authorization policy apppolicy {
set auth url https://auth.example.com/auth/
crypto key verify {env.AUTHCRUNCH_SIGNING_KEY}
validate bearer header
allow roles app/member
}
}
}
auth.example.com {
route {
redir /auth /auth/ 308
authenticate /auth/* with myportal
@app path /app /app/*
route @app {
authorize with apppolicy
respond "You reached the protected example app." 200
}
respond "Open /app to begin." 200
}
}
Replace the client values and private signing key in the server environment.
FACEBOOK_ALLOWED_SUB expands at parse time and must be the exact app-scoped
account ID returned by this integration. The example resets provider roles and
grants app/member only to that subject. It does not grant portal administration
by email or allow every Facebook identity into the application.
Facebook access tokens are opaque to this driver; it retrieves the profile through the provider rather than treating them as signed OIDC ID tokens. PKCE and nonce are disabled for this named driver. Email can be absent even when requested, so decide explicitly whether the application's subject-based identity permits disabling the default email claim check.
Treat each compatibility stage as separate evidence
The preserved Facebook setup and accepted driver configuration do not prove a completed login against today’s platform.
| Stage | Evidence to collect | What remains unproven |
|---|---|---|
| Caddyfile adaptation | Installed parser accepts the declaration | Current Facebook app/product support |
| Authorization redirect | Correct client, public callback, and requested scopes | An accepted token response |
| Token and identity processing | Required fields and driver identity consumer match the response | Application membership |
| Portal and protected app | Fresh login plus allowed and denied users | Compatibility of another app or driver version |
Compatibility verification
Before deployment, test code exchange, Graph profile retrieval, application assignment/permissions, exact subject mapping, and a nonmember's rejection. If a retired endpoint or provider permission blocks the flow, a Caddyfile rewrite is not evidence of a repaired upstream implementation. Use another documented provider that meets your deployment requirements.
Agentic Prompts
Copy a prompt into your LLM to explore this topic. Each prompt prioritizes upstream repository guidance and code over this page, and asks for version-aware reasoning.
Inspect compatibility before setup
Help me understand Facebook.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0008-facebook
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Audit the installed Facebook driver’s hard-coded API versions and endpoint
override behavior. Compare them with current official Meta support policy
before proposing a deployment. Explain why parsing or an authorization
redirect is not evidence of successful modern profile retrieval.
Distinguish Facebook credentials
Help me understand Facebook.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0008-facebook
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Explain App ID, confidential App Secret, Client Token, and user access token
in this named driver. Trace appsecret_proof and profile lookup. Use fake
values and keep real secrets out of browser code, screenshots, and logs.
Compare identity trust models
Help me understand Facebook.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0008-facebook
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Explain this driver’s opaque-token/profile path versus generic OIDC signed
identity tokens. Inspect actual PKCE, nonce, state, and email behavior for my
release. Do not invent an ID token or automatically weaken a different driver
to match Facebook defaults.
Diagnose without inventing compatibility
Help me understand Facebook.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0008-facebook
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Help me classify unsupported API version, callback registration,
permission/app-review restrictions, profile error, absent email, and app-role
denial. Ask for redacted response metadata and consult official Meta
requirements. Leave unsupported behavior explicitly unresolved.
Design a compatibility gate
Help me understand Facebook.
Primary authorities (take precedence over website documentation):
https://github.com/greenpau/caddy-security/blob/main/AGENTS.md
https://github.com/greenpau/caddy-security/tree/main/.codex/skills
https://github.com/greenpau/go-authcrunch/blob/main/AGENTS.md
https://github.com/greenpau/go-authcrunch/tree/main/.codex/skills
Read each repository's root AGENTS.md first, then any scoped AGENTS.md that
applies to inspected paths. Read the relevant SKILL.md files and follow their
implementation and test references.
Relevant skills to locate: configuration-oauth-providers,
oauth-identity-provider.
Secondary reference:
https://docs.authcrunch.com/docs/authenticate/oauth/backend-oauth2-0008-facebook
If a source is inaccessible, ask me to paste its relevant text. Identify the
versions your answer applies to; main may be newer than my release. Resolve
disagreements using code and tests, and flag unverified claims. Use synthetic
credentials and redacted examples; explain proposed checks before any changes.
Create a go/no-go checklist that requires live profile retrieval and
member/nonmember access, not only adaptation. Include secret handling,
missing-email policy, exact subject mapping, and logout/session limits.
Explain which upstream change would be needed if the named driver’s endpoints
are obsolete.
Source Code References
Start with the code search, then follow the parser, runtime, and tests relevant
to this topic. These links target main; use GitHub's branch/tag selector to
compare them with your installed release.
- Search this topic in both repositories — searches topic-specific symbols and paths across both codebases.
- caddy-security: caddyfile_identity_provider_oauth.go — adapts OAuth/OIDC provider settings, scopes, endpoints, and trust options.
- go-authcrunch: pkg/idp/oauth/config.go — validates generic and named-driver defaults and endpoint settings.
- go-authcrunch: pkg/idp/oauth/user.go — fetches and normalizes named-provider profile, membership, and identity data.
- go-authcrunch: pkg/idp/oauth/authenticate.go — handles authorization callbacks, token exchange, and identity completion.
- go-authcrunch: pkg/idp/oauth/config_test.go — tests generic/named provider configuration and validation.