SSO Integration

Enterprise authentication with Single Sign-On

SSO Integration

Configure Single Sign-On (SSO) for your organization to streamline authentication and improve security. Bud Stack supports multiple authentication providers through Keycloak integration.

Overview

SSO provides several benefits:

• Centralized Authentication: One set of credentials for all applications
• Enhanced Security: Leverage your existing identity provider’s security features
• Simplified User Management: Auto-provision users from your directory
• Improved User Experience: Seamless login across services
• Compliance: Meet enterprise security requirements

SSO configuration requires Admin privileges with SUPER_ADMIN or ADMIN role. Contact support for assistance with setup.

Supported Authentication Providers

Bud Stack supports the following authentication methods through Keycloak:

Google OAuth

Sign in with Google Workspace accounts

Microsoft OAuth

Sign in with Microsoft 365 / Azure AD accounts

LinkedIn OAuth

Sign in with LinkedIn accounts

GitHub OAuth

Sign in with GitHub accounts

Coming Soon

• SAML 2.0: Generic SAML integration for enterprise IdPs
• Okta: Direct Okta integration
• Azure AD: Native Azure Active Directory
• Custom OIDC: OpenID Connect providers

How SSO Works in Bud Stack

Authentication Flow

Just-In-Time (JIT) Provisioning

When a user logs in via SSO for the first time:

1. User Authentication: User authenticates with OAuth provider
2. Token Verification: Keycloak verifies the authentication
3. User Lookup: System checks if user exists in database
4. Auto-Provisioning: If new, system automatically creates user account
5. Role Assignment: User type and role derived from Keycloak realm roles
6. Permission Setup: Appropriate permissions assigned automatically
7. Resource Creation: Default project and billing plan created (for Client users)

JIT provisioning means you don’t need to manually create accounts for SSO users - they’re automatically created on first login.

Setting Up SSO

Prerequisites

Before configuring SSO:

• Admin access to your OAuth provider (Google, Microsoft, etc.)
• Ability to create OAuth applications
• Redirect URLs approved by your IT security team
• Understanding of your organization’s identity provider setup

Configuration Steps

Google OAuth

Google OAuth Setup

1. Create OAuth App in Google Cloud

   1. Go to Google Cloud Console
   2. Navigate to APIs & Services > Credentials
   3. Click Create Credentials > OAuth 2.0 Client ID
   4. Select Web application
   5. Add authorized redirect URI: https://auth.bud.studio/realms/{your-realm}/broker/google/endpoint
2. Get OAuth Credentials

   Copy the Client ID and Client Secret provided by Google.

3. Configure in Bud Stack

   Contact Bud Stack support with:

   • Your OAuth Client ID
   • Your OAuth Client Secret
   • Your organization domain
   • Desired user mapping (Admin vs Client)
4. Test Authentication

   1. Log out of Bud Stack
   2. Click “Sign in with Google”
   3. Authenticate with your Google account
   4. Verify you’re logged into Bud Stack

Domain Restriction: Restrict authentication to your organization’s domain by configuring the hd parameter in Google OAuth to only allow @yourcompany.com emails.

Microsoft OAuth

Microsoft OAuth Setup

1. Register App in Azure Portal

   1. Go to Azure Portal
   2. Navigate to Azure Active Directory > App registrations
   3. Click New registration
   4. Name: “Bud Stack Authentication”
   5. Add redirect URI: https://auth.bud.studio/realms/{your-realm}/broker/microsoft/endpoint
2. Configure API Permissions

   Add the following Microsoft Graph permissions:

   • User.Read - Read user profile
   • email - Read user email
   • profile - Read user profile info
3. Create Client Secret

   1. Go to Certificates & secrets
   2. Click New client secret
   3. Copy the secret value (shown only once)
4. Provide to Bud Stack

   Send to support:

   • Application (client) ID
   • Client secret value
   • Directory (tenant) ID
   • Organization info

Tenant Configuration: Use single-tenant configuration for maximum security, restricting to your Azure AD tenant only.

GitHub OAuth

GitHub OAuth Setup

1. Create OAuth App in GitHub

   1. Go to GitHub Developer Settings
   2. Click New OAuth App
   3. Fill in application details
   4. Authorization callback URL: https://auth.bud.studio/realms/{your-realm}/broker/github/endpoint
2. Generate Client Secret

   After creating the app, generate a new client secret.

3. Configure Organization Access

   If using GitHub Organizations:

   1. Enable organization access
   2. Restrict to specific organizations
   3. Request organization email access
4. Submit to Bud Stack

   Provide support with:

   • Client ID
   • Client secret
   • Organization restrictions (if any)

Organization Filtering: Configure GitHub OAuth to only allow users from specific GitHub organizations.

LinkedIn OAuth

LinkedIn OAuth Setup

1. Create LinkedIn App

   1. Go to LinkedIn Developers
   2. Create new app
   3. Request access to Sign In with LinkedIn product
   4. Add redirect URL: https://auth.bud.studio/realms/{your-realm}/broker/linkedin/endpoint
2. Configure OAuth Scopes

   Request the following scopes:

   • r_liteprofile - Read profile
   • r_emailaddress - Read email
3. Get Credentials

   Copy Client ID and Client Secret from app settings.

4. Configure with Bud Stack

   Send credentials and configuration to support team.

User Type Mapping

Configure how SSO users are mapped to Bud Stack user types:

Option 1: Domain-Based Mapping

Map users based on email domain:

# Example configuration
domain_mapping:
  admin_domains:
    - "@yourcompany.com"
    - "@corp.yourcompany.com"
  client_domains:
    - "@partner.com"
    - "@contractor.com"

Option 2: Role-Based Mapping

Use Keycloak realm roles to determine user type:

# Example configuration
role_mapping:
  keycloak_role: "bud-admin"
  bud_user_type: "ADMIN"
  bud_role: "DEVELOPER"

  keycloak_role: "bud-client"
  bud_user_type: "CLIENT"

Option 3: Group-Based Mapping

Map based on OAuth provider groups (Azure AD, Google Workspace):

# Example configuration
group_mapping:
  "Engineering Team":
    user_type: "ADMIN"
    role: "DEVELOPER"
  "Data Science Team":
    user_type: "ADMIN"
    role: "DEVELOPER"
  "Business Users":
    user_type: "CLIENT"

Security Considerations

Multi-Factor Authentication (MFA)

Bud Stack relies on your identity provider’s MFA. Ensure MFA is enabled in your OAuth provider (Google, Microsoft, etc.) for enhanced security.

Session Management

• Session Duration: 8 hours by default
• Refresh Tokens: Automatically refreshed
• Forced Re-authentication: Can be configured
• Logout: Logs out of both Bud Stack and Keycloak

Access Control

• IP Whitelisting: Configure allowed IP ranges in Keycloak
• Device Trust: Leverage provider’s device trust features
• Conditional Access: Use Azure AD conditional access policies

Troubleshooting SSO

Common Issues

Redirect URI Mismatch

Error: redirect_uri_mismatch

Solution:

1. Verify redirect URI in OAuth provider matches exactly
2. Check for http vs https
3. Ensure realm name is correct in URL
4. No trailing slashes

User Not Provisioned

Error: User authenticates but doesn’t get created

Solution:

1. Check JIT provisioning is enabled
2. Verify user email is accessible from OAuth provider
3. Check realm role mapping configuration
4. Review Keycloak logs for errors

Wrong User Type Assigned

Error: User gets Client instead of Admin (or vice versa)

Solution:

1. Review domain/role/group mapping configuration
2. Check user’s realm roles in Keycloak
3. Verify OAuth provider returns correct group information
4. User may need to log out and back in after role change

Permission Errors After Login

Error: User logs in but can’t access expected features

Solution:

1. Verify user type and role in User Management
2. Check permission assignment for that role
3. User should log out and log back in
4. Refer to Roles & Permissions

Getting Help

For SSO setup assistance:

1. Check Configuration: Review OAuth app settings
2. Test OAuth Flow: Use provider’s OAuth testing tools
3. Review Logs: Check Keycloak logs for errors
4. Contact Support: Email [e-mail] with:
   • OAuth provider being used
   • Error messages or screenshots
   • Organization details
   • Current configuration (without secrets)

Best Practices

Enable MFA

Require multi-factor authentication in your identity provider for all users.

Restrict Domains

Limit SSO to your organization’s email domains to prevent unauthorized access.

Regular Audits

Review SSO user access quarterly and remove inactive users.

Test Thoroughly

Test SSO with different user types before rolling out organization-wide.

Document Process

Maintain documentation of your SSO configuration for your team.

Monitor Activity

Track SSO logins in audit logs to detect anomalies.

Enterprise Features

SAML 2.0 (Coming Soon)

For organizations with custom identity providers:

• Generic SAML 2.0 support
• Works with Okta, OneLogin, Auth0, etc.
• Attribute mapping configuration
• SP-initiated and IdP-initiated flows

Contact sales for early access.

Advanced Provisioning (Coming Soon)

• SCIM Protocol: Automated user sync from your directory
• Deprovisioning: Automatic account deactivation when users leave
• Attribute Sync: Keep user profiles updated automatically
• Group Sync: Automatic permission assignment based on groups

Related Pages

• Inviting Users - Manual user invitation
• Roles & Permissions - Understanding permissions
• User Activity - Monitor SSO logins
• Security Best Practices - Secure your organization

API Reference

Get User SSO Info

import requests

response = requests.get(
    "https://api.bud.studio/users/me",
    headers={"Authorization": f"Bearer {api_key}"}
)

user = response.json()
print(f"Auth Method: {user.get('auth_provider', 'email_password')}")
print(f"SSO Email: {user['email']}")

Check SSO Configuration

# Check if SSO is configured for your realm
curl -X GET https://api.bud.studio/auth/sso-config \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
{
  "sso_enabled": true,
  "providers": ["google", "microsoft"],
  "jit_provisioning": true
}

Summary

SSO integration provides:

• Seamless Authentication: One-click login with existing credentials
• Auto-Provisioning: New users created automatically (JIT)
• Enhanced Security: Leverage enterprise identity provider features
• Centralized Management: Manage access from your identity provider
• Better User Experience: No need to remember multiple passwords

For SSO setup assistance, contact [e-mail] or your account manager.