OAuth Apps Setup

Register your own OAuth applications for self-hosted Align.

Overview

Self-hosted Align requires you to create your own OAuth apps for each integration. This gives you full control over data access and permissions.

---

Slack App

Step 1: Create Slack App

1. Go to api.slack.com/apps
2. Click Create New App → From scratch
3. Name: "Align" (or your preferred name)
4. Select your workspace

Step 2: Configure OAuth & Permissions

1. Go to OAuth & Permissions

2. Add these Bot Token Scopes:

   • channels:history — Read messages in public channels
   • groups:history — Read messages in private channels
   • chat:write — Send messages
   • users:read — Read user information
   • commands — Add slash commands

3. Add these User Token Scopes (optional, for richer context):

   • channels:history
   • groups:history

Step 3: Configure Redirect URLs

Add your OAuth redirect URL:

https://api.yourdomain.com/auth/slack/callback

Step 4: Configure Event Subscriptions

1. Go to Event Subscriptions
2. Enable Events
3. Request URL: https://api.yourdomain.com/connectors/slack/events
4. Subscribe to bot events:
   • app_mention
   • message.channels
   • message.groups

Step 5: Configure Slash Commands (Optional)

1. Go to Slash Commands
2. Create: /align
3. Request URL: https://api.yourdomain.com/connectors/slack/commands

Step 6: Install to Workspace

1. Go to Install App
2. Click Install to Workspace
3. Note your Bot Token and Signing Secret

Step 7: Configure Align

Create the Kubernetes secret:

kubectl create secret generic align-oauth-slack \
  --namespace align \
  --from-literal=client-id="YOUR_CLIENT_ID" \
  --from-literal=client-secret="YOUR_CLIENT_SECRET" \
  --from-literal=signing-secret="YOUR_SIGNING_SECRET"

---

Microsoft Teams App

Step 1: Create Azure AD App Registration

1. Go to Azure Portal → Azure Active Directory
2. App registrations → New registration
3. Name: "Align"
4. Supported account types: Choose based on your needs
5. Redirect URI: https://api.yourdomain.com/auth/teams/callback

Step 2: Configure API Permissions

Add these Microsoft Graph permissions:

Permission	Type	Purpose
ChannelMessage.Read.All	Application	Read channel messages
ChannelMessage.Send	Delegated	Send messages
User.Read.All	Application	Read user information
Team.ReadBasic.All	Application	List teams

Click Grant admin consent for your tenant.

Step 3: Create Client Secret

1. Go to Certificates & secrets
2. New client secret
3. Note the secret value (only shown once)

Step 4: Create Bot Channel Registration

1. Go to Azure Bot Service
2. Create a new Bot
3. Link to your App Registration
4. Configure messaging endpoint: https://api.yourdomain.com/connectors/teams/messages

Step 5: Configure Align

kubectl create secret generic align-oauth-teams \
  --namespace align \
  --from-literal=client-id="YOUR_CLIENT_ID" \
  --from-literal=client-secret="YOUR_CLIENT_SECRET" \
  --from-literal=bot-app-id="YOUR_BOT_APP_ID" \
  --from-literal=bot-app-password="YOUR_BOT_PASSWORD"

---

Atlassian (Jira) App

Step 1: Create Atlassian App

1. Go to developer.atlassian.com
2. Create → OAuth 2.0 integration
3. Name: "Align"

Step 2: Configure Permissions

Add these scopes:

• read:jira-work — Read issues and projects
• write:jira-work — Write comments
• read:jira-user — Read user information

Step 3: Configure Callback URL

https://api.yourdomain.com/auth/atlassian/callback

Step 4: Configure Align

kubectl create secret generic align-oauth-atlassian \
  --namespace align \
  --from-literal=client-id="YOUR_CLIENT_ID" \
  --from-literal=client-secret="YOUR_CLIENT_SECRET"

---

GitHub App

Step 1: Create GitHub App

1. Go to Settings → Developer settings → GitHub Apps
2. New GitHub App
3. Name: "Align" (must be unique on GitHub)
4. Homepage URL: https://app.yourdomain.com

Step 2: Configure Permissions

Repository permissions:

• Contents: Read
• Issues: Read & Write
• Pull requests: Read & Write
• Metadata: Read

Organization permissions:

• Members: Read (optional)

Step 3: Configure URLs

• Callback URL: https://api.yourdomain.com/auth/github/callback
• Webhook URL: https://api.yourdomain.com/connectors/github/webhooks

Step 4: Generate Private Key

1. Scroll to Private keys
2. Generate a private key
3. Download the .pem file

Step 5: Configure Align

kubectl create secret generic align-oauth-github \
  --namespace align \
  --from-literal=client-id="YOUR_CLIENT_ID" \
  --from-literal=client-secret="YOUR_CLIENT_SECRET" \
  --from-literal=app-id="YOUR_APP_ID" \
  --from-file=app-private-key=./your-app.private-key.pem

---

Linear App

Step 1: Create Linear OAuth App

1. Go to linear.app/settings → API → OAuth applications
2. Create OAuth application
3. Name: "Align"
4. Redirect URI: https://api.yourdomain.com/auth/linear/callback

Step 2: Configure Scopes

Request these scopes:

• read — Read issues and comments
• write — Write comments

Step 3: Configure Align

kubectl create secret generic align-oauth-linear \
  --namespace align \
  --from-literal=client-id="YOUR_CLIENT_ID" \
  --from-literal=client-secret="YOUR_CLIENT_SECRET"

---

Webhook URLs Reference

Configure these webhook/callback URLs in your OAuth apps:

Integration	Callback URL	Webhook URL
Slack	https://api.{domain}/auth/slack/callback	https://api.{domain}/connectors/slack/events
Teams	https://api.{domain}/auth/teams/callback	https://api.{domain}/connectors/teams/messages
Jira	https://api.{domain}/auth/atlassian/callback	https://api.{domain}/connectors/jira/webhooks
GitHub	https://api.{domain}/auth/github/callback	https://api.{domain}/connectors/github/webhooks
Linear	https://api.{domain}/auth/linear/callback	https://api.{domain}/connectors/linear/webhooks

Replace {domain} with your actual domain (e.g., yourdomain.com).