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.