auth-server

auth-server

Serving authentication and OAuth2 authorization

It is based on the following libraries.

• go-oauth2/oauth2.
• golang-jwt/jwt
• spf13/viper
• gin-gonic/gin
• go-webauthn/webauthn
• resendlabs/resend-go

⚠ This is a work in progress and not ready for production yet ⚠

Setting up server

Users with administrative privileges can be seeded by starting this server with an empty database (technically empty database table users). The server will read the file configured via environment variable AUTH_SEED_USERS_FILE_PATH.

The file is in JSON format and the schema can be found in ImportUser. The following is an example of content of the file.

[
  {
    "email": "user@test.com",
    "password": "password",
    "display_name": "Test User",
    "roles": ["admin"]
  }
]

Note that setting of role admin is important to allow the user to act as an administrator to configure other aspects (such as OAuth clients) of this server.

Development setup

Prerequisite

go install github.com/swaggo/swag/cmd/swag@latest

Using localhost

Using localhost is not recommended as it is hard, if not impossible, do test the workflow of webauthn and some of the OIDC providers.

Using MagicDNS of Tailscale and Caddy

Assuming the domain is node-name.some-name.ts.net.

Set environment variable AUTH_DOMAIN to node-name.some-name.ts.net.

To setup the API and its databases

task up-db
task run

Assuming Caddyfile like the following has been prepared.

node-name.some-name.ts.net

reverse_proxy :8080

To start reverse proxy from the MagicDNS domain name from Tailscale to port 8080.

task caddy

To create user and OAuth client

task test-client-create

To test sign-in and access token retrieval

task test-step-domain

or

task test-login
task test-password
task test-token

To test WebAuthn (FIDO2) registration

1. Sign-in using password via https://mac14.husky-bee.ts.net/
2. Once authenticated, press button Register key via https://mac14.husky-bee.ts.net/authenticated/

To test login via OIDC provider

1. Ensure environment variable AUTH_ENABLE_OIDC is set to true.
2. Setup a OIDC provider via POST /oidcclients (currently only google is supported).

Webauthn (FIDO2)

Encoding

This server implementation uses base64url encoding. As a result, front-end has to convert standard base64 encoding to the encoding.

Default authenticator selection

"authenticatorSelection": {
  "authenticatorAttachment": "cross-platform",
  "requireResidentKey": false,
  "residentKey": "discouraged",
  "userVerification": "required"
}

References

• Sign-in form best practices
• Sign-up form best practices
• Well-known URL for changing passwords
• 13 best practices for user account, authentication, and password management
• RFC 6749 The OAuth 2.0 Authorization Framework
• RFC 8414 OAuth 2.0 Authorization Server Metadata
• RFC 7636 Proof Key for Code Exchange by OAuth Public Clients
• RFC 8693 OAuth 2.0 Token Exchange
  • An explanation from Scott Brady in Delegation Patterns for OAuth 2.0 using Token Exchange
  • example implementation in .NET from RockSolidKnowledge/TokenExchange
    • sample
• RFC 7522 Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants
• RFC 7033 WebFinger
• bcrypt
• swaggo/swag
• swaggo/gin-swagger