Skip to content

Authentication Workflow

Overview

This document explains the authentication workflow used on our platform. The authentication system primarily uses Bearer token authentication, leveraging Authress for user and service authentication.

Key Components

  1. Bearer Token Authentication
  2. User Token Validation
  3. Machine Token Validation
  4. Token Caching

1. Bearer Token Authentication

Bearer token authentication is the primary method for user and service authentication. It's implemented in the validate_token function.

  • The Bearer token is extracted from the Authorization header using FastAPI's HTTPBearer dependency.
  • The token is verified using a cached verification process to improve performance.
  • Depending on the client_id in the token, it's processed as either a user token or a machine token.

2. User Token Validation

User tokens are validated in the validate_user_token function:

  1. The user's Authress ID is extracted from the token.
  2. User information is fetched from Authress using authress_client.users.get_user().
  3. If the user exists in the local database, their information is returned.
  4. If the user doesn't exist locally:
  5. The Authress tenant information is retrieved.
  6. A corresponding account is fetched from the local database.
  7. A new user is created in the local database and returned.

3. Machine Token Validation

Machine tokens (for service clients) are validated in the validate_machine_token function:

  1. The client_id from the token is used to fetch the corresponding account.
  2. A UserWithAccount object is created with predefined values for service clients.

4. Token Caching

To improve performance, token verification results are cached:

  • The cached_verify_token function uses lru_cache for caching.
  • Cache keys include the token and a time bucket to ensure regular revalidation.
  • Cache size and TTL are configurable via TOKEN_CACHE_SIZE and TOKEN_CACHE_TTL.

Error Handling

  • Invalid or expired tokens result in a 401 Unauthorized error.
  • Any exceptions during the Authress verification process also result in a 401 Unauthorized error.

Database Integration

  • The authentication process is tightly integrated with the application's database.
  • User information is stored and retrieved from the database during the authentication process.
  • Tenant-specific database sessions are created based on the authenticated user's account.

Service and Repository Initialization

The authentication workflow also sets up the necessary services and repositories:

  • get_tenant_session creates a database session for the authenticated user's tenant.
  • get_repository and get_service are utility functions to initialize repositories and services with the appropriate database session.

Authress Integration

The application uses Authress for token verification and user management:

  • authress_client.verify_token() is used to verify the JWT token.
  • authress_client.users.get_user() fetches user information from Authress.
  • authress_client.tenants.get_tenant() retrieves tenant information when creating new users.

This authentication workflow ensures secure access to your application's resources while providing flexibility for both user and service authentication.