From ed4cfb4d3f9606f6b0c469f896298628a35341da Mon Sep 17 00:00:00 2001 From: zkldi Date: Fri, 3 Sep 2021 12:07:02 +0100 Subject: [PATCH] Describe our OAuth2 Flow --- docs/docs/api/routes/oauth2-clients.md | 2 +- docs/docs/api/routes/oauth2.md | 2 +- docs/docs/codebase/infrastructure/oauth2.md | 48 +++++++++++++++++++++ docs/mkdocs.yml | 2 + 4 files changed, 52 insertions(+), 2 deletions(-) create mode 100644 docs/docs/codebase/infrastructure/oauth2.md diff --git a/docs/docs/api/routes/oauth2-clients.md b/docs/docs/api/routes/oauth2-clients.md index bd03cda5a..0a1944a93 100644 --- a/docs/docs/api/routes/oauth2-clients.md +++ b/docs/docs/api/routes/oauth2-clients.md @@ -2,7 +2,7 @@ These endpoints relate to managing your OAuth2 clients, such as creating new ones or deleting them. -For a detailed explaination on how to use the OAuth2 flow, you can check [Using OAuth2 With Tachi](../../codebase/batch-manual/oauth2.md) +For a detailed explaination on how to use the OAuth2 flow, you can check [Using OAuth2 With Tachi](../../codebase/infrastructure/oauth2.md) ***** diff --git a/docs/docs/api/routes/oauth2.md b/docs/docs/api/routes/oauth2.md index 524d33697..779e00787 100644 --- a/docs/docs/api/routes/oauth2.md +++ b/docs/docs/api/routes/oauth2.md @@ -4,7 +4,7 @@ Tachi provides an OAuth2 API and some other things so that you can create your own clients and retrieve user api keys safely. -For a detailed explaination on how to use the OAuth2 flow, you can check [Using OAuth2 With Tachi](../../codebase/batch-manual/oauth2.md) +For a detailed explaination on how to use the OAuth2 flow, you can check [Using OAuth2 With Tachi](../../codebase/infrastructure/oauth2.md) ***** diff --git a/docs/docs/codebase/infrastructure/oauth2.md b/docs/docs/codebase/infrastructure/oauth2.md new file mode 100644 index 000000000..483e0661b --- /dev/null +++ b/docs/docs/codebase/infrastructure/oauth2.md @@ -0,0 +1,48 @@ +# OAuth2 Flow + +`tachi-server` has a functional implementation of OAuth2, which lets people create clients to request APIKeys from users. + +This is the preferred way of handling authorisation, as it can be done without the user ever really having to deal with their API keys! + +!!! note + The below steps assume some familiarity with OAuth2. If you are not familiar, I find [this](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2) to be the best explaination. + +We use an *almost* standard OAuth2 flow, but with the added react-app caveat of POSTing for an intermediate token. If that makes sense to you, you don't need to read this page! + +## Process + +In this scenario, we have two users, user A, who is making a service that integrates with Tachi, and user B, who wants to link integrate their service with their tachi profile. + +- An OAuth2 client is created by user A. + +This client will have the following properties. + +```json +{ + "clientID": "ABCDEF", // this is a random string in practice. + "clientSecret": "GHIJKL", // this is another random string. + "name": "Epic Games", + "author": 1, + "redirectUri": "https://epicgames.example.com/tachi-auth-callback", + "requestedPermissions": ["customise_score"] +} +``` + +- User B wants to link their account to this service, and must click on an auth link on Tachi. + +In the `tachi-client`, this link is `/oauth/request-auth?clientID={clientID}` + +EpicGames would show this link to the user, and they would click it. + +While on Tachi, they are presented with the option to accept linking with `clientID`, or decline it. + +- If they accept, `tachi-client` will make a POST request to `/api/v1/oauth/create-code`, which will create an intermediate authorisation code. + +The user and this authorisation code are then taken to the `redirectUri` defined in the client. In our case, this means they are taken to +`https://epicgames.example.com/tachi-auth-callback?code=SOME_INTERMEDIATE_TOKEN` + +This token **IS NOT** an API Key, but rather an intermediate value that needs to then be converted up. + +EpicGames would now have to take this token and make a POST request to tachi's `/api/v1/oauth/token`, with their client secret and the intermediate token. + +This POST request will then return the API Key EpicGames wants! The user can then be redirected by EpicGames to wherever they want. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 640de657f..1bffb525f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -59,6 +59,7 @@ nav: - "api/routes/games.md" - "api/routes/gpt.md" - "api/routes/admin.md" + - "api/routes/ugpt-showcase.md" - "api/routes/oauth2.md" - "api/routes/oauth2-clients.md" @@ -75,6 +76,7 @@ nav: - "codebase/infrastructure/logging.md" - "codebase/infrastructure/branches.md" - "codebase/infrastructure/versions.md" + - "codebase/infrastructure/oauth2.md" - Structure: - "codebase/structure/style.md"