Authentication

Stib includes an optional authentication system that lets you secure your instance and control who can access it. When enabled, users must log in before interacting with Stib. You can use local accounts or connect an external identity provider via OIDC Single Sign-On.

INFO

Authentication is disabled by default. Stib works out of the box without any login — perfect for personal or local use. Enable authentication only when you need to share your instance with others.

How Authentication Works

When authentication is enabled:

• Every API request is checked by an authentication middleware (except public routes like health checks)
• Users receive a JWT token (HS256, 24-hour expiry) upon login
• The JWT secret is auto-generated on first startup and stored in the database
• Two authentication methods are available: local accounts and OIDC SSO

Enable Authentication

Authentication is configured from the Settings page in the Stib web UI.

On first launch, Stib prompts you to create a super admin account (username + password). This account has full access to all settings, including OIDC configuration. Once created, go to Settings → Authentication to enable login for your instance.

Environment Variables

Variable	Description	Default	Required
STIB_SERVER_ORIGIN	Public base URL of your Stib instance (e.g., https://stib.example.com). Used to build the OIDC callback URL.	http://localhost:50505	Yes, for OIDC

WARNING

STIB_SERVER_ORIGIN must match the URL your users access in their browser. If it's wrong, the OIDC callback will fail. Include the protocol and port if non-standard (e.g., https://stib.example.com:8443).

OIDC SSO Configuration

Stib supports any OIDC-compliant identity provider. The Settings UI includes presets for common providers.

Supported Providers

Provider	Issuer URL	Notes
Google	https://accounts.google.com	Works with Google Workspace and personal accounts
Microsoft Entra ID	https://login.microsoftonline.com/{tenant-id}/v2.0	Requires your Azure AD tenant ID
Keycloak	Your Keycloak realm URL	Self-hosted identity provider
Custom	Any OIDC-compliant issuer URL	Must expose /.well-known/openid-configuration

Required Parameters

Parameter	Description
Issuer URL	The OIDC provider's base URL. Stib fetches the discovery document from {issuer_url}/.well-known/openid-configuration.
Client ID	The OAuth2 client ID from your provider's application registration.
Client Secret	The OAuth2 client secret. Encrypted at rest with AES-256-GCM using a key derived from the JWT secret.
Scopes	The OIDC scopes to request. Default: openid email profile.

Setting Up OIDC

WARNING

OIDC configuration requires super admin privileges. Only the super admin account created during first-run setup can access Settings → OIDC Configuration.

1. Register an application in your identity provider
2. Set the redirect URI to: {STIB_SERVER_ORIGIN}/api/auth/oidc/callback
3. Copy the Client ID and Client Secret
4. In Stib, go to Settings → OIDC Configuration
5. Select your provider from the dropdown (or choose Custom)
6. Fill in the Issuer URL, Client ID, Client Secret, and Scopes
7. Click Test Connection to validate the configuration
8. Toggle Enable OIDC and click Save

TIP

The redirect URI is displayed in the OIDC settings panel with a copy button (e.g., https://stib.example.com/api/auth/oidc/callback). Use this exact value when registering your application with the identity provider.

Provider-Specific Guides

Google

1. Go to the Google Cloud Console → APIs & Services → Credentials
2. Create an OAuth 2.0 Client ID (Web application)
3. Add the redirect URI: {STIB_SERVER_ORIGIN}/api/auth/oidc/callback
4. In Stib, select Google from the provider dropdown
5. The issuer URL is pre-filled: https://accounts.google.com
6. Enter your Client ID and Client Secret

Microsoft Entra ID

1. Go to the Azure Portal → Microsoft Entra ID → App registrations
2. Register a new application with the redirect URI: {STIB_SERVER_ORIGIN}/api/auth/oidc/callback
3. Under Certificates & Secrets, create a new client secret
4. In Stib, select Microsoft Entra ID from the provider dropdown
5. Enter your Tenant ID — the issuer URL is built automatically: https://login.microsoftonline.com/{tenant-id}/v2.0
6. Enter your Client ID and Client Secret

INFO

Find your Tenant ID in the Azure Portal under Microsoft Entra ID → Overview. It's the "Directory (tenant) ID" value.

Keycloak

1. In Keycloak Admin, create a new Client in your realm
2. Set Client authentication to On
3. Set the Valid redirect URI to: {STIB_SERVER_ORIGIN}/api/auth/oidc/callback
4. In Stib, select Keycloak from the provider dropdown
5. Enter your issuer URL: https://your-keycloak.example.com/realms/{realm-name}
6. Enter your Client ID and Client Secret

Custom Provider

Any OIDC-compliant provider works with Stib. The provider must:

• Expose a discovery document at {issuer_url}/.well-known/openid-configuration
• Support the authorization code flow with PKCE
• Return an id_token containing sub, email, and optionally name and picture claims

1. In Stib, select Custom from the provider dropdown
2. Enter the issuer URL of your provider
3. Enter your Client ID and Client Secret
4. Adjust scopes if your provider uses non-standard scope names

How SSO Login Works

When OIDC is enabled, the login page shows a "Sign in with {Provider}" button alongside the local login form.

Login Flow

User clicks "Sign in with Google"
        │
        ▼
┌─────────────────────────────┐
│  Stib Server                │
│  GET /api/auth/oidc         │
│  • Generates PKCE verifier  │
│  • Generates state (CSRF)   │
│  • Stores both in memory    │
│  • Redirects to IdP         │
└──────────┬──────────────────┘
           │  302 Redirect
           ▼
┌─────────────────────────────┐
│  Identity Provider          │
│  • User authenticates       │
│  • User consents            │
│  • Redirects back with code │
└──────────┬──────────────────┘
           │  302 Redirect
           ▼
┌─────────────────────────────┐
│  Stib Server                │
│  GET /api/auth/oidc/callback│
│  • Validates state (CSRF)   │
│  • Exchanges code for tokens│
│    using PKCE verifier      │
│  • Validates ID token       │
│  • Provisions user (JIT)    │
│  • Issues Stib JWT          │
│  • Redirects to frontend    │
└─────────────────────────────┘

Token Validation

The ID token received from the provider is validated for:

• Issuer — must match the configured issuer URL
• Audience — must contain the configured client ID
• Expiration — token must not be expired

INFO

Stib does not verify the ID token's cryptographic signature via JWKS. Since the token is received directly from the identity provider over TLS (via the token endpoint), the transport layer guarantees authenticity.

User Provisioning

Stib uses Just-In-Time (JIT) provisioning — user accounts are created automatically on first SSO login.

First Login

1. The server looks up the user by the sub (subject) claim from the ID token
2. If not found, it checks whether the email conflicts with the super admin account
3. If no conflict, a new user is created with:
   • Role: user
   • Auth provider: oidc
   • Name and avatar from the ID token claims (name, picture)
4. Any pending project invitations matching the user's email are automatically resolved

Subsequent Logins

On each login, the user's name and avatar are updated from the latest ID token claims. This keeps user profiles in sync with the identity provider.

WARNING

An OIDC user cannot log in if their email matches the super admin's email. The super admin account is always a local account.

Mobile SSO

The Stib mobile app supports SSO via a deep-link callback flow.

Mobile Login Flow

1. The mobile app initiates authentication: GET /api/auth/oidc?mobile_redirect=stib://auth/callback
2. The server redirects to the identity provider (same PKCE flow as web)
3. After successful authentication, the server redirects to: stib://auth/callback?token={jwt}
4. The mobile app captures the deep link and stores the JWT token

INFO

The mobile_redirect parameter must use the stib:// scheme. The server validates this to prevent open redirect attacks.

Security Considerations

PKCE (Proof Key for Code Exchange)

Stib uses PKCE with the S256 method for all OIDC flows. A unique code verifier and challenge are generated for each authorization request, preventing authorization code interception attacks even if an attacker captures the callback URL.

CSRF Protection

A random state parameter is generated for each authorization request. The server validates the state on callback to prevent cross-site request forgery. States expire automatically after 10 minutes.

Client Secret Encryption

The OIDC client secret is encrypted at rest using AES-256-GCM. The encryption key is derived from the internal JWT secret (auto-generated, stored in database) — this is separate from STIB_ENCRYPTION_KEY, which is used for other credentials like Claude API keys.

Troubleshooting

Common OIDC errors and their solutions:

Error Code	Meaning	Solution
OIDC_NOT_ENABLED	OIDC configuration exists but is not enabled	Go to Settings → OIDC Configuration and toggle Enable OIDC
OIDC_CONFIG_INVALID	Required configuration fields are missing	Verify that Issuer URL, Client ID, and Client Secret are all filled in
OIDC_STATE_INVALID	The state parameter is missing or expired	Try logging in again — states expire after 10 minutes. Ensure your browser accepts cookies.
OIDC_TOKEN_INVALID	The ID token from the provider is malformed or invalid	Check your provider configuration. Ensure the Client ID matches.
OIDC_EMAIL_CONFLICT	The SSO user's email matches the super admin email	The super admin account is always local. Use a different email for SSO.

TIP

Use the Test Connection button in the OIDC settings to validate your configuration before enabling SSO. It checks that the discovery document and JWKS endpoint are reachable.

Next Steps

TIP

Now that authentication is configured, explore these related guides:

• Configuration — General server configuration and environment variables
• Credentials & Scripts — Manage encrypted credentials and database backups
• API Reference — API endpoints and authentication headers