Skip to main content

Introduction

AuthService is a self-hosted service that provides authentication and authorization for web app/dApp.

Getting Started​

Pre-requisites:

  • A subkey signed by your Avatar.
  • OAuth Apps applied for your Auth Service to verify your identity.
  • A server that your devices could access. Note that you don't really need a VPS, but an IP:PORT that browsers could redirect you to.

We're using Docker to simplify deployment. You can also run it without Docker, but you'll need to compile the binary yourself.

Subkey​

Subkey is a key pair signed by your Avatar. It is meant to be used for authentication purposes without saving your primary Avatar key pair on server, which is a dangerous action. Now we support Secp256k1 key pair only, but more curves will be supported in the future.

Run the following command with generate_subkey.py to generate a new subkey and sign it with your Avatar private key:

pip install base58 eth_keys # skip if installed
python ./build/generate_subkey.py

Subkey is randomly generated so that you can regenerate and use a new subkey at any time.

OAuth Apps​

Currently supported OAuth apps:

Take Discord as an example, you need to apply for an OAuth App to get a CLIENT_ID and CLIENT_SECRET. You can find the guide here.

Callback URL/Redirect URL is the URL that your browser will be redirected to in order to continue AuthService authentication process. It should be your AuthServer's address, suffixed with /signin-${platform}, e.g. https://localhost:5050/signin-discord.

Configuration​

Once you have your subkey signed and OAuth applications, you can start to configure your AuthServer.

Configure appsettings.Production.json with your secrets as following:

{
  "Avatars": [
    {
      "Avatar": "0x1145141919810...",
      "Subkey": {
        "PrivateKey": "0xbadbadbad...",
        "CertificationSignature": "aBcDEFGHij123456..."
      }
    }
  ],
  "Discord": {
    "ClientID": "123456789012345678",
    "ClientSecret": "123456789012345678"
  },
  "Twitter": {
    "ClientID": "aBcDEFG...",
    "ClientSecret": "Hij123456..."
  }
  // ...
}

Note that AuthServer supports multiple Avatars, so you can add more Avatars to the Avatars array.

Deployment​

Firstly, you need to build the Docker image:

docker build -t authserver -f ./src/AuthServer.Server/Dockerfile .

Run the following command to run it once, replace /path/to/appsettings.Production.json with your own configuration file path.

docker run --rm -p 80:80 -v /path/to/appsettings.Production.json:/app/appsettings.Production.json authserver