Takagi enables you to use GitHub as an OpenID Connect (OIDC) provider. With it, you can use GitHub to identify your application's users without needing to implement specific support for GitHub's OAuth2 API.

Takagi is a sister project to Snowflake, which does the same thing but for Discord. You should check that out, too.

Docker is the only supported way of running Takagi. You will almost always want to set the TAKAGI_ALLOWED_HOSTS environment variable; see Configuration.

After installing Takagi, I recommend taking a look at the interactive API documentation at https://takagi.example.com/docs.

services:
  takagi:
    image: ghcr.io/celsiusnarhwal/takagi:latest
    container_name: takagi
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - TAKAGI_ALLOWED_HOSTS=takagi.example.com
    volumes:
      - /some/directory/on/your/machine:/app/takagi/data

docker run --name takagi \
--restart unless-stopped \
-p "8000:8000" \
-e "TAKAGI_ALLOWED_HOSTS=takagi.example.com"
-v "/some/directory/on/your/machine:/app/takagi/data" \
ghcr.io/celsiusnarhwal/takagi:latest

First, create an OAuth application in your GitHub developer settings. Put in whatever you want for the application name and homepage URL.

For the authorization callback URL, you must set it to https://takagi.example.com/r/{YOUR_REDIRECT_URI}, where {YOUR_REDIRECT_URI} is the actual intended redirect URI for your application. For example, a redirect URI of https://myapp.example.com/callback would be set as as https://takagi.example.com/r/https://myapp.example.com/callback.

From there, Takagi works just like any other OIDC provider. Your app redirects to Takagi for authorization; upon succcessful authorization, Takagi provides your app with an authorization code, which your app returns to Takagi in exchange for an access token and an ID token. The access token can be sent to Takagi's /userinfo endpoint to obtain the associated identity claims, or your application can decode the ID token directly to obtain the same claims.

Frankly, if you're reading this then you should already know how this works.

Depending on the provided scopes, Takagi-issued ID tokens include some subset of the following claims:

Takagi-issued access tokens include the following claims:

The /userinfo endpoint returns the same claims as ID tokens but does not include iss, aud, iat, exp, or nonce.

Takagi provides a WebFinger endpoint at /.well-known/webfinger to enable the discovery of Takagi as the OIDC provider for email addresses at domains permitted by the TAKAGI_ALLOWED_WEBFINGER_HOSTS environment variable (see Configuration). The endpoint only supports acct: URIs containing email addresses and does not support any link relations other than OpenID Connnect.

The endpoint will return an HTTP 404 error for email addresses at non-whitelisted domains.

As previously mentioned, Takagi requires HTTPS for external connections. If you're serving Takagi behind a reverse proxy and connecting to the reverse proxy over HTTPS, you will likely need to configure Uvicorn — which Takagi uses under the hood — to trust the IP address of your reverse proxy.

You can do this by setting the UVICORN_FORWARDED_ALLOW_IPS environment variable to a comma-separated list of IP addresses or networks, at least one of which must match the IP of your reverse proxy. You can also set it to * to trust all IP addresses, but this is generally not recommended.

For more information, see Uvicorn's documentation.

By default, Takagi writes its private keys to /app/takagi/data, which you are instructed to mount on your host machine (see Installation). As an alternative to this, Takagi allows you to provide keys externally.

First, you'll need to generate a suitable private key³ using the following command:⁴

docker exec takagi keygen

Or, if you don't have a running Takagi instance:

docker run ghcr.io/celsiusnarhwal/takagi keygen

Second, you'll need to provide the key to Takagi in one of two ways:

1. As the value of the TAKAGI_KEYSET environment variable. This may be useful in serverless enviroments where mounting /app/takagi isn't possible.
2. As a file mounted into Takagi's container whose path is provided via TAKAGI_KEYSET. This file cannot be located within /app/takagi. This allows for compatibility with Docker secrets.

// For demonstration purposes only, do not actually use this keyset. Obviously.

{
  "keys": [
    {
      "n": "1PZYs3MrRkF83qVCoZ1qEJ3doCWaOflTVaZNceqYx4F1m_p_prUlzpBlsIky0q45e4ov3hehSh3FkvlnXLzYrD_Ewgwjy7xwIEhR7zyUUYMlUSCdb0Bq8mFRVG0zPYOSAY3CFkadnH0vwroJJcnc_mmAssfu6eUaIB7kfnqFx2RI3jXzi-runGrki8Y2yVAjovlgulX04Y0GD60kt1-vwva8Goci8Rij0IIna4GyKjYwxzKrOvMqI9_td7JJItF4QiDMd_SSjf8p6TenaWG26gb0vWhkzR6zWs-lVxMJYFkhnrGRk9urq6Zk4r_mmez7NPIyYAS5GWUW_Of7c-_h6w",
      "e": "AQAB",
      "d": "DK-gGRCDQ2wjRCAUGAyIhPTifue-iDWSAUgm1OJkt32-w8voTsX7upJffGSv4lz-j51rvI8rzH55hofU4HFfduNVlTmj6D8RbtrgBqBVNYXaczq-JiJwPIAPmDfpFYEA8ZbAORN70BalAbSTVuzvfThLslq2oLhFFiTA98fUsEvtN0O_FwNgvzJGfwvVGEmP6grYjqQr0NSqpD3tj2fq2AC5531ri1fjPyDE9wvQM4_EkZ0eOHtJW7ztfimiv_pgz1B_V6p26_FMhzhKkBepyMIewGPY4mzP-v4zlQILL6uYP9IbOZf1bCGjgcPF5lxQkL9Hjq1z0bRrpQgkoowAAQ",
      "p": "79NHLDfiFlo-lml4yVRVrRbrFZknbO506NdB-JKNcs1H7uYf_UTiY0E-oScvTZdgti0lxWh8syUCmXhkqLykrGgHG1M7uSmGACki35_diG5VTyIJuO4g92lLjw6d0slBcqaLZyeWctC_gU8F262HX97BombfIM6Nb2pWQ7zAQ-s",
      "q": "41NDWHVyTZkOjgwd8WIuYmBVd59MRYXyo_sBFkku8WyH21q-B7iTuMFcb7i61e0Qv8HPAchljqqEl3d91DpMOFTEy-MHoV2jn7_D4Grxsqb6mNomdOcC0oN4o7ZAvdJzffVfJXWBFwNbXyg7o3Byyr4Rl3OSi8HonYKVR80tWgE",
      "dp": "7SK6Q2zWb0e4jz2nI1vyg34f4XFY3ItEql7-am1u089Li1uc0e_k8kO3S93VFiHSjRBDQtk4RGMaGOpEjdxJ7_fE3y4D5ei7CTmjs_79LEP8soxzlJpRmpJRFhlb0OsTfexT9yHbz5e9ZHzgzADf1NoMGSsjAet7SmmY9s2SRxU",
      "dq": "2XJO7DHD-agbvRKoHbqdxeqCNp_BFIuxctvpyUiNx8_aEKA3QCl13HfRlOiuh21x5QtdmUX4p0RC-qQJT9XIDOZBLQpoxRlOJ8QGeQezVQHWmhmqSY6kK3wpDOiL-0dwxB7POYSxy7KhV1-j1I3-sCKpryaVGmyMtwYvB3SjGgE",
      "qi": "gYDgAbG3OHiQzLF76WuVfOoS2yUc_wJEExTvAYaRZ-yPEQBk4b3J5rYZUmxGJUMVzrNBEfMKR0bXwFB76JR53jD_NEOBUseTd4E4YldX_CMrw2XaopE4ftuR-5EklaOP2jP6Zqr3QQpqKpO9G-nC8ZQY5Gz4DWEtz4v0gUvvV_I",
      "use": "sig",
      "alg": "RS256",
      "kty": "RSA",
      "kid": "D-byh_ZgjoJOOho7vui-P_7WENzRKxgUAgiHZJOcHig"
    },
    {
      "k": "9AY2hzl0Sje9Zwv_XNHuz1BdEESmkVplMvap4KGfIeI",
      "use": "enc",
      "alg": "A256GCM",
      "kty": "oct",
      "kid": "GtMvEe77qYhPK6sOkWjuU9Yynzv-u8WYLCdwXN-qkGA"
    }
  ]
}

If TAKAGI_KEYSET is set, there's no need to mount /app/takagi/data. On startup, Takagi will log a message affirming that a custom private keyset is in use.

If you think Takagi's private keys have been compromised, you can rotate them with the following command:⁴

docker exec takagi rotate

This only has any effect if Takagi is managing its own keys. If you're using custom private keys, you'll have to change them manually.

Takagi is configurable through the following environment variables (all optional):

Uvicorn will respect most⁷ of its own environment variables if they are set, but UVICORN_FORWARDED_ALLOW_IPS is the only one supported by Takagi. Please don't open an issue if you set any of the others and something breaks.