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

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. 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, 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) 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, 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 (or add to console.yml) in the Console configuration directory. The configuration structure maps directly to the OAuthConfig struct defined in modules/security/config/oauth.go:

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 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 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
• 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 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

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:

// 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:

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, 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

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 file specifically instantiates github.NewClient during the initialization phase. However, the generic OAuth realm architecture in 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}