From e4ce3ae25802471bea0ea99698fbb3f6ffdf7953 Mon Sep 17 00:00:00 2001 From: vman Date: Sun, 20 Nov 2022 15:27:58 -0500 Subject: Fix SocialOauth --- VNLib.Plugins.Essentials.SocialOauth/README.md | 45 ++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 VNLib.Plugins.Essentials.SocialOauth/README.md (limited to 'VNLib.Plugins.Essentials.SocialOauth/README.md') diff --git a/VNLib.Plugins.Essentials.SocialOauth/README.md b/VNLib.Plugins.Essentials.SocialOauth/README.md new file mode 100644 index 0000000..7a54c20 --- /dev/null +++ b/VNLib.Plugins.Essentials.SocialOauth/README.md @@ -0,0 +1,45 @@ +# VNLib.Plugins.Essentials.SocialOauth + +A basic external OAuth2 authentication plugin. + +## Plugin Mode + +This library exports an IPlugin type that may be loaded directly by a host application, or +imported to provide base classes for creating OAuth2 authentication endpoints. + +By default, exports 2 endpoints for Github and Discord authentication. Configuration +variables for either endpoint may be omitted or included to export endpoints. + +## Library Mode + +Exports SocialOAuthBase to provide a base class for creating OAuth2 authentication +endpoints, that is compatible with the VNLib web client library authentication flow + + +## Authentication Flow + +The authentication flow works similar to the local account mechanism with an extra step that helps +guard against replay, and MITM attacks. When an request claim is made (request to login) from client +side code (via put request), a browser id is request (for login flow) along with the clients encryption +public key (same key as Essentials.Accounts requires). The public key is used to encrypted a derived +redirect url, which includes a "secret" state token (OAuth2 standard state) that only the private-key +holder should be able to recover. When decrypted, should be used to redirect the client's browser to +the remote authentication server. Assuming the request is granted, the browser is redirected to the +originating endpoint, and the nonce is used to recover the initial claim and the flow continues. The +request should also include the required OAuth2 'code' parameter used to exchange for an access token. +If the access token is granted, a nonce is generated, passed to the browser via a redirect query parameter +which the browser code will use in a POST request to the endpoint to continue the flow. The nonce is +used to recover the access token and original claim data (public key, browser id, etc), which is used +to recover a user account, or optionally create a new account. Once complete, the user account is used +to upgrade the session and grant authorization to the client. The public key (and browser id) is used +from the initial claim to authorize the session, which should guard against MITM, replay, and forgery +attacks. However this only works if we assume the clients private key has not been stolen, which is a +much larger issue and should be addressed separately. + +## Diagram + +PUT -> { public_key, browser_id } -> server -> { result: "base64 encrypted redirect url"} -> + OAuth2Server -> redirect -> "?code=some_code&state=decrypted_state_token" + +GET -> "?code=some_code&state=decrypted_state_token" -> server -> "?result=authorized&nonce=some_nonce" +POST -> { nonce:"some_nonce" } -> server -> [authorization complete message] \ No newline at end of file -- cgit