zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
2.8 KiB
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 between web applications, 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 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.
!!! info
In this example we will use boku.tachi.ac as the Tachi site name.
- An OAuth2 client is created by user A.
This client will have the following properties.
{
"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"],
"apiKeyFormat": null, // These are for the Client File Flow.
"apiKeyFilename": null, // More on that later.
}
- 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 https://boku.tachi.ac/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-clientwill make a POST request tohttps://boku.tachi.ac/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 https://boku.tachi.ac/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.
The application I want to integrate isn't a web app!
That's fine. Infact, it's very common for us to integrate with applications that just want an API token inside a JSON file. For that, we have the Client File Flow