--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_auth_oauth_external/README.md	Thu Mar 16 12:45:22 2023 +0100
@@ -0,0 +1,44 @@
+---
+summary: Authenticate against an external OAuth 2 IdP
+labels:
+- Stage-Alpha
+---
+
+This module provides external authentication via an external [AOuth
+2](https://datatracker.ietf.org/doc/html/rfc7628) authorization server
+and supports the [SASL OAUTHBEARER authentication][rfc7628]
+mechanism.
+
+# How it works
+
+Clients retrieve tokens somehow, then show them to Prosody, which asks
+the Authorization server to validate them, returning info about the user
+back to Prosody.
+
+# Configuration
+
+`oauth_external_discovery_url`
+:   Optional URL string pointing to [OAuth 2.0 Authorization Server
+    Metadata](https://oauth.net/2/authorization-server-metadata/). Lets
+    clients discover where they should retrieve access tokens from if
+    they don't have one yet.
+
+`oauth_external_validation_endpoint`
+:   URL string. The token validation endpoint, should validate the token
+    and return a JSON structure containing the username of the user
+    logging in the field specified by `oauth_external_username_field`.
+    Commonly the [OpenID `UserInfo`
+    endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
+
+`oauth_external_username_field`
+:   String. Default is `"preferred_username"`. Field in the JSON
+    structure returned by the validation endpoint that contains the XMPP
+    localpart.
+
+# Compatibility
+
+  Version   Status
+  --------- ---------------
+  trunk     works
+  0.12.x    does not work
+  0.11.x    does not work