💃 Tango

Copy Markdown View Source

Hex.pm Hex Docs License

OAuth integrations for Phoenix — sessions, encrypted tokens, and multi-tenant connections.

Tango is an Elixir library for third-party OAuth in Phoenix apps. It is compatible with Nango's provider catalog and stores tokens encrypted in Postgres via your host Ecto repo.

Why Tango?

  • OAuth2 authorization code flow with PKCE, CSRF state, and tenant isolation
  • Encrypted tokens (AES-GCM) plus structured audit logging
  • Credential-free browser callback (0.2.0) — completion handle only; verify and finalize on your server
  • Optional LiveView component and mountable OAuth API router
  • Nango-compatible providers from catalog or custom config (the catalog's OAuth2 authorization-code entries; see PROVIDERS.md)

Further reading

  • SETUP.md — config options, upgrades, non-Ecto installs
  • PROVIDERS.md — catalog mix tasks and programmatic providers
  • USAGE.md — direct server-side OAuth and connection usage
  • AUTHORIZATION.md — browser popup completion (0.2.0)
  • API.md — mountable HTTP router and JavaScript examples

Prerequisites

  • Elixir 1.15+
  • PostgreSQL
  • An Ecto SQL repo

Installation

Add tango to your dependencies in mix.exs:

def deps do
  [
    {:tango, "~> 0.2.0"}
  ]
end

Then fetch dependencies:

mix deps.get

Quick Start

1. Configure

# config/config.exs
config :tango,
  repo: MyApp.Repo,
  encryption_key: System.get_env("TANGO_ENCRYPTION_KEY"),
  api_key: System.get_env("TANGO_API_KEY")

Generate an encryption key:

openssl rand -base64 32

2. Install the schema

mix tango.setup writes a host-owned wrapper migration; mix ecto.migrate applies it. Use setup for the initial install only — upgrades need a separate pinned migration (see SETUP.md).

mix tango.setup
mix ecto.migrate

3. Create a provider

mix tango.providers.create github \
  --client-id=your_client_id \
  --client-secret=your_client_secret

4. Run a direct OAuth flow

tenant_id = "user-123"
redirect_uri = "https://yourapp.com/auth/callback"

{:ok, session} =
  Tango.create_session("github", tenant_id,
    redirect_uri: redirect_uri,
    scopes: ["user:email", "repo"]
  )

{:ok, auth_url} =
  Tango.authorize_url(session.session_token, redirect_uri: redirect_uri)

# Redirect the user to auth_url. After the provider returns state + code:

{:ok, connection} =
  Tango.exchange_code(state, code, tenant_id, redirect_uri: redirect_uri)

{:ok, connection} = Tango.get_connection_for_provider("github", tenant_id)
headers = [{"Authorization", "Bearer #{connection.access_token}"}]

For browser popups (credential-free completion handle), see AUTHORIZATION.md. More connection helpers: USAGE.md. Mount the HTTP API: API.md.

Testing

Requires local PostgreSQL with postgres:postgres credentials.

mix test
mix coveralls
mix quality

License

See LICENSE.