|
1
|
--- |
|
2
|
title: Single Sign-On (SSO) |
|
3
|
description: Configure SSO with Azure Entra ID, Google, or Cloudflare Access so users can log in via their identity provider. |
|
4
|
--- |
|
5
|
|
|
6
|
**Menu:** Users → Single Sign-On (SSO) Configuration |
|
7
|
|
|
8
|
**Best for:** Admin |
|
9
|
|
|
10
|
CoPilot supports three SSO providers out of the box. Once configured, users see **Sign in with …** buttons on the login page alongside the standard username/password form. |
|
11
|
|
|
12
|
| Provider | Protocol | How it works | |
|
13
|
|---|---|---| |
|
14
|
| **Azure Entra ID** | OAuth 2.0 / OIDC | User is redirected to Microsoft, then back to CoPilot with an authorization code. | |
|
15
|
| **Google** | OAuth 2.0 / OIDC | Same redirect flow via Google accounts. | |
|
16
|
| **Cloudflare Access** | JWT assertion | Cloudflare sits in front of CoPilot and injects a signed header; no redirect needed from the user's perspective. | |
|
17
|
|
|
18
|
--- |
|
19
|
|
|
20
|
## How SSO login works |
|
21
|
|
|
22
|
``` |
|
23
|
┌──────────┐ ┌───────────────────┐ ┌──────────────┐ |
|
24
|
│ Browser │─────▶│ Identity Provider │─────▶│ CoPilot │ |
|
25
|
│ (login │ │ (Azure / Google / │ │ backend │ |
|
26
|
│ page) │◀─────│ Cloudflare) │◀─────│ │ |
|
27
|
└──────────┘ └───────────────────┘ └──────────────┘ |
|
28
|
|
|
29
|
1. User clicks an SSO button on the login page. |
|
30
|
2. Browser redirects to the identity provider. |
|
31
|
3. User authenticates with their corporate credentials. |
|
32
|
4. Provider redirects back to CoPilot with a signed token. |
|
33
|
5. CoPilot verifies the token, checks the email allowlist, |
|
34
|
auto-provisions a local account if needed, and issues a session. |
|
35
|
``` |
|
36
|
|
|
37
|
> **Auto-provisioning:** The first time an allowed email logs in via SSO, CoPilot automatically creates a local user account with the role you assigned in the allowlist. No manual user creation is required. |
|
38
|
|
|
39
|
--- |
|
40
|
|
|
41
|
## Prerequisites |
|
42
|
|
|
43
|
- Your CoPilot instance must be reachable at a stable URL (HTTPS recommended). |
|
44
|
- You need **admin** access in CoPilot. |
|
45
|
- You need admin access to the identity provider you want to configure (Azure portal, Google Cloud Console, or Cloudflare Zero Trust dashboard). |
|
46
|
|
|
47
|
--- |
|
48
|
|
|
49
|
## Step 1 — Enable SSO globally |
|
50
|
|
|
51
|
1. Go to **Users** in the top navigation. |
|
52
|
2. Scroll to the **Single Sign-On (SSO) Configuration** card. |
|
53
|
3. Toggle **Enable SSO** to on. |
|
54
|
|
|
55
|
> This toggle controls whether SSO login buttons appear on the login page. You can enable the global toggle and then selectively enable individual providers. |
|
56
|
|
|
57
|
--- |
|
58
|
|
|
59
|
## Step 2 — Configure a provider |
|
60
|
|
|
61
|
### Azure Entra ID |
|
62
|
|
|
63
|
<Steps> |
|
64
|
|
|
65
|
<Step title="Register an application in Azure"> |
|
66
|
Go to [portal.azure.com](https://portal.azure.com) → **Azure Active Directory** → **App registrations** → **New registration**. |
|
67
|
|
|
68
|
- **Name:** e.g. `CoPilot SSO` |
|
69
|
- **Supported account types:** *Accounts in this organizational directory only* |
|
70
|
- Click **Register**. |
|
71
|
</Step> |
|
72
|
|
|
73
|
<Step title="Copy IDs"> |
|
74
|
From the app's **Overview** page: |
|
75
|
- Copy the **Application (client) ID** → you will paste this as **Client ID** in CoPilot. |
|
76
|
- Copy the **Directory (tenant) ID** → you will paste this as **Tenant ID** in CoPilot. |
|
77
|
</Step> |
|
78
|
|
|
79
|
<Step title="Create a client secret"> |
|
80
|
Go to **Certificates & secrets** → **New client secret**. Copy the **Value** (not the Secret ID) → you will paste this as **Client Secret** in CoPilot. |
|
81
|
</Step> |
|
82
|
|
|
83
|
<Step title="Set the redirect URI"> |
|
84
|
Go to **Authentication** → **Add a platform** → **Web**. Set the redirect URI to: |
|
85
|
|
|
86
|
``` |
|
87
|
https://<your-copilot-domain>/api/auth/sso/azure/callback |
|
88
|
``` |
|
89
|
|
|
90
|
> **Tip:** In CoPilot, the **Auto-fill** button next to the Redirect URI field will populate this automatically based on your current domain. |
|
91
|
</Step> |
|
92
|
|
|
93
|
<Step title="Add the email claim"> |
|
94
|
Go to **Token configuration** → **Add optional claim** → select **ID** token type → check **email** → **Add**. |
|
95
|
</Step> |
|
96
|
|
|
97
|
<Step title="Fill in CoPilot"> |
|
98
|
Back in CoPilot under the **Azure Entra ID** section: |
|
99
|
1. Toggle **Enable Azure SSO** to on. |
|
100
|
2. Paste the **Tenant ID**, **Client ID**, and **Client Secret**. |
|
101
|
3. Confirm the **Redirect URI** matches what you set in Azure. |
|
102
|
4. Click **Save SSO Settings**. |
|
103
|
</Step> |
|
104
|
|
|
105
|
</Steps> |
|
106
|
|
|
107
|
--- |
|
108
|
|
|
109
|
### Google |
|
110
|
|
|
111
|
<Steps> |
|
112
|
|
|
113
|
<Step title="Create OAuth credentials"> |
|
114
|
Go to [Google Cloud Console](https://console.cloud.google.com) → **APIs & Services** → **Credentials** → **Create Credentials** → **OAuth client ID**. |
|
115
|
|
|
116
|
- **Application type:** Web application |
|
117
|
- **Authorized redirect URIs:** add: |
|
118
|
|
|
119
|
``` |
|
120
|
https://<your-copilot-domain>/api/auth/sso/google/callback |
|
121
|
``` |
|
122
|
</Step> |
|
123
|
|
|
124
|
<Step title="Copy credentials"> |
|
125
|
Copy the **Client ID** and **Client Secret** shown after creation. |
|
126
|
</Step> |
|
127
|
|
|
128
|
<Step title="Enable People API"> |
|
129
|
In the Cloud Console go to **APIs & Services** → **Library** → search for **People API** → **Enable**. This is required for CoPilot to retrieve the user's email and profile. |
|
130
|
</Step> |
|
131
|
|
|
132
|
<Step title="Fill in CoPilot"> |
|
133
|
Under the **Google (OAuth2 / OIDC)** section: |
|
134
|
1. Toggle **Enable Google SSO** to on. |
|
135
|
2. Paste the **Client ID** and **Client Secret**. |
|
136
|
3. Confirm the **Redirect URI**. |
|
137
|
4. Click **Save SSO Settings**. |
|
138
|
</Step> |
|
139
|
|
|
140
|
</Steps> |
|
141
|
|
|
142
|
--- |
|
143
|
|
|
144
|
### Cloudflare Access |
|
145
|
|
|
146
|
Cloudflare Access works differently from the other providers. Instead of redirecting the user, Cloudflare sits **in front** of CoPilot as a reverse proxy and injects a cryptographically signed JWT header (`Cf-Access-Jwt-Assertion`) into every request. CoPilot verifies this header — it is impossible to forge without Cloudflare's private key. |
|
147
|
|
|
148
|
<Steps> |
|
149
|
|
|
150
|
<Step title="Create a Cloudflare Access application"> |
|
151
|
In the **Cloudflare Zero Trust** dashboard go to **Access** → **Applications** → **Add an application** → **Self-hosted**. |
|
152
|
|
|
153
|
- Set the domain to your CoPilot URL (e.g. `copilot.example.com`). |
|
154
|
- Connect your identity provider (e.g. Entra ID, Google, GitHub) under **Identity providers**. |
|
155
|
</Step> |
|
156
|
|
|
157
|
<Step title="Copy the Application Audience"> |
|
158
|
After creating the app open it → **Overview** → copy the **Application Audience (AUD) Tag**. |
|
159
|
</Step> |
|
160
|
|
|
161
|
<Step title="Copy your Team Domain"> |
|
162
|
Go to **Settings** → **Custom Pages** and copy your team domain (e.g. `myteam.cloudflareaccess.com`). |
|
163
|
</Step> |
|
164
|
|
|
165
|
<Step title="Fill in CoPilot"> |
|
166
|
Under the **Cloudflare Access (JWT Assertion)** section: |
|
167
|
1. Toggle **Enable Cloudflare Access** to on. |
|
168
|
2. Paste the **Team Domain** and **Application Audience (AUD)**. |
|
169
|
3. Click **Save SSO Settings**. |
|
170
|
</Step> |
|
171
|
|
|
172
|
</Steps> |
|
173
|
|
|
174
|
> With Cloudflare Access there is no client secret — authentication is handled entirely by the signed JWT header. |
|
175
|
|
|
176
|
--- |
|
177
|
|
|
178
|
## Step 3 — Manage the email allowlist |
|
179
|
|
|
180
|
SSO users can only log in if their email address is in the **SSO Allowed Emails** list. This prevents unauthorized accounts in your identity provider from accessing CoPilot. |
|
181
|
|
|
182
|
1. Scroll to the **SSO Allowed Emails** card (below the SSO configuration card). |
|
183
|
2. Click **Add Email**. |
|
184
|
3. Enter the user's email address and select a **role**: |
|
185
|
- **Admin** — full platform access |
|
186
|
- **Analyst** (default) — standard operator access |
|
187
|
4. Click **Add Email**. |
|
188
|
|
|
189
|
| Column | Description | |
|
190
|
|---|---| |
|
191
|
| **Email** | The email address permitted to log in via SSO. | |
|
192
|
| **Role** | The CoPilot role assigned on first login. | |
|
193
|
| **Added** | Timestamp of when the entry was created. | |
|
194
|
|
|
195
|
To remove an email, click the delete button in the row. |
|
196
|
|
|
197
|
> **Important:** Only emails in this list can log in via SSO. If a user's email is not listed, they will be denied access even if they authenticate successfully with the identity provider. |
|
198
|
|
|
199
|
--- |
|
200
|
|
|
201
|
## How SSO interacts with 2FA |
|
202
|
|
|
203
|
If a user has [two-factor authentication](/user/ui/two-factor-authentication) enabled on their CoPilot account, SSO login will still require the second factor: |
|
204
|
|
|
205
|
1. User authenticates via the identity provider. |
|
206
|
2. CoPilot verifies the SSO token and finds that the user has 2FA enabled. |
|
207
|
3. The user is prompted for their TOTP code (or a backup code) before the session is created. |
|
208
|
|
|
209
|
This means SSO and 2FA are **complementary** — SSO simplifies *how* users authenticate with their identity, while 2FA adds a second verification step. |
|
210
|
|
|
211
|
--- |
|
212
|
|
|
213
|
## Environment variables |
|
214
|
|
|
215
|
| Variable | Purpose | Default | |
|
216
|
|---|---|---| |
|
217
|
| `SSO_STATE_SECRET` | HMAC key used to sign OAuth2 state tokens (prevents CSRF). | Falls back to `JWT_SECRET` | |
|
218
|
|
|
219
|
> The state token is stateless — it encodes a timestamp and is signed with HMAC-SHA256. It expires after 10 minutes. |
|
220
|
|
|
221
|
--- |
|
222
|
|
|
223
|
## Troubleshooting |
|
224
|
|
|
225
|
| Symptom | Likely cause | Fix | |
|
226
|
|---|---|---| |
|
227
|
| SSO buttons don't appear on the login page | Global SSO toggle is off, or no individual provider is enabled. | Enable SSO globally **and** enable at least one provider. | |
|
228
|
| "Email not in allowed list" after SSO login | The user's email is not in the SSO Allowed Emails list. | Add the email address to the allowlist. | |
|
229
|
| Azure callback fails with "invalid redirect URI" | Redirect URI in Azure app registration doesn't match CoPilot. | Copy the redirect URI from CoPilot (use **Auto-fill**) and paste it exactly into Azure. | |
|
230
|
| Google callback fails | People API not enabled or redirect URI mismatch. | Enable the People API in Google Cloud Console and verify the redirect URI. | |
|
231
|
| Cloudflare "authentication failed" | CoPilot is not behind Cloudflare Access, or the AUD/team domain is wrong. | Ensure traffic goes through Cloudflare Access and double-check the AUD tag and team domain. | |