magicauth

README

Magicauth

output.webm

Magicauth is a lightweight OpenID Connect server that leverages Tailscale identity for seamless authentication. It's designed for self-hosted applications, eliminating the need for complex OpenID Connect provider setups.

Features

• Zero-interaction authentication for users connected to your Tailnet
• Minimal OpenID Connect implementation compatible with most self-hosted apps
• No external dependencies besides Tailscale
• Easy configuration via YAML, TOML, JSON, or environment variables
• Optional Kubernetes integration for managing OAuth clients

How It Works

Magicauth utilizes the special identity headers set by Tailscale Serve/Funnel:

1. When a user makes a request, Tailscale adds identity headers (e.g., Tailscale-User-Login, Tailscale-User-Name)
2. Magicauth checks the Tailscale-User-Login header to authenticate the user
3. If the user is authenticated, Magicauth handles the OpenID Connect flow

This approach provides automatic authentication for users within your Tailnet without additional login steps.

For more information, see the Magicauth blog post.

Installation

Docker

Use the Docker image provided here.

Configuration

Magicauth can be configured using:

• YAML, TOML, or JSON files, e.g.:

base_url: http://localhost:8080
global_secret: redacted
clients:
  outline:
    audience:
      - https://outline.qilin-qilin.ts.net
    public: false
    client_secret: redacted
    redirect_uris:
      - https://outline.qilin-qilin.ts.net/auth/oidc.callback
    response_types:
      - "id_token"
      - "code"
      - "token"
      - "id_token token"
      - "code id_token"
      - "code token"
      - "code id_token token"
    grant_types:
      - "implicit"
      - "refresh_token"
      - "authorization_code"
      - "password"
      - "client_credentials"
    scopes:
      - "openid"

• Environment variables:

MAGICAUTH_BASE_URL="http://localhost:8080"
MAGICAUTH_GLOBAL_SECRET="redacted"
MAGICAUTH_CLIENTS__OUTLINE__AUDIENCE="https://outline.qilin-qilin.ts.net"
MAGICAUTH_CLIENTS__OUTLINE__PUBLIC="false"
MAGICAUTH_CLIENTS__OUTLINE__CLIENT_SECRET="redacted"
MAGICAUTH_CLIENTS__OUTLINE__REDIRECT_URIS="https://outline.qilin-qilin.ts.net/auth/oidc.callback"
MAGICAUTH_CLIENTS__OUTLINE__RESPONSE_TYPES="id_token,code,..."
MAGICAUTH_CLIENTS__OUTLINE__GRANT_TYPES="implicit,refresh_token,..."
MAGICAUTH_CLIENTS__OUTLINE__SCOPES="openid"

• Kubernetes resources

Kubernetes Integration

To enable Kubernetes integration for managing OAuth clients:

1. Enable the Kubernetes controller by either:

• Setting enable_k8s to true in the configuration file
• Setting the MAGICAUTH_ENABLE_K8S environment variable to true

1. Install the CRDs provided here

Now you can create OAuth clients using Kubernetes resources. For example:

apiVersion: magicauth.invak.id/v1
kind: OAuthClient
metadata:
  name: outline
spec:
  audience:
    - https://outline.qilin-qilin.ts.net
  public: false
  clientSecret: redacted
  redirectUris:
    - https://outline.qilin-qilin.ts.net/auth/oidc.callback
  responseTypes: ...
  grantTypes: ...
  scopes: ...

Acknowledgements

• Ory Fosite for the OpenID Connect implementation and reference code