legate 0.1.0

data/public/docs/authentication/api_reference/schemes/openid_connect.md

@@ -0,0 +1,311 @@
+# Legate::Auth::Schemes::OpenIDConnect
+
+The `OpenIDConnect` class implements the OpenID Connect (OIDC) authentication scheme, which provides a layer of identity verification on top of OAuth 2.0 protocols. It extends the `OAuth2` scheme class. It is also available via the `OIDC` alias.
+
+## Overview
+
+OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol. It allows clients to verify the identity of end-users based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end-user in an interoperable and REST-like manner.
+
+## Class Methods
+
+### `new`
+
+Creates a new OpenID Connect authentication scheme.
+
+**Parameters:**
+- Inherits all parameters from `OAuth2.new` (authorization_url, token_url, scopes, use_pkce, etc.)
+- `discovery_url` (String, optional keyword): The OIDC discovery endpoint URL
+- `jwks_url` (String, optional keyword): The JSON Web Key Set URI for token validation
+- `userinfo_url` (String, optional keyword): The userinfo endpoint URL
+- `issuer` (String, optional keyword): The OIDC issuer URL
+- `provider_uri` (String, optional keyword): The provider URI
+- `client_id` (String, optional keyword): The client ID for the OIDC provider
+- `**kwargs` (Hash): Additional parameters for the authentication scheme
+
+**Examples:**
+
+```ruby
+# Create a basic OIDC scheme with discovery
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://accounts.google.com/.well-known/openid-configuration',
+  scopes: ['openid', 'email', 'profile']
+)
+
+# With explicit endpoint configuration
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  authorization_url: 'https://login.microsoftonline.com/tenant-id/oauth2/v2.0/authorize',
+  token_url: 'https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token',
+  userinfo_url: 'https://graph.microsoft.com/oidc/userinfo',
+  jwks_url: 'https://login.microsoftonline.com/tenant-id/discovery/v2.0/keys',
+  scopes: ['openid', 'email', 'profile', 'offline_access']
+)
+```
+
+## Instance Methods
+
+### `scheme_type`
+
+Returns the type of the authentication scheme.
+
+**Returns:**
+- Symbol: `:openid_connect`
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::OpenIDConnect.new
+scheme.scheme_type  # => :openid_connect
+```
+
+### `validate!`
+
+Validates the scheme configuration.
+
+**Raises:**
+- `Legate::Auth::SchemeValidationError`: If the scheme configuration is invalid (e.g. missing `authorization_url` or `token_url`)
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://accounts.google.com/.well-known/openid-configuration',
+  token_url: 'https://oauth2.googleapis.com/token'
+)
+scheme.validate!
+```
+
+### `build_authorization_uri`
+
+Builds the authorization URL for the OpenID Connect flow. Includes OIDC-specific parameters like nonce.
+
+**Parameters:**
+- `config` (Legate::Auth::Config): The authentication configuration
+- `redirect_uri` (String, optional): The redirect URI for the callback
+- `state` (String, optional): The state parameter for CSRF protection
+
+**Returns:**
+- String: The authorization URL for the OIDC flow
+
+**Examples:**
+
+```ruby
+config = Legate::Auth::Config.new(scheme: scheme, credential: credential)
+auth_url = scheme.build_authorization_uri(
+  config,
+  'http://localhost:3000/auth/callback',
+  SecureRandom.hex(16)
+)
+```
+
+### `apply_to_request`
+
+Applies OIDC authentication to a request (inherited from OAuth2).
+
+**Parameters:**
+- `request` (Hash): The request to authenticate
+- `credential` (Legate::Auth::ExchangedCredential): The exchanged credential
+
+**Returns:**
+- Hash: The authenticated request with access token in the Authorization header
+
+### `exchange_token`
+
+Exchanges an authorization code for OIDC tokens (access token, ID token, and optional refresh token).
+
+**Parameters:**
+- `config` (Legate::Auth::Config): The authentication configuration
+- `credential` (Legate::Auth::Credential): The credential containing client information
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The exchanged tokens
+
+**Examples:**
+
+```ruby
+token = scheme.exchange_token(config, credential)
+
+puts token[:access_token]  # => "access-token"
+puts token[:id_token]      # => "id-token-jwt"
+puts token[:refresh_token] # => "refresh-token" (if granted)
+```
+
+### `discover_endpoints`
+
+Discovers OIDC endpoints from the discovery URL.
+
+**Returns:**
+- Hash: The discovered endpoint configuration
+
+### `get_userinfo`
+
+Retrieves user information from the OIDC userinfo endpoint.
+
+**Parameters:**
+- `access_token` (String): The access token to use for the userinfo request
+
+**Returns:**
+- Hash: The user information retrieved from the userinfo endpoint
+
+**Examples:**
+
+```ruby
+user_info = scheme.get_userinfo(token[:access_token])
+
+puts "User ID: #{user_info['sub']}"
+puts "Email: #{user_info['email']}"
+puts "Name: #{user_info['name']}"
+```
+
+### `verify_id_token`
+
+Verifies the ID token from the OIDC provider.
+
+**Parameters:**
+- `id_token` (String): The ID token to verify
+- `nonce` (String, optional): The nonce used in the authorization request
+- `audience` (String, optional): The expected audience for the token
+
+**Returns:**
+- Hash: The decoded and verified ID token claims
+
+**Raises:**
+- `Legate::Auth::TokenVerificationError`: If the ID token is invalid (signature, claim, or nonce mismatch)
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://accounts.google.com/.well-known/openid-configuration',
+  client_id: 'my-client-id'
+)
+
+begin
+  claims = scheme.verify_id_token(id_token, 'original-nonce-value')
+  puts "Authenticated user: #{claims['sub']}"
+  puts "Email: #{claims['email']}"
+rescue Legate::Auth::TokenVerificationError => e
+  puts "ID token verification failed: #{e.message}"
+end
+```
+
+### `to_h`
+
+Converts the scheme to a hash representation.
+
+**Returns:**
+- Hash: A hash representation of the scheme configuration
+
+## Usage Examples
+
+### Complete OIDC Authorization Flow
+
+```ruby
+require 'securerandom'
+
+# Step 1: Create the OIDC scheme
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://accounts.google.com/.well-known/openid-configuration',
+  scopes: ['openid', 'email', 'profile']
+)
+
+# Step 2: Set up credential with client details
+credential = Legate::Auth::Credential.new(
+  auth_type: :oidc,
+  client_id: ENV['OIDC_CLIENT_ID'],
+  client_secret: ENV['OIDC_CLIENT_SECRET']
+)
+
+# Step 3: Create config and build authorization URI
+config = Legate::Auth::Config.new(scheme: scheme, credential: credential)
+state = SecureRandom.hex(16)
+auth_url = config.build_authorization_uri(
+  'http://localhost:3000/auth/callback',
+  state
+)
+
+# Step 4: Redirect user to auth_url
+# redirect_to auth_url
+
+# Step 5: Handle the callback
+config.response_uri = "http://localhost:3000/auth/callback?code=12345&state=#{state}"
+token = scheme.exchange_token(config, credential)
+
+# Step 6: Verify ID token
+claims = scheme.verify_id_token(token[:id_token])
+
+# Step 7: Get user info
+user_info = scheme.get_userinfo(token[:access_token])
+
+# Step 8: Create user session
+session[:user_id] = claims['sub']
+session[:user_email] = claims['email']
+```
+
+### Using with Token Manager
+
+```ruby
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://accounts.google.com/.well-known/openid-configuration'
+)
+
+credential = Legate::Auth::Credential.new(
+  auth_type: :oidc,
+  client_id: 'ENV:OIDC_CLIENT_ID',
+  client_secret: 'ENV:OIDC_CLIENT_SECRET'
+)
+
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# Get a token (will auto-refresh if expired)
+token = token_manager.get_token(scheme, credential)
+```
+
+## Provider-Specific Configurations
+
+### Google
+
+```ruby
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://accounts.google.com/.well-known/openid-configuration',
+  scopes: ['openid', 'email', 'profile']
+)
+```
+
+### Microsoft Azure AD / Entra ID
+
+```ruby
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  authorization_url: 'https://login.microsoftonline.com/tenant-id/oauth2/v2.0/authorize',
+  token_url: 'https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token',
+  userinfo_url: 'https://graph.microsoft.com/oidc/userinfo',
+  scopes: ['openid', 'email', 'profile', 'offline_access']
+)
+```
+
+### Auth0
+
+```ruby
+scheme = Legate::Auth::Schemes::OpenIDConnect.new(
+  discovery_url: 'https://your-tenant.auth0.com/.well-known/openid-configuration',
+  scopes: ['openid', 'email', 'profile', 'offline_access']
+)
+```
+
+## Security Considerations
+
+- Store tokens securely; for at-rest encryption use the opt-in [`Legate::Auth::Encryption`](../encryption) module (TokenStore does not encrypt)
+- Always validate the ID token's signature and claims
+- Use state parameters to prevent CSRF attacks
+- Use nonce parameters to prevent replay attacks
+- Implement proper token lifecycle management, including expiration
+- Consider using PKCE for additional security
+- Always use HTTPS for all OIDC-related communications
+
+## See Also
+
+- [Legate::Auth::Schemes::OAuth2](./oauth2)
+- [Legate::Auth::Credential](../credential)
+- [Legate::Auth::ExchangedCredential](../exchanged_credential)
+- [Legate::Auth::Scheme](../scheme)
+- [Legate::Auth::TokenManager](../token_manager)

data/public/docs/authentication/api_reference/schemes/service_account.md

@@ -0,0 +1,287 @@
+# Legate::Auth::Schemes::ServiceAccount
+
+The `ServiceAccount` class implements service account authentication, which allows applications to authenticate with APIs using key-based credentials rather than user credentials. This authentication scheme is designed for server-to-server and automated workflows where no user interaction is required.
+
+## Overview
+
+Service account authentication uses cryptographic key pairs (usually RSA) to sign authentication tokens that are then exchanged for access tokens. The service account scheme in Legate Ruby provides a flexible foundation for implementing various service account authentication methods, with provider-specific implementations available for common cloud services.
+
+## Class Methods
+
+### `new`
+
+Creates a new service account authentication scheme.
+
+**Parameters:**
+- `token_url` (String, optional keyword): The token endpoint URL where the service account credentials are exchanged for tokens
+- `audience` (String, optional keyword): The target audience for the service account tokens
+- `scopes` (Array<String>, optional keyword): The scopes to request for the service account
+- `token_lifetime` (Integer, optional keyword): The lifetime of the token in seconds (default: 3600)
+- `client_email` (String, optional keyword): The service account client email
+- `private_key` (String, optional keyword): The private key for signing JWTs
+- `private_key_id` (String, optional keyword): The private key ID
+- `config` (Hash, optional keyword): Additional configuration (default: {})
+
+**Examples:**
+
+```ruby
+# Create a basic service account scheme
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://provider.com/oauth2/token',
+  audience: 'https://api.example.com',
+  scopes: ['https://api.example.com/auth/read', 'https://api.example.com/auth/write']
+)
+
+# With custom token lifetime
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://provider.com/oauth2/token',
+  audience: 'https://api.example.com',
+  token_lifetime: 1800  # 30 minutes
+)
+```
+
+## Instance Methods
+
+### `scheme_type`
+
+Returns the type of the authentication scheme.
+
+**Returns:**
+- Symbol: `:service_account`
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::ServiceAccount.new
+scheme.scheme_type  # => :service_account
+```
+
+### `validate!`
+
+Validates the scheme configuration.
+
+**Raises:**
+- `Legate::Auth::SchemeValidationError`: If the scheme configuration is invalid
+
+**Examples:**
+
+```ruby
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://provider.com/oauth2/token'
+)
+scheme.validate!
+```
+
+### `apply_to_request`
+
+Applies service account authentication to a request by adding the access token to the Authorization header.
+
+**Parameters:**
+- `request` (Hash): The request to authenticate
+- `credential` (Legate::Auth::ExchangedCredential): The exchanged credential containing the access token
+
+**Returns:**
+- Hash: The authenticated request with access token in the Authorization header
+
+**Examples:**
+
+```ruby
+request = { headers: {} }
+authenticated = scheme.apply_to_request(request, exchanged_credential)
+puts authenticated[:headers]['Authorization']  # => "Bearer [access-token]"
+```
+
+### `fetch_token`
+
+Fetches a token from the token endpoint using a signed JWT.
+
+**Parameters:**
+- `credential` (Legate::Auth::Credential): The credential containing the service account information
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The fetched token
+
+### `exchange_token`
+
+Exchanges a service account credential for an access token by creating and signing a JWT and exchanging it with the token endpoint.
+
+**Parameters:**
+- `credential` (Legate::Auth::Credential): The credential containing the service account information
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The exchanged token
+
+**Examples:**
+
+```ruby
+# Create a service account credential
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account-key.json')  # raw JSON string, not a parsed Hash
+)
+
+# Exchange for a token
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://provider.com/oauth2/token',
+  audience: 'https://api.example.com',
+  scopes: ['read', 'write']
+)
+token = scheme.exchange_token(credential)
+
+puts token[:access_token]  # => "[service-account-access-token]"
+```
+
+### `supports_refresh?`
+
+Returns `true` -- service account schemes always support token refresh by re-exchanging credentials.
+
+**Returns:**
+- Boolean: `true`
+
+### `refresh_token`
+
+Refreshes an expired service account token by performing a new token exchange.
+
+**Parameters:**
+- `token` (Legate::Auth::ExchangedCredential): The token to refresh
+- `credential` (Legate::Auth::Credential): The original credential
+
+**Returns:**
+- Legate::Auth::ExchangedCredential: The refreshed token
+
+**Examples:**
+
+```ruby
+refreshed_token = scheme.refresh_token(expired_token, credential)
+```
+
+### `create_signed_jwt`
+
+Creates a signed JWT assertion for the service account.
+
+**Parameters:**
+- `service_account_key` (Hash, optional): The service account key to use for signing (default: nil, uses configured key)
+
+**Returns:**
+- String: The signed JWT assertion
+
+**Examples:**
+
+```ruby
+jwt = scheme.create_signed_jwt
+puts jwt  # => "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+### `to_h`
+
+Converts the scheme to a hash representation.
+
+**Returns:**
+- Hash: A hash representation of the scheme configuration
+
+## Usage Examples
+
+### Basic Authentication Flow
+
+```ruby
+# Create a Service Account scheme
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://provider.com/oauth2/token',
+  audience: 'https://api.example.com',
+  scopes: ['read', 'write']
+)
+
+# Create a credential from a service account key file
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account-key.json')  # raw JSON string, not a parsed Hash
+)
+
+# Exchange the credential for a token
+token = scheme.exchange_token(credential)
+
+# Apply to a request
+request = { headers: {} }
+authenticated = scheme.apply_to_request(request, token)
+puts authenticated[:headers]['Authorization']  # => "Bearer [access-token]"
+```
+
+### With Token Manager
+
+```ruby
+# Create a Service Account scheme
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://provider.com/oauth2/token',
+  audience: 'https://api.example.com'
+)
+
+# Create a credential from a service account key file
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key: File.read('service-account-key.json')  # raw JSON string, not a parsed Hash
+)
+
+# Use with token manager for automatic token management
+token_store = Legate::Auth::TokenStore.new(session_service)
+token_manager = Legate::Auth::TokenManager.new(token_store)
+
+# Get a token (this will create, store, and refresh the token as needed)
+token = token_manager.get_token(scheme, credential)
+```
+
+### Using Key File from Path
+
+```ruby
+# Create a credential using a key file path
+credential = Legate::Auth::Credential.new(
+  auth_type: :service_account,
+  service_account_key_file: 'path/to/service-account-key.json'
+)
+
+# Create the scheme and use as normal
+scheme = Legate::Auth::Schemes::ServiceAccount.new(
+  token_url: 'https://provider.com/oauth2/token',
+  audience: 'https://api.example.com'
+)
+
+# Exchange for a token
+token = scheme.exchange_token(credential)
+```
+
+## Service Account Key Format
+
+A standard service account key JSON file typically contains:
+
+```json
+{
+  "type": "service_account",
+  "project_id": "your-project-id",
+  "private_key_id": "abcdef1234567890",
+  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n",
+  "client_email": "service-account@project-id.iam.gserviceaccount.com",
+  "client_id": "123456789012345678901",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token"
+}
+```
+
+The exact format may vary by service provider.
+
+## Security Considerations
+
+- Store service account keys securely and restrict access
+- Grant service accounts the minimum necessary permissions (principle of least privilege)
+- Regularly rotate service account keys
+- Monitor service account usage for suspicious activity
+- Avoid embedding service account keys in client-side code
+- Use environment variables or secure credential stores to manage service account keys
+- Always use HTTPS for transmitting service account tokens
+- Consider using shorter token lifetimes in high-security environments
+
+## See Also
+
+- [Legate::Auth::Schemes::GoogleServiceAccount](./google_service_account)
+- [Legate::Auth::Credential](../credential)
+- [Legate::Auth::ExchangedCredential](../exchanged_credential)
+- [Legate::Auth::Scheme](../scheme)
+- [Legate::Auth::TokenManager](../token_manager)