Connector Authentication

How self-hosted Align connects to Slack, Teams, Jira, GitHub, and other integrations.

Overview

Self-hosted Align uses Align's centrally-managed OAuth applications for all integrations. You don't need to create your own OAuth apps for Slack, Teams, Jira, GitHub, or Linear.

This approach provides:

• Zero configuration - No OAuth app setup required
• Automatic updates - Permission changes handled by Align
• Enterprise compliance - Align's OAuth apps are reviewed and approved
• Consistent experience - Same connector setup flow as Align Cloud

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                     Your Self-Hosted Align                      │
│                                                                 │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐     │
│  │ Gateway │    │  Brain  │    │   UI    │    │Connector│     │
│  └────┬────┘    └─────────┘    └────┬────┘    └────┬────┘     │
│       │                             │              │           │
└───────┼─────────────────────────────┼──────────────┼───────────┘
        │                             │              │
        │                             │              │
        │    ┌────────────────────────┼──────────────┼───────┐
        │    │                        ▼              ▼       │
        │    │              ┌─────────────────────────────┐  │
        │    │              │   Align OAuth Gateway       │  │
        │    │              │   (oauth.align.tech)        │  │
        │    │              └─────────────────────────────┘  │
        │    │                        │                      │
        │    │            Align-Managed OAuth Apps           │
        │    └────────────────────────┼──────────────────────┘
        │                             │
        ▼                             ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│    Slack      │  │    Teams      │  │    Jira       │
└───────────────┘  └───────────────┘  └───────────────┘

When a user connects an integration:

1. User clicks "Connect Slack" in your self-hosted Align UI
2. They're redirected to Align's OAuth gateway (oauth.align.tech)
3. Align's OAuth app handles the authorization with Slack
4. Tokens are encrypted and returned to your self-hosted instance
5. Your instance stores the encrypted tokens locally

Your data stays in your infrastructure - only the OAuth handshake goes through Align's gateway.

Connecting Integrations

From the UI

1. Navigate to Settings → Connectors
2. Click the connector you want to enable
3. Follow the OAuth authorization flow
4. Grant permissions when prompted
5. The connector is now active

Required Permissions

Each connector requests specific permissions:

Slack

• Read messages in channels where Align is added
• Send messages and responses
• Read user information for attribution

Microsoft Teams

• Read channel messages
• Send messages and cards
• Read team and user information

Jira

• Read issues and projects
• Write comments on issues
• Read user information

GitHub

• Read repository contents and metadata
• Read and write issues and pull requests
• Receive webhook events

Linear

• Read issues and comments
• Write comments
• Read user information

Network Requirements

Your self-hosted Align needs outbound HTTPS access to:

Endpoint	Purpose
oauth.align.tech	OAuth token exchange
api.slack.com	Slack API calls
graph.microsoft.com	Teams API calls
api.atlassian.com	Jira API calls
api.github.com	GitHub API calls
api.linear.app	Linear API calls

Inbound webhooks require your instance to be accessible from the internet (or configure a webhook relay).

Webhook Configuration

After connecting an integration, webhooks are automatically configured to point to your self-hosted instance using the gateway.frontendUrl you configured in your Helm values. No manual webhook setup is required in the provider dashboards.

If you change your instance's public URL, disconnect and reconnect the integration to update the webhook endpoints.

Webhook URLs

Webhooks are sent directly to your self-hosted Align:

Integration	Webhook Endpoint
Slack	https://api.{your-domain}/connectors/slack/events
Teams	https://api.{your-domain}/connectors/teams/messages
Jira	https://api.{your-domain}/connectors/jira/webhooks
GitHub	https://api.{your-domain}/connectors/github/webhooks
Linear	https://api.{your-domain}/connectors/linear/webhooks

Firewall Configuration

Allow inbound HTTPS (443) from these IP ranges:

• Slack: Slack's IP ranges
• GitHub: GitHub's IP ranges
• Atlassian: Atlassian's IP ranges
• Microsoft: Microsoft 365 service endpoints

Token Security

• OAuth tokens are encrypted at rest using your encryption-key secret
• Tokens are never sent to Align's servers after the initial exchange
• Token refresh happens directly between your instance and the provider
• You can revoke access at any time from the provider's settings

Troubleshooting

"OAuth authorization failed"

1. Check your instance can reach oauth.align.tech
2. Check browser console for CORS or redirect errors

"Webhook verification failed"

1. Verify your API endpoint is publicly accessible
2. Check TLS certificate is valid (not self-signed)
3. Confirm firewall allows inbound from the provider

"Token refresh failed"

1. Check outbound access to the provider's API
2. User may need to reauthorize if permissions changed
3. Check provider's status page for outages