legate 0.1.0

data/public/docs/authentication/guides/service_account.md

@@ -0,0 +1,228 @@
+# Service Account Authentication
+
+Service accounts provide a way to authenticate applications without user interaction, typically for server-to-server communication. The Legate Ruby library supports service account authentication with various cloud providers.
+
+## Overview
+
+Service account authentication uses a key-based approach where:
+
+1. The application creates a signed JWT (JSON Web Token) using the service account's private key
+2. This JWT is exchanged for an access token from the authorization server
+3. The access token is then used to authenticate API requests
+
+This flow is ideal for:
+- Server-to-server integrations
+- Background processing
+- Automated tasks and scheduled jobs
+- Services that run without user interaction
+
+## Configuration
+
+### Creating a Service Account Scheme
+
+```ruby
+# Basic service account scheme
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://oauth2.googleapis.com/token',
+  audience: 'https://oauth2.googleapis.com/token',
+  scopes: ['https://www.googleapis.com/auth/cloud-platform']
+)
+
+# With additional options
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://oauth2.googleapis.com/token',
+  audience: 'https://oauth2.googleapis.com/token',
+  scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+  token_lifetime: 3600  # Access token lifetime in seconds (default: 3600)
+)
+```
+
+### Creating a Service Account Credential
+
+There are several ways to provide the service account key information:
+
+#### From a JSON Key File
+
+```ruby
+# Using a JSON key file. service_account_key takes a raw JSON string
+# (not a parsed Hash); or use service_account_key_file with a path.
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account-key.json')
+)
+
+# Or point at the file directly:
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key_file: '/path/to/service-account-key.json'
+)
+```
+
+#### From Environment Variable
+
+```ruby
+# Store the entire JSON key contents in an environment variable (raw string)
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: ENV['SERVICE_ACCOUNT_JSON']
+)
+
+# Or reference it lazily with the ENV: prefix:
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: 'ENV:SERVICE_ACCOUNT_JSON'
+)
+```
+
+## Authentication Flow
+
+Service account authentication is non-interactive and happens automatically when the tool is executed:
+
+```ruby
+# 1. Configure the service account scheme
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://oauth2.googleapis.com/token',
+  audience: 'https://oauth2.googleapis.com/token',
+  scopes: ['https://www.googleapis.com/auth/cloud-platform']
+)
+
+# 2. Configure the credential with the service account key (raw JSON string)
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account-key.json')
+)
+
+# 3. Exchange the credential for an access token
+token = scheme.exchange_token(credential)
+
+# 4. Apply the token to outbound requests
+connection = Legate::Auth.create_connection('https://api.example.com',
+  scheme: scheme,
+  credential: token
+)
+result = connection.get(path: '/resource')
+```
+
+## Provider-Specific Configurations
+
+### Google Cloud Service Account
+
+```ruby
+# Using the GoogleServiceAccount scheme (recommended for Google Cloud)
+scheme = Legate::Auth::Schemes::GoogleServiceAccount.new(
+  scopes: [
+    'https://www.googleapis.com/auth/cloud-platform',
+    'https://www.googleapis.com/auth/bigquery'
+  ]
+)
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :google_service_account,
+  service_account_key: File.read('google-service-account.json')
+)
+```
+
+### AWS Service Account
+
+```ruby
+# AWS STS token exchange
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://sts.amazonaws.com',
+  audience: 'aws.amazonaws.com'
+)
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('aws-credentials.json')
+)
+```
+
+### Azure Service Account
+
+```ruby
+# Azure service principal
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token',
+  audience: 'https://management.azure.com/'
+)
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: ENV['AZURE_SERVICE_ACCOUNT_JSON']  # raw JSON string
+)
+```
+
+> The base `ServiceAccount` scheme reads its key material from the credential's
+> `service_account_key` (raw JSON string) or `service_account_key_file` (path).
+> Provider-specific client_id/secret/tenant fields are not read directly by the
+> base scheme.
+
+## Token Management
+
+When used with a `TokenManager`, service account tokens are managed for you:
+
+- **Token Acquisition**: The JWT assertion is exchanged for an access token
+- **Token Storage**: The access token is cached in scoped session state (plaintext; apply `Legate::Auth::Encryption` yourself for at-rest encryption)
+- **Token Refresh**: Service account schemes support refresh — an expired token triggers a new exchange (`supports_refresh?` is `true`)
+
+## Security Best Practices
+
+1. **Secure Key Storage**:
+   - Never commit service account keys to source control
+   - Use environment variables or secret management services
+   - Restrict file permissions on key files
+
+2. **Principle of Least Privilege**:
+   - Create service accounts with minimal required permissions
+   - Request only necessary scopes
+   - Use different service accounts for different purposes
+
+3. **Key Rotation**:
+   - Regularly rotate service account keys
+   - Monitor key usage for suspicious activity
+
+4. **Secure Transport**:
+   - Always use HTTPS for token exchange (token URLs are SSRF-checked by `Legate::Auth::UrlGuard`)
+   - HTTPS encrypts tokens in transit; for at-rest encryption use the opt-in `Legate::Auth::Encryption` module
+
+## Creating Service Account Keys
+
+### Google Cloud
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Navigate to IAM & Admin > Service Accounts
+3. Select or create a service account
+4. Click "Keys" > "Add Key" > "Create new key"
+5. Choose JSON format and click "Create"
+6. Save the downloaded key file securely
+
+### AWS
+
+1. Go to the [AWS Management Console](https://console.aws.amazon.com/)
+2. Navigate to IAM > Users
+3. Create a new user or select an existing one
+4. Click "Security credentials" > "Create access key"
+5. Save the Access Key ID and Secret Access Key securely
+
+### Azure
+
+1. Go to the [Azure Portal](https://portal.azure.com/)
+2. Navigate to Azure Active Directory > App registrations
+3. Create a new registration or select an existing one
+4. Go to "Certificates & secrets" > "New client secret"
+5. Create a secret and save the value securely
+
+## Troubleshooting
+
+If you encounter issues with service account authentication:
+
+- Verify that the service account key is valid and correctly formatted
+- Check that the service account has the necessary permissions
+- Ensure the scopes requested are allowed for the service account
+- Verify that the audience value matches what the provider expects
+- Check that the token URL is correct for your provider
+
+## Related Topics
+- [Token Lifecycle Management](./token_lifecycle) - Advanced token management techniques
+- [Secure Credential Storage](./secure_storage) - Best practices for credential security
+- [OAuth2 Authentication](./oauth2) - Learn about OAuth2 authentication for user-based flows 

data/public/docs/authentication/guides/token_lifecycle.md

@@ -0,0 +1,295 @@
+# Token Lifecycle Management
+
+Authentication tokens have a lifecycle that includes acquisition, refresh, and eventual expiration or revocation. The Legate Ruby library provides a comprehensive token management system to handle these aspects automatically.
+
+## Overview
+
+The token lifecycle includes several key phases:
+
+1. **Token Acquisition**: The initial exchange of credentials for a token
+2. **Token Storage**: Secure storage of the token for subsequent requests
+3. **Token Usage**: Using the token to authenticate API requests
+4. **Token Refresh**: Renewing the token before it expires
+5. **Token Expiration**: Handling token expiration gracefully
+6. **Token Revocation**: Explicitly revoking tokens when no longer needed
+
+## Token Manager
+
+The `Legate::Auth::TokenManager` class handles all aspects of token lifecycle management:
+
+```ruby
+# Create a token manager with a token store
+token_store = Legate::Auth::TokenStore.new(session)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# Get a token (automatically handles acquisition and refresh)
+token = token_manager.get_token(scheme, credential)
+
+# Force refresh a token
+refreshed_token = token_manager.get_token(scheme, credential, force_refresh: true)
+
+# Invalidate a token in the store
+token_manager.invalidate_token(cache_key)
+
+# Revoke a token with the provider
+token_manager.revoke_token(scheme, credential, token)
+```
+
+## Token Acquisition
+
+Tokens are acquired through different mechanisms depending on the authentication scheme:
+
+### OAuth2/OIDC
+
+```ruby
+# OAuth2 token acquisition via authorization code
+scheme = Legate::Auth::Schemes::OAuth2.new(
+  authorization_url: 'https://auth.example.com/authorize',
+  token_url: 'https://auth.example.com/token',
+  scopes: ['profile', 'email']
+)
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :oauth2,
+  client_id: ENV['CLIENT_ID'],
+  client_secret: ENV['CLIENT_SECRET']
+)
+
+# The token is acquired through the Fiber yield/resume mechanism
+```
+
+### Service Account
+
+```ruby
+# Service account token acquisition
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://oauth2.googleapis.com/token',
+  audience: 'https://oauth2.googleapis.com/token',
+  scopes: ['https://www.googleapis.com/auth/cloud-platform']
+)
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account-key.json')  # raw JSON string
+)
+
+# The token is acquired automatically when needed
+token = token_manager.get_token(scheme, credential)
+```
+
+### API Key
+
+```ruby
+# API key "token" creation
+scheme = Legate::Auth::Schemes::ApiKey.new
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :api_key,
+  api_key: ENV['API_KEY']
+)
+
+# Creates a wrapper token that never expires
+token = token_manager.get_token(scheme, credential)
+```
+
+## Token Storage
+
+Tokens are cached in scoped session state:
+
+```ruby
+# The TokenStore caches tokens under the 'auth' scope
+token_store = Legate::Auth::TokenStore.new(session_service)
+
+# Store a token
+token_store.store(cache_key, token)
+
+# Retrieve a token (returns nil if missing or expired)
+token = token_store.get(cache_key)
+
+# Clear a token
+token_store.clear(cache_key)
+```
+
+### Security Considerations
+
+- Tokens are stored as plaintext (`token.to_h`) in scoped state; `TokenStore` does **not** encrypt them
+- For at-rest encryption, apply the opt-in `Legate::Auth::Encryption` module yourself (requires the `rbnacl` gem and a Base64 key in `LEGATE_AUTH_ENCRYPTION_KEY`)
+- Sensitive token information should never be logged
+
+## Token Refresh
+
+Most tokens have an expiration time and need to be refreshed:
+
+```ruby
+# Configure token refresh settings
+token_manager = Legate::Auth::TokenManager.new(token_store, {
+  refresh_buffer: 60,       # Refresh 60 seconds before expiration
+  retry_max_attempts: 3,    # Try up to 3 times
+  retry_delay: 2,           # Wait 2 seconds between attempts
+  retry_backoff: 1.5,       # Increase wait time by 1.5x each try
+  auto_refresh: true        # Enable automatic refresh
+})
+
+# Token refresh is automatic when get_token is called
+token = token_manager.get_token(scheme, credential)
+```
+
+### Refresh Behavior by Scheme Type
+
+- **OAuth2/OIDC**: Uses the refresh token to obtain a new access token
+- **Service Account**: Creates a new JWT assertion and exchanges it for a new token
+- **API Key**: No refresh needed (API keys don't expire)
+- **Bearer Token**: Can't be refreshed (must re-authenticate)
+
+## Token Expiration
+
+The Legate Ruby library handles token expiration gracefully:
+
+```ruby
+# Check if a token is expired
+if token.expired?
+  # Handle expiration
+end
+
+# Check if a token is expired with a buffer time (positional argument)
+if token.expired?(60)
+  # Token expires within the next 60 seconds
+end
+
+# ExchangedCredential includes expiration information
+token = Legate::Auth::ExchangedCredential.new(
+  auth_type: :oauth2,
+  access_token: 'access-token',
+  refresh_token: 'refresh-token',
+  expires_in: 3600          # Token expires in 3600 seconds
+)
+
+# Get expiration time
+expiry = token.expires_at   # Time object representing expiration
+```
+
+## Token Revocation
+
+When a token is no longer needed, it can be explicitly revoked:
+
+```ruby
+# Revoke a token with the provider
+token_manager.revoke_token(scheme, credential, token)
+
+# Just invalidate it in the store without provider revocation
+token_manager.invalidate_token(cache_key)
+```
+
+### Revocation Support by Scheme Type
+
+- **OAuth2/OIDC**: Supported if the provider has a revocation endpoint
+- **Service Account**: Generally not supported by providers
+- **API Key**: Not applicable (API keys must be deleted from the provider's management interface)
+
+## Event Callbacks
+
+The token manager supports callbacks for token lifecycle events:
+
+Each callback receives a single data Hash (keys include `:event`, `:token`,
+`:scheme`, `:credential`, plus `:error` for `:refresh_failure` and `:cache_key`
+for `:invalidated`).
+
+```ruby
+# Register a callback for token refresh
+token_manager.on(:refresh_success) do |data|
+  # data[:token] is the new token
+end
+
+# Register a callback for token refresh failure
+token_manager.on(:refresh_failure) do |data|
+  # data[:error] is the failure
+end
+
+# Register a callback for approaching expiration
+token_manager.on(:before_expiry) do |data|
+  # data[:token] is approaching expiry
+end
+
+# Register a callback for token invalidation
+token_manager.on(:invalidated) do |data|
+  # data[:cache_key] is the invalidated key
+end
+```
+
+## Advanced Configuration
+
+### Custom Token Store
+
+```ruby
+# Create a custom token store
+class CustomTokenStore
+  def store(key, token)
+    # Store the token
+  end
+  
+  def get(key)
+    # Retrieve the token
+  end
+  
+  def clear(key)
+    # Clear the token
+  end
+end
+
+# Use the custom token store
+token_store = CustomTokenStore.new
+token_manager = Legate::Auth::TokenManager.new(token_store)
+```
+
+### Background Token Refresh
+
+```ruby
+# Enable background token refresh
+token_manager = Legate::Auth::TokenManager.new(token_store, {
+  background_refresh: true
+})
+
+# This will refresh tokens in a background thread
+```
+
+## Best Practices
+
+1. **Minimize Token Requests**: Cache tokens until they're close to expiration
+2. **Handle Refresh Failures**: Implement retry logic with backoff
+3. **Secure Storage**: Tokens are not encrypted by `TokenStore`; apply the opt-in `Legate::Auth::Encryption` module if you need at-rest encryption
+4. **Revoke Unused Tokens**: Explicitly revoke tokens when they're no longer needed
+5. **Monitor Token Usage**: Track token usage for security auditing
+
+## Troubleshooting
+
+### Token Refresh Failures
+
+If token refresh fails, check:
+- The refresh token hasn't expired or been revoked
+- The token endpoint is accessible
+- The client credentials are still valid
+- Network connectivity to the provider
+
+### Token Storage Issues
+
+If tokens aren't being properly stored:
+- Verify the session service is properly initialized and passed to `TokenStore.new`
+- Ensure session persistence between requests
+- If you added opt-in `Legate::Auth::Encryption`, verify the key is consistent across instances
+
+### Performance Considerations
+
+- Token refresh can add latency to requests
+- Use the refresh buffer to refresh tokens before they expire
+- Consider background refresh for critical applications
+
+## Next Steps
+
+- [OAuth2 Authentication](./oauth2) - Learn more about OAuth2 authentication flows
+- [Service Account Authentication](./service_account) - Use service accounts for server-to-server authentication
+- [Secure Credential Storage](./secure_storage) - Best practices for credential security
+
+## Related Topics
+- [OAuth2 Authentication](./oauth2) - Learn more about OAuth2 authentication flows
+- [Service Account Authentication](./service_account) - Use service accounts for server-to-server authentication
+- [Secure Credential Storage](./secure_storage) - Best practices for credential security