Authentication¶

Lango supports OIDC (OpenID Connect) authentication for the gateway server. When configured, protected routes require a valid session cookie before granting access.

Auth Endpoints¶

Login Flow¶

sequenceDiagram
    participant Browser
    participant Lango as Lango Gateway
    participant IdP as OIDC Provider

    Browser->>Lango: GET /auth/login/google
    Lango->>Lango: Generate state, set oauth_state cookie
    Lango-->>Browser: 302 Redirect to IdP
    Browser->>IdP: Authorize
    IdP-->>Browser: 302 Redirect with code + state
    Browser->>Lango: GET /auth/callback/google?code=...&state=...
    Lango->>IdP: Exchange code for token
    IdP-->>Lango: ID Token + Access Token
    Lango->>Lango: Verify ID token, create session
    Lango-->>Browser: JSON {"status":"authenticated","sessionKey":"..."}

The callback returns a JSON response (not a redirect), making it suitable for both browser and programmatic clients:

{
  "status": "authenticated",
  "sessionKey": "sess_abc123..."
}

A lango_session cookie is also set automatically with HttpOnly, Secure (when HTTPS), and SameSite=Lax flags.

Logout¶

curl -X POST http://localhost:18789/auth/logout \
  -b "lango_session=sess_abc123..."

Returns:

{
  "status": "logged_out"
}

The session is deleted from the store and the cookie is cleared.

Protected Routes¶

When OIDC is configured, the following routes require a valid lango_session cookie:

Unauthenticated requests to protected routes receive:

{"error": "authentication required"}

with HTTP status 401 Unauthorized.

WebSocket CORS¶

The allowedOrigins setting controls which origins can establish WebSocket connections:

Settings: lango settings → Security

{
  "server": {
    "allowedOrigins": [
      "https://app.example.com",
      "https://admin.example.com"
    ]
  }
}

When no Origin header is present in the request (same-origin requests), the connection is always allowed regardless of configuration.

Rate Limiting¶

Auth endpoints are throttled to a maximum of 10 concurrent requests to prevent abuse. Excess requests are queued until a slot becomes available.

This applies to:

• /auth/login/{provider}
• /auth/callback/{provider}
• /auth/logout

Configuration¶

Single Provider¶

Settings: lango settings → Auth

{
  "auth": {
    "providers": {
      "google": {
        "issuerUrl": "https://accounts.google.com",
        "clientId": "your-client-id.apps.googleusercontent.com",
        "clientSecret": "your-client-secret",
        "redirectUrl": "https://your-domain.com/auth/callback/google",
        "scopes": [
          "openid",
          "email",
          "profile"
        ]
      }
    }
  }
}

Multiple Providers¶

Settings: lango settings → Auth

{
  "auth": {
    "providers": {
      "google": {
        "issuerUrl": "https://accounts.google.com",
        "clientId": "google-client-id",
        "clientSecret": "google-client-secret",
        "redirectUrl": "https://your-domain.com/auth/callback/google",
        "scopes": ["openid", "email", "profile"]
      },
      "github": {
        "issuerUrl": "https://token.actions.githubusercontent.com",
        "clientId": "github-client-id",
        "clientSecret": "github-client-secret",
        "redirectUrl": "https://your-domain.com/auth/callback/github",
        "scopes": ["openid", "email"]
      }
    }
  }
}

Each provider is registered under a unique name (e.g., google, github) which maps to the {provider} path parameter in auth endpoints.

Configuration Reference¶