# HG changeset patch # User Matthew Wild # Date 1601468411 -3600 # Node ID 93b12bfd7aa8a80e6f79e9435b872be781c86155 # Parent b79904446d9e4489f71398731da3d4563b20a675 mod_auth_http: Yet another module to authenticate against a HTTP service diff -r b79904446d9e -r 93b12bfd7aa8 mod_auth_http/README.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_http/README.markdown Wed Sep 30 13:20:11 2020 +0100 @@ -0,0 +1,127 @@ +--- +labels: +- Stage-Alpha +summary: "Authenticate users against an external HTTP API" +... + +# Overview + +This authentication module allows Prosody to authenticate users against +an external HTTP service. + +# Configuration + +``` lua +VirtualHost "example.com" + authentication = "http" + http_auth_url = "http://example.com/auth" +``` + +If the API requires Prosody to authenticate, you can provide static +credentials using HTTP Basic authentication, like so: + +``` +http_auth_credentials = "prosody:secret-password" +``` + +# Developers + +This + +## Protocol + +Prosody will make a HTTP request to the configured API URL with an +appended `/METHOD` where `METHOD` is one of the methods described below. + +GET methods must expect a series of URL-encoded query parameters, while +POST requests will receive an URL-encoded form (i.e. +`application/x-www-form-urlencoded`). + +## Parameters + +user +: The username, e.g. `stephanie` for the JID `stephanie@example.com`. + +server +: The host part of the user's JID, e.g. `example.com` for the JID + `stephanie@example.com`. + +pass +: For methods that verify or set a user's password, the password will + be supplied in this parameter, otherwise it is not set. + +## Methods + +The only mandatory methods that the service must implement are `check_password` +and `user_exists`. Unsupported methods should return a HTTP status code +of `501 Not Implemented`, but other error codes will also be handled by +Prosody. + +### register + +**HTTP method:** +: POST + +**Success codes:** +: 201 + +**Error codes:** +: 409 (user exists) + +### check_password + +**HTTP method:** +: GET + +**Success codes:** +: 200 + +**Response:** +: A text string of `true` if the user exists, or `false` otherwise. + +### user_exists + +**HTTP method:** +: GET + +**Success codes:** +: 200 + +**Response:** +: A text string of `true` if the user exists, or `false` otherwise. + +### set_password + +**HTTP method:** +: POST + +**Success codes:** +: 200, 201, or 204 + +### remove_user + +**HTTP method:** +: POST + +**Success codes:** +: 200, 201 or 204 + +## Examples + +With the following configuration: + +``` +authentication = "http" +http_auth_url = "https://auth.example.net/api" + +If a user connects and tries to log in to Prosody as "romeo@example.net" +with the password "iheartjuliet", Prosody would make the following HTTP +request: + +``` +https://auth.example.net/api/check_password?user=romeo&server=example.net&pass=iheartjuliet +``` + +# Compatibility + +Requires Prosody 0.11.0 or later. diff -r b79904446d9e -r 93b12bfd7aa8 mod_auth_http/mod_auth_http.lua --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_auth_http/mod_auth_http.lua Wed Sep 30 13:20:11 2020 +0100 @@ -0,0 +1,122 @@ +-- Prosody IM +-- Copyright (C) 2008-2013 Matthew Wild +-- Copyright (C) 2008-2013 Waqas Hussain +-- Copyright (C) 2014 Kim Alvefur +-- +-- This project is MIT/X11 licensed. Please see the +-- COPYING file in the source package for more information. +-- + +local new_sasl = require "util.sasl".new; +local base64 = require "util.encodings".base64.encode; +local have_async, async = pcall(require, "util.async"); +local http = require "net.http"; + +if not have_async then + error("Your version of Prosody does not support async and is incompatible"); +end + +local host = module.host; + +local api_base = module:get_option_string("http_auth_url", ""):gsub("$host", host); +if api_base == "" then error("http_auth_url required") end +api_base = api_base:gsub("/$", ""); + +local auth_creds = module:get_option_string("http_auth_credentials"); + +local method_types = { + -- Unlisted methods default to GET + register = "POST"; + set_password = "POST"; + remove_user = "POST"; +}; + +local provider = {}; + +local function make_request(method_name, params) + local wait, done = async.waiter(); + + local method_type = method_types[method_name] or "GET"; + + params.server = params.server or host; + local encoded_params = http.formencode(params); + + local url; + local ex = { + method = method_type; + headers = { Authorization = auth_creds and ("Basic "..base64(auth_creds)) or nil; }; + } + if method_type == "POST" then + url = api_base.."/"..method_name; + ex.headers["Content-Type"] = "application/x/www-form-urlencoded"; + ex.body = encoded_params; + else + url = api_base.."/"..method_name.."?"..encoded_params; + end + + local content, code; + local function cb(content_, code_) + content, code = content_, code_; + done(); + end + http.request(url, ex, cb); + wait(); + return code, content; +end + +function provider.test_password(username, password) + local code, body = make_request("check_password", { user = username, pass = password }); + if code == 200 and body == "true" then + return true; + end + return false; +end + +function provider.users() + return function() + return nil; + end +end + +function provider.set_password(username, password) + local code = make_request("set_password", { user = username, pass = password }); + if code == 200 or code == 201 or code == 204 then + return true; + end + return false; +end + +function provider.user_exists(username) + local code, body = make_request("user_exists", { user = username }); + if code == 200 and body == "true" then + return true; + end + return false; +end + +function provider.create_user(username, password) + local code = make_request("register", { user = username, pass = password }); + if code == 201 then + return true; + end + return false; +end + +function provider.delete_user(username) + local code = make_request("remove_user", { user = username }); + if code == 200 or code == 201 or code == 204 then + return true; + end + return false; +end + +function provider.get_sasl_handler() + return new_sasl(host, { + --luacheck: ignore 212/sasl 212/realm + plain_test = function(sasl, username, password, realm) + return provider.test_password(username, password), true; + end; + }); +end + +module:provides("auth", provider);