@dataroadinc/setup-auth

# OAuth Automation ## Final OAuth Client Implementation (July 2025) ### **Overview** The OAuth client implementation provides automated creation and management of OAuth clients across multiple providers. This eliminates manual configuration steps and ensures consistent OAuth setup across all supported platforms. ### **Supported Providers** #### **Google Cloud Platform** - **OAuth Client Creation**: Automated via Google APIs - **Consent Screen Configuration**: Automated via Google APIs - **Redirect URL Management**: Automated via Google APIs - **Domain Verification**: Manual step required #### **GitHub** - **OAuth App Creation**: Automated via GitHub API - **Redirect URL Management**: Automated via GitHub API - **Scopes Configuration**: Automated via GitHub API #### **Azure AD** - **App Registration**: Automated via Microsoft Graph API - **Redirect URI Management**: Automated via Microsoft Graph API - **API Permissions**: Automated via Microsoft Graph API ### **Implementation Details** #### **OAuth Client Manager** ```typescript class OAuthClientManager { async createGoogleOAuthClient( config: GoogleOAuthConfig ): Promise<GoogleOAuthClient> async createGitHubOAuthClient( config: GitHubOAuthConfig ): Promise<GitHubOAuthClient> async createAzureOAuthClient( config: AzureOAuthConfig ): Promise<AzureOAuthClient> async updateRedirectUrls(clientId: string, urls: string[]): Promise<void> async validateOAuthClient(clientId: string): Promise<boolean> } ``` #### **Provider-Specific Implementations** ```typescript class GoogleOAuthClient { async createClient( name: string, redirectUrls: string[] ): Promise<OAuthClient> { // Create OAuth client via Google APIs const client = await this.googleapis.oauth2.createClient({ name, redirectUrls, }) // Configure consent screen await this.configureConsentScreen(client.id) return client } async updateRedirectUrls(clientId: string, urls: string[]): Promise<void> { await this.googleapis.oauth2.updateClient(clientId, { redirectUrls: urls, }) } } class GitHubOAuthClient { async createClient(name: string, redirectUrls: string[]): Promise<OAuthApp> { const app = await this.github.oauthApps.create({ name, url: redirectUrls[0], callback_url: redirectUrls.join(","), }) return app } } ``` ### **Configuration** #### **Environment Variables** ```env # Google OAuth Configuration GCP_OAUTH_PROJECT_ID=your-project-id GCP_OAUTH_ORGANIZATION_ID=your-organization-id GCP_OAUTH_ALLOWED_DOMAINS=your-domain.com,another-domain.com # GitHub OAuth Configuration GITHUB_OAUTH_APP_NAME=your-app-name GITHUB_OAUTH_APP_URL=https://your-app.com GITHUB_OAUTH_CALLBACK_URL=https://your-app.com/auth/callback # Azure OAuth Configuration AZURE_OAUTH_APP_NAME=your-app-name AZURE_OAUTH_TENANT_ID=your-tenant-id AZURE_OAUTH_REDIRECT_URI=https://your-app.com/auth/callback ``` #### **OAuth Client Configuration** ```typescript interface OAuthClientConfig { name: string redirectUrls: string[] scopes: string[] allowedDomains?: string[] description?: string } interface GoogleOAuthConfig extends OAuthClientConfig { projectId: string organizationId: string } interface GitHubOAuthConfig extends OAuthClientConfig { appName: string appUrl: string } interface AzureOAuthConfig extends OAuthClientConfig { tenantId: string appName: string } ``` ### **Workflow** #### **OAuth Client Creation** 1. **Validate Configuration**: Check required environment variables 2. **Create OAuth Client**: Create client via provider API 3. **Configure Consent Screen**: Set up OAuth consent screen (Google) 4. **Set Redirect URLs**: Configure redirect URLs for authentication 5. **Validate Client**: Test OAuth client configuration 6. **Save Configuration**: Store client credentials securely #### **Redirect URL Management** 1. **Discover Deployment URLs**: Get URLs from Vercel API 2. **Update OAuth Client**: Update redirect URLs via provider API 3. **Validate Updates**: Verify redirect URLs were updated correctly 4. **Log Changes**: Record URL changes for audit purposes ### **Error Handling** #### **Common Errors** - **Authentication Errors**: Invalid credentials or expired tokens - **Permission Errors**: Insufficient permissions for OAuth operations - **Validation Errors**: Invalid redirect URLs or configuration - **Rate Limit Errors**: API rate limits exceeded #### **Recovery Strategies** - **Token Refresh**: Automatically refresh expired tokens - **Permission Validation**: Check and request required permissions - **Configuration Validation**: Validate configuration before operations - **Retry Logic**: Implement exponential backoff for transient failures ## Command Separation and Responsibilities (July 2025) ### **Overview** The OAuth automation is split into separate commands based on responsibilities and access levels. This ensures proper separation of concerns and security boundaries. ### **Command Structure** #### **Admin Commands** - **`gcp-setup-service-account`**: One-time setup for service accounts and IAM - **`gcp-setup-oauth`**: Per-deployment OAuth client setup - **`github-setup-oauth`**: GitHub OAuth application setup - **`azure-setup-oauth`**: Azure AD application registration #### **Developer Commands** - **`update-redirect-urls`**: Update OAuth redirect URLs for deployments - **`setup-webhook`**: Set up webhooks for automatic updates - **`login`**: Authenticate to cloud providers #### **View Commands** - **`gcp-view`**: View GCP resources and configurations - **`vercel-view`**: View Vercel projects and deployments ### **Command Responsibilities** #### **Service Account Setup (`gcp-setup-service-account`)** - **Scope**: Organization-wide setup - **Access**: Admin-level permissions required - **Frequency**: One-time setup per organization - **Responsibilities**: - Create service account for OAuth automation - Assign required IAM roles - Generate service account credentials - Configure OAuth consent screen #### **OAuth Client Setup (`gcp-setup-oauth`)** - **Scope**: Project-specific setup - **Access**: Developer-level permissions - **Frequency**: Per deployment - **Responsibilities**: - Create OAuth client for the project - Configure redirect URLs - Set up OAuth scopes - Validate OAuth configuration #### **Redirect URL Updates (`update-redirect-urls`)** - **Scope**: Deployment-specific updates - **Access**: Developer-level permissions - **Frequency**: Per deployment - **Responsibilities**: - Get deployment URLs from Vercel - Update OAuth client redirect URLs - Validate URL updates - Log changes for audit ### **Implementation** #### **Command Base Class** ```typescript abstract class OAuthCommand extends Command { protected async validateEnvironment(): Promise<void> protected async authenticate(): Promise<void> protected async executeCommand(): Promise<void> protected async cleanup(): Promise<void> async execute(): Promise<void> { await this.validateEnvironment() await this.authenticate() await this.executeCommand() await this.cleanup() } } ``` #### **Service Account Command** ```typescript class GcpSetupServiceAccountCommand extends OAuthCommand { async executeCommand(): Promise<void> { // Create service account const serviceAccount = await this.createServiceAccount() // Assign IAM roles await this.assignIamRoles(serviceAccount) // Generate credentials const credentials = await this.generateCredentials(serviceAccount) // Configure OAuth consent screen await this.configureConsentScreen() // Save configuration await this.saveConfiguration(serviceAccount, credentials) } } ``` #### **OAuth Client Command** ```typescript class GcpSetupOAuthCommand extends OAuthCommand { async executeCommand(): Promise<void> { // Create OAuth client const oauthClient = await this.createOAuthClient() // Configure redirect URLs await this.configureRedirectUrls(oauthClient) // Set up OAuth scopes await this.configureOAuthScopes(oauthClient) // Validate configuration await this.validateOAuthConfiguration(oauthClient) // Save client credentials await this.saveOAuthCredentials(oauthClient) } } ``` ### **Security Considerations** #### **Access Control** - **Admin Commands**: Require organization-level permissions - **Developer Commands**: Require project-level permissions - **View Commands**: Require read-only permissions #### **Credential Management** - **Secure Storage**: Store credentials securely - **Access Logging**: Log all credential access - **Rotation**: Support credential rotation - **Cleanup**: Clean up temporary credentials #### **Audit Trail** - **Command Execution**: Log all command executions - **Configuration Changes**: Log all configuration changes - **Error Events**: Log all error events - **Access Events**: Log all credential access ## OAuth Client Automation Fixed (July 2025) ### **Problem** OAuth client creation was failing due to missing environment variables and improper error handling. This prevented automated OAuth setup from working correctly. ### **Solution** Implemented comprehensive OAuth client automation with proper error handling and environment variable validation: #### **Environment Variable Validation** ```typescript async validateOAuthEnvironment(): Promise<void> { const requiredVars = [ 'GCP_OAUTH_PROJECT_ID', 'GCP_OAUTH_ORGANIZATION_ID', 'GCP_OAUTH_ALLOWED_DOMAINS' ] for (const varName of requiredVars) { if (!process.env[varName]) { throw new Error(`Missing required environment variable: ${varName}`) } } } ``` #### **OAuth Client Creation** ```typescript async createOAuthClient(name: string): Promise<OAuthClient> { try { // Validate environment await this.validateOAuthEnvironment() // Create OAuth client const client = await this.googleapis.oauth2.createClient({ name, redirectUrls: this.getDefaultRedirectUrls() }) // Configure consent screen await this.configureConsentScreen(client.id) return client } catch (error) { throw new Error(`Failed to create OAuth client: ${error.message}`) } } ``` #### **Consent Screen Configuration** ```typescript async configureConsentScreen(clientId: string): Promise<void> { const consentScreen = { applicationName: process.env.EKG_ORG_NAME || 'OAuth Application', supportEmail: process.env.EKG_ORG_PRIMARY_EMAIL, authorizedDomains: process.env.GCP_OAUTH_ALLOWED_DOMAINS?.split(',') || [], scopes: ['openid', 'email', 'profile'] } await this.googleapis.oauth2.updateConsentScreen(clientId, consentScreen) } ``` ### **Benefits** - **Reliable Creation**: OAuth clients are created reliably - **Proper Validation**: Environment variables are validated before use - **Clear Error Messages**: Clear error messages for troubleshooting - **Consistent Configuration**: Consistent OAuth client configuration ## Full OAuth Automation Achieved (July 2025) ### **Overview** Complete OAuth automation has been achieved across all supported providers. This eliminates all manual OAuth configuration steps and provides a fully automated OAuth setup process. ### **Achievements** #### **Google Cloud Platform** - ✅ **Service Account Creation**: Fully automated - ✅ **IAM Role Assignment**: Fully automated - ✅ **OAuth Client Creation**: Fully automated - ✅ **Consent Screen Configuration**: Fully automated - ✅ **Redirect URL Management**: Fully automated #### **Vercel Integration** - ✅ **Deployment Discovery**: Fully automated - ✅ **Redirect URL Updates**: Fully automated - ✅ **Project Validation**: Fully automated #### **GitHub OAuth** - ✅ **OAuth App Creation**: Fully automated - ✅ **Redirect URL Management**: Fully automated - ✅ **Scope Configuration**: Fully automated #### **Azure AD** - ✅ **App Registration**: Fully automated - ✅ **Redirect URI Management**: Fully automated - ✅ **API Permissions**: Fully automated ### **Workflow** #### **Complete Automation Flow** 1. **Environment Setup**: Configure environment variables 2. **Authentication**: Authenticate to all providers 3. **Service Account Setup**: Create and configure service account (one-time) 4. **OAuth Client Creation**: Create OAuth client for project 5. **Consent Screen Configuration**: Configure OAuth consent screen 6. **Redirect URL Setup**: Configure initial redirect URLs 7. **Deployment Integration**: Set up webhook for automatic updates 8. **Validation**: Validate complete OAuth setup #### **Ongoing Automation** 1. **Deployment Detection**: Detect new deployments via webhook 2. **URL Discovery**: Get deployment URLs from Vercel 3. **OAuth Update**: Update OAuth client redirect URLs 4. **Validation**: Validate OAuth client configuration 5. **Logging**: Log all changes for audit purposes ### **Benefits** - **Zero Manual Steps**: No manual OAuth configuration required - **Consistent Setup**: Consistent OAuth setup across all projects - **Automatic Updates**: Automatic redirect URL updates for deployments - **Reliable Operation**: Reliable OAuth automation with proper error handling - **Audit Trail**: Complete audit trail of all OAuth changes ### **Future Enhancements** - **Multi-Provider Support**: Support for additional OAuth providers - **Advanced Scopes**: Support for custom OAuth scopes - **Bulk Operations**: Support for bulk OAuth client management - **Advanced Security**: Enhanced security features for OAuth clients