@devries-cameron20 / composio Mirror · read-only / commits / d9b7ec54b
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 18:30 UTC

docs(auth): OAuth connection security page (good-docs-writing voice)

Skill-guided rewrite of the OAuth connection security page: direct second-person voice, no em-dashes, concept-first sentences, no salesy comparatives. Also corrects four accuracy issues found while verifying against the Apollo code (these exist in the sibling PR too): - the ten-minute figure is the session_uri TTL, not a connection-expiry; - verification covers API + Connect Link redirects, not marketplace-install acknowledgements (which return before the verifier fork); - save-time validation is https + SSRF (private/reserved), not a reachability test; - the rejection message has no trailing period.

Anshu Garg committed Jul 30, 2026 at 18:13 UTC d9b7ec54b7942c60d15a91ba27510e395e2b9332
4 files changed +188
docs/agent/instructions/context.md
+1
@@ -24,6 +24,7 @@ This is your always-on map of Composio's concepts and the canonical page for eac
24 - **Manual auth** — generate Connect Links yourself with `session.authorize()`. → [Manually authenticating users](/docs/authenticating-users/manually-authenticating)
25 - **Managed vs custom auth** — use Composio's managed OAuth apps, or bring your own for branding/scopes. → [Managed vs custom auth](/docs/custom-app-vs-managed-app)
26 - **White-labeling** — remove Composio branding from the auth flow. → [White-labeling authentication](/docs/white-labeling-authentication)
27 +- **OAuth connection security** — two controls against OAuth session fixation: same-browser binding (managed apps; the `This connection was started from a different browser or device` rejection and the in-app-browser limitation) and callback identity verification (custom auth configs; verifier URL + `complete_auth`). This is the page for "connections from the dashboard stopped completing" and "a real `user_id` is now required". → [OAuth connection security](/docs/oauth-connection-security)
28 - **Importing existing connections** — pass in API keys or bearer tokens you already hold. → [Importing existing connections](/docs/importing-existing-connections)
29 - **Multiple accounts per user** — e.g. work and personal Gmail. → [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts)
30 - **Shared connections** — share one connected account across users via an ACL. → [Shared connections](/docs/authenticating-users/shared-connections)
docs/content/changelog/07-30-26-oauth-connection-binding.mdx new
+23
@@ -0,0 +1,23 @@
1 +---
2 +title: "OAuth connection security: same-browser binding and callback identity verification"
3 +date: "2026-07-30"
4 +description: "Stop an OAuth connection from being completed by another party: same-browser binding on Composio-managed apps, and opt-in, per-project callback identity verification."
5 +---
6 +
7 +Composio now stops an OAuth connection from being completed by someone other than the person who
8 +started it. On Composio-managed apps this is enforced automatically, bound to the browser that
9 +started the flow. Any project can also opt into callback identity verification, which ties activation
10 +to the user — the durable way to secure your own OAuth apps.
11 +
12 +### What shipped
13 +
14 +- **Same-browser binding** — for **Composio-managed apps** (default auth configs). Because Composio
15 + owns the OAuth app here, it enforces this automatically: a Connect Link must be completed in the
16 + browser that started it, and a callback from a different browser is rejected. It stays on for every
17 + managed connection, including where identity verification is also enabled. No setup required.
18 + [Learn more](/docs/oauth-connection-security#same-browser-binding)
19 +- **Callback identity verification** — an opt-in, per-project identity check, and the most reliable
20 + way to secure your **own OAuth apps**. Set a verifier URL, and Composio holds every OAuth connection
21 + in the project — managed and custom alike — until your server confirms the returning user matches
22 + the one it was created for. Enable it in Settings → General.
23 + [Learn more](/docs/oauth-connection-security#callback-identity-verification)
docs/content/docs/meta.json
+1
@@ -13,6 +13,7 @@
13 "---Authenticate users---",
14 "authentication",
15 "manually-authenticating",
16 + "oauth-connection-security",
17 "managing-multiple-connected-accounts",
18 "shared-connections",
19 "importing-existing-connections",
docs/content/docs/oauth-connection-security.mdx new
+163
@@ -0,0 +1,163 @@
1 +---
2 +title: OAuth connection security
3 +description: "Protect an OAuth connection from being completed by another party: same-browser binding on Composio managed apps, and opt-in callback identity verification per project."
4 +keywords: [oauth session fixation, same-browser binding, callback identity verification, user verification, connect link, verifier url, complete_auth]
5 +---
6 +
7 +On its own, a Connect Link or provider authorization URL is enough to complete an OAuth connection:
8 +whoever opens it and consents becomes the account attached to the flow. That is exploitable. Someone
9 +starts a connection under their own Composio user, copies the authorization URL before consenting,
10 +and gets a different person to finish it. The victim's provider account ends up attached to the
11 +attacker's identity.
12 +
13 +This is **OAuth session fixation**. Composio stops it two ways.
14 +
15 +**[Same-browser binding](#same-browser-binding)** runs automatically on Composio managed apps, with
16 +no setup from you. These apps are shared across every Composio user, so anyone can start a connection
17 +with one. Binding ties each authorization attempt to the browser that began it, so a flow one person
18 +starts can't be finished in another browser.
19 +
20 +**[Callback identity verification](#callback-identity-verification)** is how you secure connections
21 +on your own OAuth apps. Composio holds each connection until your server confirms the user who came
22 +back, and activates it only when that user matches the one the flow was created for. It checks the
23 +user rather than the browser, so it holds however the user returns from the provider, with none of
24 +the same-browser edge cases. It's opt-in per project, and once you turn it on it covers every OAuth
25 +connection in that project, managed and custom alike.
26 +
27 +## Same-browser binding
28 +
29 +On Composio managed apps, a connection has to be finished in the same browser that started it. When
30 +the Connect Link is submitted, Composio sets a secure cookie in that browser and checks it when the
31 +provider returns, so a link can't be carried to another browser and completed there. This runs
32 +automatically, with nothing to configure.
33 +
34 +<Callout type="warn">
35 +**This check can block some of your real users.** If someone opens the Connect Link in one browser
36 +but the provider sends them back to another, the connection is rejected with *"This connection was
37 +started from a different browser or device"*. It usually happens with in-app browsers (Instagram,
38 +LinkedIn, and similar) that hand the provider step off to the system browser, or when cookies are
39 +blocked. Reopening the link and finishing it in one browser gets them through.
40 +
41 +You can't turn this check off on managed apps. Composio's OAuth app is shared across every Composio
42 +user, so without it a connection one person starts could be finished by another. If it's blocking
43 +your users, bring your own OAuth app and turn on
44 +[callback identity verification](#callback-identity-verification). That binds each connection to your
45 +signed-in user instead of the browser, so it holds however the user returns from the provider.
46 +</Callout>
47 +
48 +## Callback identity verification
49 +
50 +Set a verifier URL on a project, and Composio stops activating OAuth connections there until your
51 +server confirms who came back. After the provider callback, Composio redirects the browser to an
52 +endpoint you host. Your server returns the signed-in `user_id`, and Composio activates the connection
53 +only if it matches the user the connection was created for.
54 +
55 +### Roles
56 +
57 +- **Your server asserts identity.** It reads its own session and returns the signed-in `user_id`.
58 +- **Composio verifies it.** It compares that `user_id` against the user the connection was created
59 + for, then activates or rejects.
60 +
61 +The endpoint you host stays small: read a session, call one Composio API, and redirect the user
62 +onward.
63 +
64 +### How it works
65 +
66 +<Steps>
67 +<Step>
68 +<StepTitle>The user consents at the provider</StepTitle>
69 +
70 +Create the connection as usual, passing the `user_id` you're connecting for.
71 +</Step>
72 +
73 +<Step>
74 +<StepTitle>Composio redirects to your verifier URL</StepTitle>
75 +
76 +Instead of activating the connection, Composio redirects the browser to the URL you configured,
77 +whatever path you set, with one query parameter appended: `session_uri`. For a configured URL of
78 +`https://your-app.com/oauth/return`:
79 +
80 +```
81 +https://your-app.com/oauth/return?session_uri=session_8Ff2...
82 +```
83 +
84 +`session_uri` is the only parameter Composio sends. It carries no connection id, user id, or toolkit
85 +name.
86 +</Step>
87 +
88 +<Step>
89 +<StepTitle>Your server identifies the user</StepTitle>
90 +
91 +Read your session from the incoming request and determine the signed-in `user_id`.
92 +</Step>
93 +
94 +<Step>
95 +<StepTitle>Redeem the session</StepTitle>
96 +
97 +This call runs from your server, authenticates with your project API key, and must not run in the
98 +browser. `POST` the `session_uri` and `user_id` to `complete_auth`:
99 +
100 +```bash
101 +curl -X POST https://backend.composio.dev/api/v3.1/connected_accounts/complete_auth \
102 + -H "x-api-key: $COMPOSIO_API_KEY" \
103 + -H "Content-Type: application/json" \
104 + -d '{
105 + "session_uri": "session_8Ff2...",
106 + "user_id": "your-signed-in-user"
107 + }'
108 +```
109 +
110 +On a match, the connection activates and the response returns `connected_account_id` and
111 +`toolkit_slug`. A `200` comes back only once the connection is `ACTIVE`, so there's nothing to poll.
112 +If the `user_id` doesn't match, the request returns `400` and the connection moves to `FAILED`;
113 +restart the flow if you need to. See the
114 +[API reference](/reference/api-reference/connected-accounts/postConnectedAccountsCompleteAuth) for
115 +the full response contract.
116 +</Step>
117 +
118 +<Step>
119 +<StepTitle>Redirect the user</StepTitle>
120 +
121 +The browser ends at your endpoint. Your server owns the redirect on success and the failure page on
122 +rejection.
123 +</Step>
124 +</Steps>
125 +
126 +### How to enable it
127 +
128 +Set the verifier URL in **Settings → General → Configuration**. The URL must be public HTTPS.
129 +Composio validates it on save and rejects private and reserved addresses, so local development needs a
130 +tunnel rather than `localhost`. The presence of the URL is the switch: remove it to disable
131 +verification.
132 +
133 +<Callout type="warn">
134 +A verifier URL takes effect immediately for every OAuth connection in the project. There's no staged
135 +rollout and no per-connection opt-out. Review the constraints below and deploy your endpoint before
136 +you set the URL.
137 +</Callout>
138 +
139 +### What to expect once it's on
140 +
141 +**Dashboard connections can't complete.** The dashboard still creates a pending connection and opens
142 +the provider consent screen, but on the callback Composio redirects the browser to your verifier URL
143 +instead of back to the dashboard. Your endpoint reports the user signed into your app, and Composio
144 +activates only if that matches the connection's owner. A dashboard connection is owned by a Composio
145 +dashboard user: not one of your app's users, and not disclosed to your endpoint, so your app can't
146 +report a match, and the connection never activates. To test a connection, run the flow from your own
147 +app, or clear the verifier URL while you work in the dashboard.
148 +
149 +**Verification covers the connections you create.** It applies to every OAuth connection in the
150 +project that goes through a provider redirect, whether you start it from the API or a hosted Connect
151 +Link.
152 +
153 +**Managed connections keep their browser binding.** On a managed connection, a verifier URL adds
154 +identity verification on top of same-browser binding; it doesn't switch the binding off. Composio's
155 +managed OAuth app is shared across every Composio user, so Composio enforces that binding itself
156 +rather than handing the guarantee to any one project. A managed connection with a verifier URL set is
157 +covered by both checks.
158 +
159 +### Session lifetime
160 +
161 +`session_uri` is valid for ten minutes and can be redeemed once, so redeem it on the incoming request
162 +rather than later. A second redemption of the same value returns `404`. Activation always requires a
163 +matching `user_id`, so a connection can never complete for the wrong user.