OAuth integrations
Built-in OAuth 2.0 integrations for secure third-party service connections.
OAuth integrations provide a secure way to connect to third-party services without exposing credentials in workflows or logs. All tokens are encrypted at rest and automatically refreshed when needed.
OAuth integrations are built-in connections to third-party services that handle the complete authentication flow automatically. Unlike action templates that require manual token management, OAuth integrations provide seamless, secure access to external APIs.
Key benefits:
- Secure credential storage - Client secrets and tokens are encrypted at rest
- Automatic token refresh - Expired tokens are refreshed in the background
- Dynamic scope management - Configure only the permissions you need
- Workspace isolation - Each workspace has separate integration configurations
OAuth grant types
Tracecat supports two OAuth 2.0 grant types for different authentication scenarios. The grant type must be selected when configuring each provider and affects both the authentication flow and available features.
Authorization Code Flow (Delegated User)
The standard OAuth flow where users are redirected to the provider to grant permissions. Best for:
- Delegated user access - Actions performed on behalf of a specific user
- Interactive authentication - Requires user consent and login
- Broad API access - Full access to user resources with appropriate scopes
Examples: Accessing a user’s Microsoft OneDrive files, sending Slack messages as a specific user
Client Credentials Flow (Service Account)
Direct machine-to-machine authentication using client credentials only. Best for:
- Service account access - Actions performed by the application itself
- Service authentication - No user interaction required
- System integration - Background processes and automated workflows
Examples: Organization-wide Microsoft Teams channel management, system-level GitHub repository access
Each provider requires a specific grant type to be selected during configuration. This choice determines:
- The authentication flow (user redirect vs direct authentication)
- Available API permissions and scopes
- Token refresh behavior
Some providers support both flows while others may only support one. The provider’s setup instructions will indicate which grant types are available.
Setting up OAuth integrations
Before configuring OAuth integrations in Tracecat, you must first create an OAuth application with your chosen provider (Microsoft, Google, GitHub, etc.). This process is the same for both Authorization Code and Client Credentials flows:
- Create OAuth application - Register a new application in your provider’s developer console
- Configure redirect URI - Set the callback URL that Tracecat will provide during setup
- Obtain credentials - Copy the client ID and client secret from your OAuth application
- Set permissions - Configure the required scopes and permissions for your use case
Each provider has specific setup requirements. Tracecat provides direct links to setup guides in the configuration interface for each OAuth integration.
Navigate to integrations
Go to your workspace and navigate to the integrations page. Select the OAuth provider you want to configure from the available list. Each grant type is defined as a separate OAuth integration - you can distinguish between them by the lock icon (Client Credentials) or user icon (Authorization Code) displayed on each integration tile. This allows you to configure multiple integrations for the same provider with different grant types and credentials.
Configure the provider
Configure the following settings for your selected provider:
- Client ID - OAuth application client ID from the provider
- Client Secret - OAuth application client secret (encrypted when saved)
- Additional Scopes - Custom scopes beyond the base requirements (optional)
Each provider includes setup instructions with links to their developer documentation. Follow the provider’s guide to create an OAuth application and obtain your client credentials.
Complete authentication
The authentication process depends on your selected grant type:
Authorization Code Flow
Click “Connect with OAuth” to complete the authorization:
This redirects you to the provider’s authorization page where you grant permissions to Tracecat.
Client Credentials Flow
Click “Fetch Token” to verify your client credentials. No user authorization is required - the connection uses your application’s credentials directly.
Verify connection
Once connected, the integration status shows as “Connected” with details about granted scopes and token expiration:
Managing scopes
OAuth integrations use a two-tier scope system:
Base scopes
Required permissions that every integration needs for basic functionality. These are automatically included and cannot be removed.
Additional scopes
Optional permissions you can add for extended functionality. Use the scope input to add custom scopes beyond the base requirements.
Only add scopes you actually need. Extra permissions increase security risk and may require additional approval from your organization.
Scope validation
Scope validation
Each provider defines allowed scope patterns to prevent invalid or potentially dangerous permissions.
If you enter an invalid scope, you’ll see a validation error with the expected patterns.
Common validation patterns:
- Microsoft Graph:
https://graph.microsoft.com/.default
or specific resource scopes - Google APIs: Service-specific scopes like
https://www.googleapis.com/auth/drive.readonly
- GitHub: Repository and organization permissions like
repo
,read:org
Integration status
OAuth integrations have three possible states:
Not Configured
No client credentials have been set up. Click “Configure Integration” to get started.
Configured
Client credentials are saved but authentication hasn’t been completed. For Authorization Code flow, click “Connect with OAuth”. For Client Credentials flow, click “Test Connection”.
Connected
Successfully authenticated and ready to use in workflows. For Authorization Code flow, tokens are automatically refreshed as needed.
Managing integrations
Once configured, you have two options for managing OAuth integrations:
Disconnect
Removes the OAuth tokens while preserving your configuration (client ID, secret, and scopes). Use this when:
- You want to re-authenticate with different permissions
- The current authentication has issues but you want to keep the configuration
- You need to switch which account is connected
Delete
Completely removes the integration including all configuration and tokens. Use this when:
- You no longer need the integration
- You want to set up with entirely different credentials
- You’re switching to a different OAuth application
Supported providers
Microsoft Graph
Access Office 365, Azure AD, and Microsoft services
Microsoft Teams
Channel management and team collaboration
Google Workspace
Connect to Gmail, Drive, Calendar, and Google services
GitHub
Repository management and organization access
Slack
Channel messaging and workspace integration
Don’t see your provider? OAuth integrations are extensible - check our contributing guide to learn how to add new providers.
Using in workflows
Once connected, OAuth integrations work seamlessly with action templates and Python UDFs. The integration handles token retrieval automatically - no need to manage credentials in your workflows.
The tools.microsoft_graph.list_drive_files
action automatically uses your connected OAuth integration for authentication.
Troubleshooting
Integration shows as expired
Integration shows as expired
OAuth tokens have limited lifespans. Tracecat automatically refreshes expired tokens using refresh tokens.
If refresh fails, you may need to re-authorize by clicking “Connect with OAuth” again.
Scope permission errors
Scope permission errors
If workflows fail with permission errors, check that your integration includes the required scopes.
You can update scopes in the configuration tab and re-authorize to grant additional permissions.
Provider connection fails
Provider connection fails
Verify your OAuth application configuration with the provider:
- Redirect URI matches the one shown in Tracecat
- Client ID and secret are correct
- OAuth application is enabled and published
Security considerations
OAuth integrations have access to external services with the permissions you grant. Follow security best practices:
- Only grant minimum required scopes
- Regularly review connected integrations
- Rotate client secrets periodically
- Monitor integration usage in audit logs
All OAuth credentials and tokens are encrypted using workspace-specific encryption keys. Tokens are never logged or exposed in workflow outputs for security.