Authentication

Configure OAuth providers and session settings for the Optio web UI.

Optio authenticates users through OAuth. When a user visits the web UI, they are redirected to an OAuth provider to log in. After a successful login, Optio creates a session that lasts 30 days.

At least one OAuth provider must be configured before anyone can log in. The setup wizard walks through this on first install.

How providers are enabled

A provider becomes available on the login page as soon as both its client ID and client secret are set. You can enable multiple providers simultaneously — users can choose between them at login.

Set credentials via Helm values or directly as environment variables:

values.yaml

auth:
  github:
    clientId: "Ov23li..."
    clientSecret: "your-secret"
  google:
    clientId: "123456789-abc.apps.googleusercontent.com"
    clientSecret: "your-secret"
  gitlab:
    clientId: "your-client-id"
    clientSecret: "your-secret"
    # baseUrl: https://gitlab.yourcompany.com  # self-hosted only

GitHub

Required scopes: read:user, user:email

1. Create a GitHub OAuth App

   Go to github.com/settings/developers and click New OAuth App.

2. Configure the app

   Set Authorization callback URL to:

   https://<your-api-host>/api/auth/github/callback
   

   Replace <your-api-host> with the value of API_PUBLIC_URL.

3. Copy credentials into Helm values

   values.yaml

   auth:
     github:
       clientId: "Ov23li..."
       clientSecret: "your-secret"
   

Google

Required scopes: openid, email, profile

1. Create an OAuth 2.0 client

   Open the Google Cloud Console and navigate to APIs & Services > Credentials > Create Credentials > OAuth client ID. Choose Web application.

2. Add the redirect URI

   Under Authorized redirect URIs, add:

   https://<your-api-host>/api/auth/google/callback
   
3. Copy credentials into Helm values

   values.yaml

   auth:
     google:
       clientId: "123456789-abc.apps.googleusercontent.com"
       clientSecret: "your-secret"
   

GitLab

Required scopes: read_user

Optio supports both GitLab.com and self-hosted GitLab instances.

1. Create a GitLab application

   Go to your GitLab instance under User Settings > Applications and create a new application.

2. Add the redirect URI

   Set the redirect URI to:

   https://<your-api-host>/api/auth/gitlab/callback
   
3. Copy credentials into Helm values

   values.yaml

   auth:
     gitlab:
       clientId: "your-client-id"
       clientSecret: "your-secret"
   

   For a self-hosted GitLab instance, also set baseUrl:

   values.yaml

   auth:
     gitlab:
       clientId: "your-client-id"
       clientSecret: "your-secret"
       baseUrl: "https://gitlab.yourcompany.com"
   

Sessions

After a successful OAuth login, Optio sets an optio_session cookie in the user’s browser. Sessions are valid for 30 days. Cookies are HttpOnly and SameSite=Lax.

Users can log out at any time from the user menu, which revokes the session immediately.

Local development bypass

The auth bypass must never be used in production. Enabling it removes all access control — any user with network access to the deployment can use Optio without logging in.

For local development, you can disable authentication entirely so you don’t need to configure OAuth providers:

values.yaml

auth:
  disabled: true

Or via environment variable:

OPTIO_AUTH_DISABLED=true

When disabled, the web UI and API accept all requests without a session, and the user profile shows as “Local Dev”.