Authentication Flow & Integration Guide

Follow this comprehensive guide to implement BOSA Authentication in your application. Each section explains both the technical concept and provides practical integration steps.

Understanding the Configuration

BOSA Authentication requires configuration for database connectivity, security parameters, and token settings. The system uses a singleton AuthenticationDbSettings class to maintain consistent configuration across your application. For more details about table structure initialized, please check database schema →

Install Dependencies

# Using pip
pip install bosa-core-binary[authentication]

# Using poetry
poetry add bosa-core-binary[authentication]

Configure Environment Variables

Add the following key to your .env file:

# Required environment variables
DATABASE_AUTHENTICATION_URL="postgresql://user:password@localhost:5432/auth_db"
AUTH_SECRET_KEY="your-secure-secret-key"

# Optional environment variables
AUTH_ALGORITHM="HS256"
AUTH_ACCESS_TOKEN_EXPIRE_MINUTES="43200"  # 30 days

Initialize Authentication

Before using any authentication features, call this once during application startup:

from bosa_core.authentication.config import AuthenticationDbSettings
from bosa_core.authentication.provider import init_auth_services

# Initialize settings
auth_settings = AuthenticationDbSettings(
    database_authentication_url=os.getenv("DATABASE_AUTHENTICATION_URL"),
    auth_secret_key=os.getenv("AUTH_SECRET_KEY"),
    auth_algorithm=os.getenv("AUTH_ALGORITHM"),
    auth_access_token_expire_minutes=int(os.getenv("AUTH_ACCESS_TOKEN_EXPIRE_MINUTES", 43200))
)

init_auth_services(auth_settings)

This initialization creates all necessary database tables and prepares the system for client and user management.

Understanding Client Management

The client represents an organization or tenant in the multi-tenancy model. Each client has its own API key used to create and manage users within its scope. Client API keys follow the format:

sk-client-<base64-client-id>.<base64-client-name>.<client-secret>

To interact with client-related features, you can import the necessary services from:

from bosa_core.authentication.service import (
    create_client_service,    # For creating new clients and generating API keys
    verify_client_service,    # For verifying API keys and retrieving client info
    client_aware_service,     # For accessing services that are scoped to a specific client
)

Create a Client

# Create a new client
client = create_client_service.create_client("Example Organization")

# Store the API key securely - it's only shown once
print(f"Client API Key: {client.api_key}")

Verify Client API Key

There are two ways to verify a client API key. First is using client_aware_service

client_api_key = "sk-client-..."
# Get client by the api_key
client = client_aware_service.get_client_by_api_key(api_key)
print(f"Existing Client: {client.name}")

This is useful when you want to perform further operations scoped to the verified client, such as accessing client-specific data. Or, you can perform direct approach when you only need to validate the API key.

client_api_key = "sk-client-..."
# Verify an API key
is_client_valid = verify_client_service.verify_client_api_key(api_key) # Boolean
print(f"Verified client: {is_client_valid}")

Understanding User Management

Users exist within the scope of a client. Each user has a unique identifier and a secret (password). The system securely hashes all secrets using Argon2 before store it. To interact with user-related features, you can import the necessary services from:

from bosa_core.authentication.service import (
    authentication_service,   # Authenticate users and issue JWT tokens
    create_user_service,      # Register new users under a client
    get_user_service,         # Retrieve user details by ID or other criteria   
)

Create a User

# Client API key from the previous step
client_api_key = "sk-client-..."

# Create a new user
user = create_user_service.create_user(client_api_key, "[e-mail]")

# Store the user secret securely - it's only shown once
print(f"User secret: {user.secret}")

Get User Information

You can retrieve user information using either:

• User ID, or

• User identifier (e.g. email)

Both methods require the client API key to enforce multi-tenancy and ensure scoped access.

# Client API key from the previous step
client_api_key = "sk-client-..."

# Get user by ID
user = get_user_service.get_user(client_api_key, user_id)

# Get user by identifier (e.g. email)
user = get_user_service.get_user_by_identifier(client_api_key, "[e-mail]")

User management operations always require a valid client API key to enforce the multi-tenancy security model.

Understanding Authentication

Authentication validates user credentials and issues JWT tokens. These tokens are used for subsequent API requests. The system records all active tokens and supports token verification and revocation.

To interact with token-related features, you can import the necessary services from:

from bosa_core.authentication.service import (
    verify_token_service,     # Verify the validity of access tokens and extract user ID
    revoke_token_service,     # Revoke active tokens to force logout or session invalidation
)

Authenticate a User

# Authenticate user with client API key, identifier and secret
try:
    auth = authenticate_service.authenticate_user(
        client_api_key, "[e-mail]", user_secret
    )
    
    # Use the token for subsequent API requests
    access_token = auth.token
    # auth.token_type == "bearer"
    # auth.expires_at contains the expiration timestamp
except Exception as e:
    print(f"Authentication failed: {str(e)}")

Verify a Token

# Verify token and get user ID
try:
    user_id = verify_token_service.verify_token_and_get_user_id(
        client_api_key, access_token
    )
    # Proceed with the authenticated request
except Exception as e:
    # Token is invalid or expired
    print(f"Token verification failed: {str(e)}")

Revoke a Token

# Revoke a token
revoked = revoke_token_service.revoke_token(client_api_key, access_token)

When implementing authentication flows, always verify tokens on each protected endpoint and implement proper error handling for authentication failures.

Understanding Third-Party Integrations

The BOSA Authentication system allows users to create secure integrations with third-party services. These integrations store authentication credentials for services like GitHub, Google Drive, and others.

To interact with third-party related features, you can import the necessary services from:

from bosa_core.authentication.service import third_party_integration_service

Create an Integration

# Create an integration for a user
integration = ThirdPartyIntegrationAuth(
    client_id=UUID("client-uuid"),  # From your client
    user_id=UUID("user-uuid"),      # From your user
    connector="github",             # Integration type
    auth_string="oauth-token-xyz",  # OAuth token or credentials
    user_identifier="github-username"
)

# Save the integration
saved_integration = third_party_integration_service.create_integration(integration)

Check for Existing Integrations

# Check if user has GitHub integration
has_integration = third_party_integration_service.has_integration(
    client_id=UUID("client-uuid"),
    user_id=UUID("user-uuid"),
    connector="github"
)

Get Integration Data

# Retrieve integration data
integration = third_party_integration_service.get_integration(
    client_id=UUID("client-uuid"),
    user_id=UUID("user-uuid"),
    connector="github"
)

if integration:
    auth_string = integration.auth_string  # Use this to authenticate with GitHub API

Remove an Integration

# Remove a third-party integration
third_party_integration_service.delete_integration(
    client_id=UUID("client-uuid"),
    user_id=UUID("user-uuid"),
    connector="github"
)

When implementing third-party integrations, follow OAuth 2.0 best practices for secure authorization flows and token storage.

You can adapt BOSA Core Authentication to other frameworks by following the same flow of initializing configuration, setting up repositories and services, and implementing the appropriate authentication checks. For more details reference of each class and functions, please check API Reference →