From 5dbc688ce80bd1a3ccbf78e2f80fc7101aaf4eb6 Mon Sep 17 00:00:00 2001 From: Nate Barbettini Date: Wed, 2 Jul 2025 15:36:21 -0700 Subject: [PATCH 1/4] Add secure/brand auth in production doc --- pages/home/auth/_meta.ts | 1 + pages/home/auth/secure-auth-production.mdx | 127 +++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 pages/home/auth/secure-auth-production.mdx diff --git a/pages/home/auth/_meta.ts b/pages/home/auth/_meta.ts index ff51313c..025a383e 100644 --- a/pages/home/auth/_meta.ts +++ b/pages/home/auth/_meta.ts @@ -3,4 +3,5 @@ export default { "auth-tool-calling": "Authorized Tool Calling", "tool-auth-status": "Checking Authorization Status", "call-third-party-apis-directly": "Direct Third-Party API Call", + "secure-auth-production": "Secure Auth in Production", }; diff --git a/pages/home/auth/secure-auth-production.mdx b/pages/home/auth/secure-auth-production.mdx new file mode 100644 index 00000000..59ff070e --- /dev/null +++ b/pages/home/auth/secure-auth-production.mdx @@ -0,0 +1,127 @@ +--- +title: "Secure Auth in Production" +description: "How to secure and brand your auth flows in production" +--- + +# Secure and Brand the Auth Flow in Production + +To keep your users safe, Arcade.dev performs a session verification check when a tool is authorized for the first time. This check verifies that the user who is authorizing the tool is the same user who started the authorization flow, which helps prevent phishing attacks. + +There are two ways to secure your auth flows with Arcade.dev: +- Use the **Arcade session verifier** for development (enabled by default) +- Implement a **custom session verifier** for production + +This setting is configured in the Arcade Dashboard. + + +## Use the Arcade session verifier + +If you're building a proof-of-concept app or a solo project, use the Arcade session verifier. This option is on by default when you create a new Arcade.dev account. + +When you authorize a tool, you'll be prompted to sign in to your Arcade.dev account. If you are already signed in (to the Arcade Dashboard, for example), this verification will succeed silently. + + + Arcade's default OAuth apps can *only* be used with the Arcade session verifier. + If you are building a multi-user production app, you must obtain your own OAuth app credentials and add them to Arcade. + For example, [configure Google auth in the Arcade Dashboard](https://docs.arcade.dev/home/auth-providers/google#access-the-arcade-dashboard). + + +The Arcade.dev session verifier helps keep your auth flows secure while you are building and testing your agent or app. When you're ready to share your work with others, implement a [custom session verifier](#set-up-a-custom-session-verifier) so your users don't need to sign in to Arcade.dev. + + +## Set up a custom session verifier + +In a production application or agent, user sessions are verified by your code, not Arcade.dev. To enable this, build a custom verifier route and add the URL to the Arcade Dashboard. + +When your users authorize a tool, Arcade.dev will redirect the user's browser to your verifier route with some information in the query string. Your custom verifier route must send a response back to Arcade.dev to confirm the user's session details. + +If you need help, start a [GitHub discussion](https://github.com/ArcadeAI/arcade-ai/discussions) and we'll be happy to assist. + +import { Steps, Tabs } from "nextra/components"; + + + +### Build a new route + +Create a public route in your app or API that can accept a browser redirect (HTTP 303) from Arcade.dev after a user has authorized a tool. + +The route must gather the following information: + +- The `flow_id` from the current URL's query string +- The unique ID of the user currently signed in. This varies depending on how your app is built, but it is typically retrieved from a session cookie or other secure storage. It **must** match the user ID that your code specified at the start of the authorization flow. + + +### Verify the user's session details + +Use the Arcade SDK (or our REST API) to verify the user's session details. + + + Because this request uses your Arcade API key, it *must not* be made from the client side (a browser or desktop app). This code must be run on a server. + + + + +```text +POST https://cloud.arcade.dev/api/v1/oauth/confirm_user +Authorization: Bearer +Content-Type: application/json + +{ + "flow_id": "", + "user_id": "" +} +``` + + + +**Valid Response** + +If the session details are valid, the response will contain some information about the auth flow: + + + +```text +HTTP 200 OK +Content-Type: application/json + +{ + // Can be used to look up the auth flow's status in the Arcade API + "auth_id": "ac_2zKml...", + + // Optional: URL to redirect the user to after the authorization flow is complete + "next_uri": "https://..." +} +``` + + + +You can optionally redirect the user's browser to the `next_uri`, which will display a generic "success" page. Or, you can redirect to your application as needed. + +**Invalid Response** + +If the session details are invalid, it means the user is not the same user who started the authorization flow. + + + +```text +HTTP 400 Bad Request +Content-Type: application/json + +{ + "code": 400, + "msg": "An error occurred during verification" +} +``` + + + +### Add your custom verifier route to Arcade + +In the Arcade Dashboard, pick the **Custom verifier** option and add the URL of your verifier route. + + + Arcade's default OAuth apps *only* support the Arcade session verifier. + Authorization flows using Arcade's default OAuth apps will use the Arcade session verifier even if you have a custom verifier route set up. + + + From 25996affda2f7f2f6300046ac08725a808e005b7 Mon Sep 17 00:00:00 2001 From: Nate Barbettini Date: Thu, 10 Jul 2025 17:39:53 -0700 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Evan Tahler --- pages/home/auth/secure-auth-production.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/home/auth/secure-auth-production.mdx b/pages/home/auth/secure-auth-production.mdx index 59ff070e..e7f090f8 100644 --- a/pages/home/auth/secure-auth-production.mdx +++ b/pages/home/auth/secure-auth-production.mdx @@ -16,7 +16,7 @@ This setting is configured in the Arcade Dashboard. ## Use the Arcade session verifier -If you're building a proof-of-concept app or a solo project, use the Arcade session verifier. This option is on by default when you create a new Arcade.dev account. +If you're building a proof-of-concept app or a solo project, use the Arcade session verifier. This option is on by default when you create a new Arcade.dev account and requires no custom development. When you authorize a tool, you'll be prompted to sign in to your Arcade.dev account. If you are already signed in (to the Arcade Dashboard, for example), this verification will succeed silently. From 9f16a1d1e5a393e8c2db280e0d66ecf260125ffa Mon Sep 17 00:00:00 2001 From: Nate Barbettini Date: Fri, 11 Jul 2025 21:37:51 -0700 Subject: [PATCH 3/4] Tweaks from feedback --- pages/home/auth/secure-auth-production.mdx | 29 +++++++++++----------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/pages/home/auth/secure-auth-production.mdx b/pages/home/auth/secure-auth-production.mdx index 59ff070e..0acdcf18 100644 --- a/pages/home/auth/secure-auth-production.mdx +++ b/pages/home/auth/secure-auth-production.mdx @@ -5,37 +5,36 @@ description: "How to secure and brand your auth flows in production" # Secure and Brand the Auth Flow in Production -To keep your users safe, Arcade.dev performs a session verification check when a tool is authorized for the first time. This check verifies that the user who is authorizing the tool is the same user who started the authorization flow, which helps prevent phishing attacks. +To keep your users safe, Arcade.dev performs a user verification check when a tool is authorized for the first time. This check verifies that the user who is authorizing the tool is the same user who started the authorization flow, which helps prevent phishing attacks. There are two ways to secure your auth flows with Arcade.dev: -- Use the **Arcade session verifier** for development (enabled by default) -- Implement a **custom session verifier** for production +- Use the **Arcade user verifier** for development (enabled by default) +- Implement a **custom user verifier** for production This setting is configured in the Arcade Dashboard. -## Use the Arcade session verifier +## Use the Arcade user verifier -If you're building a proof-of-concept app or a solo project, use the Arcade session verifier. This option is on by default when you create a new Arcade.dev account. +If you're building a proof-of-concept app or a solo project, use the Arcade user verifier. This option is on by default when you create a new Arcade.dev account. When you authorize a tool, you'll be prompted to sign in to your Arcade.dev account. If you are already signed in (to the Arcade Dashboard, for example), this verification will succeed silently. +The Arcade.dev user verifier helps keep your auth flows secure while you are building and testing your agent or app. When you're ready to share your work with others, implement a [custom user verifier](#build-a-custom-user-verifier) so your users don't need to sign in to Arcade.dev. + - Arcade's default OAuth apps can *only* be used with the Arcade session verifier. + Arcade's default OAuth apps can *only* be used with the Arcade user verifier. If you are building a multi-user production app, you must obtain your own OAuth app credentials and add them to Arcade. For example, [configure Google auth in the Arcade Dashboard](https://docs.arcade.dev/home/auth-providers/google#access-the-arcade-dashboard). -The Arcade.dev session verifier helps keep your auth flows secure while you are building and testing your agent or app. When you're ready to share your work with others, implement a [custom session verifier](#set-up-a-custom-session-verifier) so your users don't need to sign in to Arcade.dev. - +## Build a custom user verifier -## Set up a custom session verifier +In a production application or agent, users are verified by your code, not Arcade.dev. This allows you to fully control your end-user's experience. To enable this, build a custom verifier route and add the URL to the Arcade Dashboard. -In a production application or agent, user sessions are verified by your code, not Arcade.dev. To enable this, build a custom verifier route and add the URL to the Arcade Dashboard. +When your users authorize a tool, Arcade.dev will redirect the user's browser to your verifier route with some information in the query string. Your custom verifier route must send a response back to Arcade.dev to confirm the user's ID. -When your users authorize a tool, Arcade.dev will redirect the user's browser to your verifier route with some information in the query string. Your custom verifier route must send a response back to Arcade.dev to confirm the user's session details. - -If you need help, start a [GitHub discussion](https://github.com/ArcadeAI/arcade-ai/discussions) and we'll be happy to assist. +If you need help, start a [GitHub discussion](https://github.com/ArcadeAI/arcade-ai/discussions) and we'll be happy to assist. TODO prestart import { Steps, Tabs } from "nextra/components"; @@ -48,7 +47,9 @@ Create a public route in your app or API that can accept a browser redirect (HTT The route must gather the following information: - The `flow_id` from the current URL's query string -- The unique ID of the user currently signed in. This varies depending on how your app is built, but it is typically retrieved from a session cookie or other secure storage. It **must** match the user ID that your code specified at the start of the authorization flow. +- The unique ID of the user currently signed in, commonly an ID from your application, an email address, or similar. + +How it's retrieved varies depending on how your app is built, but it is typically retrieved from a session cookie or other secure storage. It **must** match the user ID that your code specified at the start of the authorization flow. ### Verify the user's session details From f60fabf4fe0bd9046ccceef57fa51da8b422acb9 Mon Sep 17 00:00:00 2001 From: Nate Barbettini Date: Mon, 14 Jul 2025 06:51:03 -0700 Subject: [PATCH 4/4] Updates from review --- pages/home/auth/secure-auth-production.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pages/home/auth/secure-auth-production.mdx b/pages/home/auth/secure-auth-production.mdx index 9b917aa5..b3a83871 100644 --- a/pages/home/auth/secure-auth-production.mdx +++ b/pages/home/auth/secure-auth-production.mdx @@ -34,7 +34,7 @@ In a production application or agent, users are verified by your code, not Arcad When your users authorize a tool, Arcade.dev will redirect the user's browser to your verifier route with some information in the query string. Your custom verifier route must send a response back to Arcade.dev to confirm the user's ID. -If you need help, start a [GitHub discussion](https://github.com/ArcadeAI/arcade-ai/discussions) and we'll be happy to assist. TODO prestart +If you need help, join the [Implementing a custom user verifier](https://github.com/ArcadeAI/arcade-ai/discussions/486) GitHub discussion and we'll be happy to assist. import { Steps, Tabs } from "nextra/components"; @@ -47,14 +47,14 @@ Create a public route in your app or API that can accept a browser redirect (HTT The route must gather the following information: - The `flow_id` from the current URL's query string -- The unique ID of the user currently signed in, commonly an ID from your application, an email address, or similar. +- The unique ID of the user currently signed in, commonly an ID from your application's database, an email address, or similar. How it's retrieved varies depending on how your app is built, but it is typically retrieved from a session cookie or other secure storage. It **must** match the user ID that your code specified at the start of the authorization flow. -### Verify the user's session details +### Verify the user's identity -Use the Arcade SDK (or our REST API) to verify the user's session details. +Use the Arcade SDK (or our REST API) to verify the user's identity. Because this request uses your Arcade API key, it *must not* be made from the client side (a browser or desktop app). This code must be run on a server. @@ -77,7 +77,7 @@ Content-Type: application/json **Valid Response** -If the session details are valid, the response will contain some information about the auth flow: +If the user's ID matches the ID specified at the start of the authorization flow, the response will contain some information about the auth flow: @@ -100,7 +100,7 @@ You can optionally redirect the user's browser to the `next_uri`, which will dis **Invalid Response** -If the session details are invalid, it means the user is not the same user who started the authorization flow. +If the user's ID does not match the ID specified at the start of the authorization flow, the response will contain an error. @@ -121,8 +121,8 @@ Content-Type: application/json In the Arcade Dashboard, pick the **Custom verifier** option and add the URL of your verifier route. - Arcade's default OAuth apps *only* support the Arcade session verifier. - Authorization flows using Arcade's default OAuth apps will use the Arcade session verifier even if you have a custom verifier route set up. + Arcade's default OAuth apps *only* support the Arcade user verifier. + Authorization flows using Arcade's default OAuth apps will use the Arcade user verifier even if you have a custom verifier route set up.