Skip to main content
The CrewAI Built-in Integrations service provides secure authentication and token management for third-party integrations including Gmail, Google Calendar, Microsoft Outlook, and other services. It operates as a separate microservice with its own database for storing encrypted OAuth tokens.

​
Core Configuration

​
oauth.enabled
boolean
default:"false"
Enable or disable the Built-in Integrations service deployment.Purpose: Controls whether the Built-in Integrations service and its associated resources (Deployment, Service, Ingress) are deployed to the cluster.When Enabled:
  • Deploys Built-in Integrations service pods
  • Creates Built-in Integrations ClusterIP service
  • Optionally creates Ingress for external OAuth callbacks
  • Automatically configures Rails application with Built-in Integrations service URL
When Disabled:
  • No Built-in Integrations service resources deployed
  • Third-party integrations unavailable
  • OAuth-related secrets still created but unused
Example:
oauth:
  enabled: true
​
oauth.name
string
default:"oauth"
Component name for the Built-in Integrations service.Purpose: Used for resource naming and labeling. Generally should not be changed.
​
oauth.replicaCount
integer
default:"2"
Number of Built-in Integrations service pod replicas.High Availability: Multiple replicas ensure Built-in Integrations service availability during rolling updates and pod failures.Recommendations:
  • Development: 1
  • Production: 2 or more for high availability
  • High-traffic: 3-5 based on load
Example:
oauth:
  replicaCount: 3
​
oauth.port
integer
default:"8787"
Container port for the Built-in Integrations service.Default: 8787Note: This is the internal container port. External access is configured via Ingress.

​
Image Configuration

​
oauth.image.host
string
default:""
Container registry hostname for the Built-in Integrations service image.Default Behavior: If empty, falls back to global.imageRegistry.Example:
oauth:
  image:
    host: "images.crewai.com"
​
oauth.image.name
string
default:"proxy/crewai/crewai/crewai-oauth"
Built-in Integrations service image name.Default: "proxy/crewai/crewai/crewai-oauth"Note: The image name includes the full path to the Built-in Integrations service container image.
​
oauth.image.tag
string
default:"0.1-pre"
Built-in Integrations service image tag.Default: "0.1-pre"Production Recommendation: Use specific version tags for reproducible deployments.Example:
oauth:
  image:
    tag: "0.1-pre"
​
oauth.image.pullPolicy
string
default:"IfNotPresent"
Image pull policy for Built-in Integrations service.Valid Values:
  • "IfNotPresent" - Pull only if not cached locally
  • "Always" - Always pull latest image
  • "Never" - Never pull, use cached only
Default: "IfNotPresent"
​
oauth.image.pullSecret
string
default:""
Kubernetes secret name for Built-in Integrations service image registry authentication.Default Behavior: If empty, falls back to image.pullSecret.Example:
oauth:
  image:
    pullSecret: "my-registry-secret"

​
Service Configuration

​
oauth.service.type
string
default:"ClusterIP"
Kubernetes service type for Built-in Integrations service.Default: "ClusterIP"Recommendation: Keep as ClusterIP and use Ingress for external access.Valid Values:
  • "ClusterIP" - Internal cluster access only (recommended)
  • "LoadBalancer" - External LoadBalancer (not recommended, use Ingress instead)
  • "NodePort" - Node port access (not recommended for production)
​
oauth.service.port
integer
default:"8787"
Service port for Built-in Integrations service.Default: 8787Note: This is the service port that other services use to communicate with the Built-in Integrations service internally.
​
oauth.service.targetPort
integer
default:"8787"
Target port on Built-in Integrations service pods.Default: 8787Note: Should match oauth.port.

​
Resource Limits

​
oauth.resources
object
CPU and memory resource requests and limits for Built-in Integrations service pods.Default Configuration:
resources:
  limits:
    cpu: "500m"
    memory: "512Mi"
  requests:
    cpu: "250m"
    memory: "256Mi"
Tuning Guidelines:Low Traffic (< 100 users):
resources:
  limits:
    cpu: "500m"
    memory: "512Mi"
  requests:
    cpu: "250m"
    memory: "256Mi"
Medium Traffic (100-500 users):
resources:
  limits:
    cpu: "1"
    memory: "1Gi"
  requests:
    cpu: "500m"
    memory: "512Mi"
High Traffic (500+ users):
resources:
  limits:
    cpu: "2"
    memory: "2Gi"
  requests:
    cpu: "1"
    memory: "1Gi"

​
Health Probes

​
oauth.livenessProbe
object
Liveness probe configuration for Built-in Integrations service.Purpose: Kubernetes restarts the container if the liveness probe fails, recovering from deadlocks or hung processes.Default Configuration:
livenessProbe:
  initialDelaySeconds: 30
  periodSeconds: 30
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3
Probe Details:
  • Endpoint: GET /health on port 8787
  • Initial Delay: 30 seconds (allows service startup time)
  • Check Interval: Every 30 seconds
  • Timeout: 5 seconds per check
  • Failure Threshold: 3 consecutive failures trigger restart
​
oauth.readinessProbe
object
Readiness probe configuration for Built-in Integrations service.Purpose: Kubernetes removes the pod from service load balancing if the readiness probe fails, preventing traffic to unhealthy pods.Default Configuration:
readinessProbe:
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3
Probe Details:
  • Endpoint: GET /health on port 8787
  • Initial Delay: 5 seconds
  • Check Interval: Every 10 seconds
  • Timeout: 5 seconds per check
  • Failure Threshold: 3 consecutive failures mark pod as not ready

​
Node Placement

​
oauth.nodeSelector
object
default:"{}"
Node selector labels for Built-in Integrations service pod placement.Default: {} (no node selector, schedule on any node)Use Cases:
  • Dedicated node pools for services
  • GPU or specialized hardware requirements
  • Cost optimization (spot/preemptible instances)
  • Compliance requirements (data locality)
Example:
oauth:
  nodeSelector:
    workload: services
    tier: backend

​
Ingress Configuration

The Built-in Integrations service requires external access for OAuth provider callbacks (redirects from Google, Microsoft, etc.). Ingress configuration provides secure HTTPS access to OAuth endpoints.
​
oauth.ingress.enabled
boolean
default:"false"
Enable Ingress for Built-in Integrations service external access.Default: falseRequired For: OAuth provider callbacks to work correctly.When Enabled:
  • Creates Ingress resource for OAuth endpoints
  • OAuth providers can send callbacks to your domain
  • Uses oauth.ingress.host or falls back to envVars.APPLICATION_HOST
When Disabled:
  • OAuth callbacks will fail
  • Third-party integrations cannot complete authentication flow
Important: OAuth callbacks require a publicly accessible HTTPS endpoint. If disabled, OAuth integrations will not function.
​
oauth.ingress.className
string
default:"nginx"
Ingress controller class name.Valid Values:
  • "nginx" - NGINX Ingress Controller
  • "alb" - AWS Application Load Balancer
Default: "nginx"
​
oauth.ingress.host
string
default:""
Hostname for Built-in Integrations service external access.Default Behavior: If empty, falls back to envVars.APPLICATION_HOST.Format: Fully qualified domain name (FQDN)Important:
  • Must be configured in DNS to point to your Ingress controller
  • Must match OAuth provider callback configuration
  • Requires valid TLS certificate for HTTPS
Example with Dedicated Subdomain:
oauth:
  ingress:
    enabled: true
    host: "oauth.crewai.company.com"
Example with Shared Domain (using fallback):
oauth:
  ingress:
    enabled: true
    host: ""  # Falls back to APPLICATION_HOST
Path Configuration:The OAuth service is automatically exposed at the /oauthsvc path prefix. When using NGINX Ingress Controller, the chart configures automatic path rewriting and optimized buffer sizes for OAuth flows.
​
oauth.ingress.annotations
object
default:"{}"
Additional annotations for the OAuth Ingress resource.Purpose: Advanced Ingress controller configuration not covered by built-in settings.Example:
oauth:
  ingress:
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      nginx.ingress.kubernetes.io/rate-limit: "100"

​
AWS ALB Configuration

​
oauth.ingress.alb.scheme
string
default:"internet-facing"
AWS ALB scheme when using ALB Ingress controller.Valid Values:
  • "internet-facing" - Public internet access (required for OAuth)
  • "internal" - VPC-internal only
Default: "internet-facing"Note: OAuth callbacks require public internet access from OAuth providers.
​
oauth.ingress.alb.targetType
string
default:"ip"
AWS ALB target type.Valid Values:
  • "ip" - Target pods by IP (recommended for most cases)
  • "instance" - Target EC2 instances via NodePort
Default: "ip"
​
oauth.ingress.alb.certificateArn
string
default:""
AWS ACM certificate ARN for HTTPS.Required: Yes (for ALB with HTTPS)Format: arn:aws:acm:region:account:certificate/idExample:
oauth:
  ingress:
    className: alb
    alb:
      certificateArn: "arn:aws:acm:us-west-2:123456789012:certificate/abc-def-123"
​
oauth.ingress.alb.sslPolicy
string
default:"ELBSecurityPolicy-TLS-1-2-2017-01"
AWS ALB SSL policy.Default: "ELBSecurityPolicy-TLS-1-2-2017-01"Other Options:
  • "ELBSecurityPolicy-TLS13-1-2-2021-06" - TLS 1.3 and 1.2
  • "ELBSecurityPolicy-FS-1-2-2019-08" - Forward secrecy
Recommendation: Use TLS 1.2 minimum for security.

​
NGINX Ingress Configuration

​
oauth.ingress.nginx.sslRedirect
boolean
default:"true"
Redirect HTTP to HTTPS automatically.Default: trueRecommendation: Keep enabled for security. OAuth requires HTTPS.
​
oauth.ingress.nginx.proxyBodySize
string
default:"10m"
Maximum request body size.Default: "10m" (10 megabytes)Purpose: Limits size of OAuth requests and responses.
​
oauth.ingress.nginx.enableCors
boolean
default:"true"
Enable CORS (Cross-Origin Resource Sharing).Default: truePurpose: Allows Built-in Integrations service to be called from web application hosted on different subdomain.
​
oauth.ingress.nginx.corsAllowMethods
string
default:"GET, POST, OPTIONS"
Allowed HTTP methods for CORS requests.Default: "GET, POST, OPTIONS"Note: OAuth flows primarily use GET and POST methods.
​
oauth.ingress.nginx.corsAllowHeaders
string
Allowed HTTP headers for CORS requests.Default: Standard headers for OAuth and API requests.
​
oauth.ingress.nginx.corsAllowOrigin
string
default:"*"
Allowed origins for CORS requests.Default: "*" (allow all origins)Security Note: For production, consider restricting to specific domains:
oauth:
  ingress:
    nginx:
      corsAllowOrigin: "https://crewai.company.com"
​
oauth.ingress.nginx.corsAllowCredentials
boolean
default:"true"
Allow credentials (cookies, authorization headers) in CORS requests.Default: truePurpose: Required for OAuth cookie-based authentication.
​
oauth.ingress.nginx.tls.enabled
boolean
default:"false"
Enable TLS termination at NGINX.Default: falseWhen Enabled: Requires TLS certificate in Kubernetes secret specified by oauth.ingress.nginx.tls.secretName.Example:
oauth:
  ingress:
    nginx:
      tls:
        enabled: true
        secretName: "oauth-tls-cert"
​
oauth.ingress.nginx.tls.secretName
string
default:""
Kubernetes secret name containing TLS certificate and key.Required When: oauth.ingress.nginx.tls.enabled: trueSecret Format:
apiVersion: v1
kind: Secret
metadata:
  name: oauth-tls-cert
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-certificate>
  tls.key: <base64-encoded-private-key>

​
Environment Configuration

​
oauth.config.logLevel
string
default:"info"
Built-in Integrations service log level.Valid Values: "debug", "info", "warn", "error"Default: "info"Recommendations:
  • Production: "info" or "warn"
  • Development: "debug"
Example:
oauth:
  config:
    logLevel: "debug"
​
oauth.config.dbSsl
string
default:"false"
Enable SSL for Built-in Integrations service database connections.Valid Values: "true", "false"Default: "false"When to Enable:
  • Using managed database service (AWS RDS, Azure Database, etc.)
  • Database requires encrypted connections
  • Compliance requirements
Example:
oauth:
  config:
    dbSsl: "true"

​
OAuth Secrets Configuration

OAuth secrets are configured via the oauth.secrets values and are used to secure the Built-in Integrations service and enable third-party integrations. These secrets are separate from the main application secrets and are stored in a dedicated Kubernetes secret resource.

​
Auto-Generated Secrets

​
oauth.secrets.cookieSecret
string
default:""
Secret key for signing OAuth session cookies.Auto-Generation: If not provided, automatically generated as a 64-character random alphanumeric string and persisted across upgrades.Purpose: Secures OAuth flow session data during the authentication process.Manual Generation:
openssl rand -base64 64
Leave Empty: To use auto-generated value (recommended).
​
oauth.secrets.dbEncryptionKey
string
default:""
Encryption key for OAuth tokens stored in the database.Auto-Generation: If not provided, automatically generated as a 64-character hexadecimal string and persisted across upgrades.Purpose: Encrypts sensitive OAuth tokens (access tokens, refresh tokens) at rest in the OAuth database.Format: 64-character hexadecimal string.Manual Generation:
openssl rand -hex 32
Leave Empty: To use auto-generated value (recommended).
​
oauth.secrets.internalApiKey
string
default:""
Internal API key for authentication between the Built-in Integrations service and Rails application.Auto-Generation: If not provided, automatically generated as a 64-character random alphanumeric string and persisted across upgrades.Purpose: Enables secure service-to-service communication for OAuth operations.Important: This value is automatically duplicated as CREWAI_OAUTH_API_KEY in the main application secrets for Rails to use.Manual Generation:
openssl rand -base64 64 | tr -d '\n'
Leave Empty: To use auto-generated value (recommended).

​
OAuth Provider Credentials

OAuth provider credentials are optional and only required if you want to enable specific OAuth integrations. Each provider supports both provider-level credentials (shared across all products) and product-specific overrides.

​
Google OAuth Provider

​
oauth.secrets.google.clientId
string
default:""
Google OAuth client ID used as default for all Google products.Purpose: Shared Google OAuth client ID. If product-specific client IDs are not provided, this value is used for all Google integrations (Gmail, Calendar, Drive, etc.).Obtain From: Google Cloud Console → APIs & Services → CredentialsExample:
oauth:
  secrets:
    google:
      clientId: "123456789-abcdefg.apps.googleusercontent.com"
      clientSecret: "GOCSPX-abc123..."
​
oauth.secrets.google.clientSecret
string
default:""
Google OAuth client secret used as default for all Google products.Purpose: Shared Google OAuth client secret for all Google integrations.
​
oauth.secrets.google.drivePickerKey
string
default:""
Google Drive Picker API key for file picker functionality.Purpose: Enables Google Drive file picker UI in the application for selecting files from Google Drive.Obtain From: Google Cloud Console → APIs & Services → Credentials → Create Credentials → API KeyImportant: This is an API key (not OAuth credentials) specifically for the Google Picker API.Example:
oauth:
  secrets:
    google:
      clientId: "123456789-abcdefg.apps.googleusercontent.com"
      clientSecret: "GOCSPX-abc123..."
      drivePickerKey: "AIzaSyAbc123def456..."
Product-Specific Google OAuth Overrides: You can override the provider-level credentials for specific Google products. If not provided, the provider-level credentials are used.
​
oauth.secrets.google.calendar.clientId
string
default:""
Google Calendar-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.calendar.clientSecret
string
default:""
Google Calendar-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.gmail.clientId
string
default:""
Gmail-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.gmail.clientSecret
string
default:""
Gmail-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.drive.clientId
string
default:""
Google Drive-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.drive.clientSecret
string
default:""
Google Drive-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.contacts.clientId
string
default:""
Google Contacts-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.contacts.clientSecret
string
default:""
Google Contacts-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.sheets.clientId
string
default:""
Google Sheets-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.sheets.clientSecret
string
default:""
Google Sheets-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.slides.clientId
string
default:""
Google Slides-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.slides.clientSecret
string
default:""
Google Slides-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.docs.clientId
string
default:""
Google Docs-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.docs.clientSecret
string
default:""
Google Docs-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.

​
Microsoft OAuth Provider

​
oauth.secrets.microsoft.clientId
string
default:""
Microsoft OAuth client ID used as default for all Microsoft products.Purpose: Shared Microsoft OAuth client ID. If product-specific client IDs are not provided, this value is used for all Microsoft integrations (Outlook, OneDrive, Teams, etc.).Obtain From: Microsoft Azure Portal → App registrationsExample:
oauth:
  secrets:
    microsoft:
      clientId: "12345678-1234-1234-1234-123456789abc"
      clientSecret: "abc123~def456..."
​
oauth.secrets.microsoft.clientSecret
string
default:""
Microsoft OAuth client secret used as default for all Microsoft products.Purpose: Shared Microsoft OAuth client secret for all Microsoft integrations.
Product-Specific Microsoft OAuth Overrides:
​
oauth.secrets.microsoft.outlook.clientId
string
default:""
Outlook-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.outlook.clientSecret
string
default:""
Outlook-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.onedrive.clientId
string
default:""
OneDrive-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.onedrive.clientSecret
string
default:""
OneDrive-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.teams.clientId
string
default:""
Teams-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.teams.clientSecret
string
default:""
Teams-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.sharepoint.clientId
string
default:""
SharePoint-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.sharepoint.clientSecret
string
default:""
SharePoint-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.excel.clientId
string
default:""
Excel-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.excel.clientSecret
string
default:""
Excel-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.word.clientId
string
default:""
Word-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.word.clientSecret
string
default:""
Word-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.

​
Other OAuth Providers

​
oauth.secrets.hubspot.clientId
string
default:""
HubSpot OAuth client ID.Obtain From: HubSpot Developer PortalExample:
oauth:
  secrets:
    hubspot:
      clientId: "12345678-abcd-1234-abcd-123456789abc"
      clientSecret: "abc123def456..."
​
oauth.secrets.hubspot.clientSecret
string
default:""
HubSpot OAuth client secret.
​
oauth.secrets.notion.clientId
string
default:""
Notion OAuth client ID.Obtain From: Notion IntegrationsExample:
oauth:
  secrets:
    notion:
      clientId: "secret_abc123def456..."
      clientSecret: "secret_xyz789..."
​
oauth.secrets.notion.clientSecret
string
default:""
Notion OAuth client secret.
OAuth Secrets: See Secrets Reference - Built-in Integrations Secrets for Built-in Integrations service secrets configuration including:
  • OAUTH_COOKIE_SECRET - Session cookie signing
  • OAUTH_DB_ENCRYPTION_KEY - Token encryption
  • OAUTH_INTERNAL_API_KEY - Service-to-service authentication
  • OAuth provider credentials (Google, Microsoft, HubSpot, Notion)
OAuth Database: The Built-in Integrations service uses a separate database (oauth_db) created automatically in the PostgreSQL instance. See PostgreSQL Configuration for database configuration. Automatic URL Configuration: When Built-in Integrations service is enabled, the Rails application is automatically configured with CREWAI_OAUTH_API_BASE_URL pointing to the internal Built-in Integrations service URL. See Environment Variables - Built-in Integrations for details.