--- /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

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_auth_oauth_external/mod_auth_oauth_external.lua	Thu Mar 16 12:45:22 2023 +0100
@@ -0,0 +1,55 @@
+local http = require "net.http";
+local async = require "util.async";
+local json = require "util.json";
+local sasl = require "util.sasl";
+
+-- TODO -- local issuer_identity = module:get_option_string("oauth_external_issuer");
+local oidc_discovery_url = module:get_option_string("oauth_external_discovery_url")
+local validation_endpoint = module:get_option_string("oauth_external_validation_endpoint");
+
+local username_field = module:get_option_string("oauth_external_username_field", "preferred_username");
+
+-- XXX Hold up, does whatever done here even need any of these things? Are we
+-- the OAuth client? Is the XMPP client the OAuth client? What are we???
+-- TODO -- local client_id = module:get_option_string("oauth_external_client_id");
+-- TODO -- local client_secret = module:get_option_string("oauth_external_client_secret");
+
+--[[ More or less required endpoints
+digraph "oauth endpoints" {
+issuer -> discovery -> { registration validation }
+registration -> { client_id client_secret }
+{ client_id client_secret validation } -> required
+}
+--]]
+
+local host = module.host;
+local provider = {};
+
+function provider.get_sasl_handler()
+	local profile = {};
+	profile.http_client = http.default; -- TODO configurable
+	local extra = { oidc_discovery_url = oidc_discovery_url };
+	function profile:oauthbearer(token)
+		if token == "" then
+			return false, nil, extra;
+		end
+
+		local ret, err = async.wait_for(self.profile.http_client:request(validation_endpoint,
+			{ headers = { ["Authorization"] = "Bearer " .. token; ["Accept"] = "application/json" } }));
+		if err then
+			return false, nil, extra;
+		end
+		local response = ret and json.decode(ret.body);
+		if not (ret.code >= 200 and ret.code < 300) then
+			return false, nil, response or extra;
+		end
+		if type(response) ~= "table" or type(response[username_field]) ~= "string" then
+			return false, nil, nil;
+		end
+
+		return response[username_field], true, response;
+	end
+	return sasl.new(host, profile);
+end
+
+module:provides("auth", provider);