# Authentication Methods in INFINI Console: How to Configure OAuth Single Sign-On

> Explore authentication methods in INFINI Console, including native LDAP and OAuth SSO. Learn to configure OAuth single sign-on using YAML for seamless access.

- Repository: [INFINI Labs/console](https://github.com/infinilabs/console)
- Tags: how-to-guide
- Published: 2026-03-04

---

**INFINI Console supports Native (local username/password), LDAP, and OAuth (GitHub) authentication through modular security realms that initialize at startup, with OAuth SSO configured via YAML files containing client credentials and role mappings.**

INFINI Console implements a pluggable authentication architecture using **security realms** loaded during the module initialization phase. The system currently ships with three concrete implementations that cover local directory services, enterprise LDAP integration, and OAuth single sign-on. Understanding these authentication methods and their configuration paths is essential for securing your console deployment.

## Supported Authentication Methods in INFINI Console

The authentication layer in INFINI Console resides in `modules/security/realm/` and registers providers through a centralized registry defined in [`modules/security/realm/realm.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/realm.go). Each realm implements the authentication interface and handles specific user credential sources.

### Native Authentication (Username/Password)

The **Native realm** stores user credentials locally within the Console's RBAC index. Located in [`modules/security/realm/authc/native/init.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/native/init.go), this implementation bcrypt-hashes passwords before persistence and validates login attempts against the internal user database. This method requires no external dependencies and serves as the default authentication mode for new installations.

### LDAP Authentication

For enterprise environments, the **LDAP realm** ([`modules/security/realm/authc/ldap/ldap.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/ldap/ldap.go)) authenticates users against external LDAP or Active Directory servers. This implementation supports role mapping from LDAP group memberships or UIDs, allowing you to synchronize existing directory permissions with INFINI Console's RBAC system without duplicating user accounts.

### OAuth Single Sign-On (GitHub)

The **OAuth realm** provides SSO capabilities through external identity providers. As implemented in [`modules/security/realm/authc/oauth/oauth.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/oauth/oauth.go), this realm currently supports GitHub as the built-in provider. The flow generates CSRF states, handles the authorization code exchange, and automatically provisions Console user accounts post-authentication. While the architecture supports additional providers, the current codebase specifically instantiates `github.NewClient` within the OAuth handler.

## How to Configure OAuth Single Sign-On

Enabling OAuth SSO requires creating an OAuth application with your provider, defining the security configuration in YAML, and reloading the Console service.

### Step 1: Create GitHub OAuth Application

Register a new OAuth application in your GitHub organization:

1. Navigate to **Settings → Developer settings → OAuth Apps → New OAuth App**
2. Set the **Authorization callback URL** to `https://<your-console-host>/sso/callback/` (this path is fixed in the codebase)
3. Record the generated **Client ID** and **Client Secret** for the next step

### Step 2: Configure OAuth Settings

Create or edit [`oauth.yml`](https://github.com/infinilabs/console/blob/main/oauth.yml) (or add to [`console.yml`](https://github.com/infinilabs/console/blob/main/console.yml)) in the Console configuration directory. The configuration structure maps directly to the `OAuthConfig` struct defined in [`modules/security/config/oauth.go`](https://github.com/infinilabs/console/blob/main/modules/security/config/oauth.go):

```yaml
security:
  oauth:
    enabled: true
    client_id: "YOUR_CLIENT_ID"
    client_secret: "YOUR_CLIENT_SECRET"
    default_roles: ["ReadonlyUI", "AllClusters"]
    role_mapping:
      github_username: ["Administrator"]
    authorize_url: "https://github.com/login/oauth/authorize"
    token_url: "https://github.com/login/oauth/access_token"
    redirect_url: ""
    scopes: []
    success_page: "/#/user/sso/success"
    failed_page: ""

```

The [`modules/security/config/oauth.go`](https://github.com/infinilabs/console/blob/main/modules/security/config/oauth.go) file defines these fields:
- **default_roles**: Roles assigned to all SSO users when no specific mapping exists
- **role_mapping**: Map specific GitHub login names to Console role arrays
- **redirect_url**: Optional override; empty string uses the default callback path

### Step 3: Initialize the OAuth Realm

When the Console starts, [`modules/security/module.go`](https://github.com/infinilabs/console/blob/main/modules/security/module.go) checks `OAuthConfig.Enabled` and calls `oauth.Init()` to register the HTTP handlers. This process:

- Builds an `oauth2.Config` from your YAML values in [`modules/security/realm/authc/oauth/init.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/oauth/init.go)
- Registers `/sso/login/` (AuthHandler) and `/sso/callback/` (CallbackHandler) routes
- Initializes the GitHub client with your endpoint configuration

Restart the Console service to load the new security realm.

### Step 4: Authentication Flow

The OAuth implementation in [`modules/security/realm/authc/oauth/oauth.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/oauth/oauth.go) handles the complete flow:

1. **AuthHandler**: Generates a CSRF state, stores it in session, and redirects to the provider's authorize URL
2. **CallbackHandler**: Validates the state parameter, exchanges the authorization code for an access token, fetches the GitHub user profile
3. **User Provisioning**: Resolves roles using `default_roles` or `role_mapping`, creates or updates the `rbac.User` entity
4. **Token Generation**: Issues a Console JWT via `rbac.GenerateAccessToken` and redirects to `SuccessPage` with the token payload

## Practical Configuration Examples

### Minimal OAuth Configuration

```yaml
security:
  oauth:
    enabled: true
    client_id: "gh_client_12345"
    client_secret: "gh_secret_67890"
    default_roles: ["ReadonlyUI"]
    authorize_url: "https://github.com/login/oauth/authorize"
    token_url: "https://github.com/login/oauth/access_token"

```

### Programmatic Login Redirect

To trigger authentication from a custom frontend:

```go
// Redirect browser to the OAuth entry point
http.Redirect(w, r, "/sso/login/?redirect_url=/dashboard", http.StatusFound)

```

### Handling the Success Page Token

The success page receives the JWT via query parameter:

```javascript
const params = new URLSearchParams(window.location.search);
const payload = params.get('payload');
if (payload) {
    const data = JSON.parse(atob(payload));
    document.cookie = `infini_token=${data.token}; path=/; secure;`;
    window.location.href = '/';
}

```

## Summary

- INFINI Console offers three authentication realms: **Native** (local bcrypt storage), **LDAP** (external directory), and **OAuth** (GitHub SSO)
- OAuth configuration requires defining `OAuthConfig` in YAML with `client_id`, `client_secret`, and role mappings
- The implementation resides in [`modules/security/realm/authc/oauth/oauth.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/oauth/oauth.go), handling the flow through `/sso/login/` and `/sso/callback/` endpoints
- After successful GitHub authentication, the system creates a `rbac.User`, applies roles from `default_roles` or `role_mapping`, and issues a JWT via `rbac.GenerateAccessToken`
- Restart the Console service after modifying security configuration to initialize the OAuth realm in [`modules/security/module.go`](https://github.com/infinilabs/console/blob/main/modules/security/module.go)

## Frequently Asked Questions

### What OAuth providers are supported besides GitHub?

Currently, only GitHub is implemented as an OAuth provider in the INFINI Console codebase. The [`modules/security/realm/authc/oauth/oauth.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/oauth/oauth.go) file specifically instantiates `github.NewClient` during the initialization phase. However, the generic OAuth realm architecture in [`modules/security/realm/authc/oauth/init.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/oauth/init.go) supports additional providers through the standard `oauth2.Config` structure, requiring code modifications to instantiate other provider clients.

### How does role mapping work with OAuth users?

Role mapping occurs in the CallbackHandler after successful authentication. The system first checks if the GitHub login name exists in the `role_mapping` dictionary defined in your configuration. If found, the user receives those specific roles; otherwise, the `default_roles` array is applied. These roles are then persisted with the user record in the Console's RBAC index during the automatic user provisioning step.

### Where are the OAuth endpoints exposed?

The OAuth realm registers two fixed HTTP endpoints during initialization: `/sso/login/` (handled by AuthHandler) initiates the authentication flow, and `/sso/callback/` (handled by CallbackHandler) receives the authorization code from the provider. These routes are defined in [`modules/security/realm/authc/oauth/init.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/oauth/init.go) and cannot be customized without modifying the source code.

### What happens if the OAuth configuration is invalid?

If `OAuthConfig.Enabled` is true but the configuration contains invalid credentials or unreachable URLs, the `oauth.Init()` function in [`modules/security/realm/authc/oauth/init.go`](https://github.com/infinilabs/console/blob/main/modules/security/realm/authc/oauth/init.go) will still register the handlers, but authentication attempts will fail at the token exchange stage. Users will be redirected to the configured `FailedPage` (or a default error state) when the GitHub API returns an error during the CallbackHandler execution. Check the Console logs for detailed error messages from the OAuth exchange.