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.