Add custom OAuth consent security guide by jescalan · Pull Request #3413 · clerk/clerk-docs

jescalan · 2026-06-01T23:25:40Z

Summary

Stacks on #3315. Adds a security-focused guide for configuring a custom OAuth consent page, with a strong recommendation to use the Account Portal or the prebuilt <OAuthConsent /> component instead of a fully custom flow.

The guide covers consent phishing risk, required consent-screen content, redirect URI presentation, route configuration, safer appearance-based customization, and low-level custom-flow responsibilities.

Changes in this repo

Adds Customize the OAuth consent page to the OAuth guide section.
Adds tabbed prebuilt <OAuthConsent /> examples for Next.js, React, React Router, TanStack React Start, Astro, Vue, and Nuxt.
Adds low-level custom-flow examples for React-based SDKs, with warnings about redirect URI presentation and organization selection.
Cross-links the new guide from existing OAuth docs.
Updates the OAuth consent component and hook references from Add OAuthConsent and useOAuthConsent docs #3315 to point to the guide and fixes a few snippet accuracy issues.

Preview links

New pages:

Customize the OAuth consent page

Changed sections:

Parent PR

Add OAuthConsent and useOAuthConsent docs #3315

Validation

rtk pnpm -C clerk-docs build
rtk pnpm -C clerk-docs lint
rtk git -C clerk-docs diff --check

vercel · 2026-06-01T23:25:45Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Jun 9, 2026 10:01pm

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6ae5e884d1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7beb713efd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

wobsoriano

this looks good on my end 👍🏼

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0bf3843f32

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

jescalan · 2026-06-02T16:01:17Z

@coderabbitai review

jescalan · 2026-06-02T16:50:22Z

@codex review

chatgpt-codex-connector · 2026-06-02T16:58:15Z

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

jfoshee · 2026-06-02T18:43:24Z

Love how simple these are. We have a separate issue to investigate alleviating the need for setting the referrer. We will circle back to these docs when we figure that out.

jfoshee · 2026-06-02T19:06:12Z

+
+These examples display the full redirect hostname and an expandable full URL. For a production custom flow, use a public-suffix-aware approach for root-domain summaries, handle IP addresses and localhost explicitly, and test long redirect URIs to make sure the real destination remains visible.
+
+These examples also do not implement organization selection. If an OAuth application can request `user:org:read`, use `<OAuthConsent />` or add an organization selector that submits the selected `organization_id` with the allow action.


How can we remember to update this bit when <OrgSelect /> is made generally available? 🤔

jfoshee · 2026-06-08T18:04:28Z

I was just testing these docs with an agent and it failed to hide the navbar. We definitely need some language to remind implementors that the consent dialog should be the only thing on the page-- no other nav like sign-in/out or user button. Any other navigation will break the OAuth flow. @jescalan

jescalan · 2026-06-08T20:11:48Z

I was just testing these docs with an agent and it failed to hide the navbar. We definitely need some language to remind implementors that the consent dialog should be the only thing on the page-- no other nav like sign-in/out or user button. Any other navigation will break the OAuth flow. @jescalan

Good call. Revised the skill a little bit - should fix this

SarahSoutoul · 2026-06-09T21:20:06Z

 </If>

 <If sdk="vue">
-  ```vue {{ filename: 'oauth-consent.vue' }}


Was the src/pages added for any reason here? From looking at the docs, the standard is to call the vue files as such (see screenshots).

@jescalan @jfoshee

SarahSoutoul · 2026-06-09T21:21:28Z

+  ```vue {{ filename: 'pages/oauth-consent.vue' }}
  <script setup lang="ts">
-  // Components are automatically imported
+  import { OAuthConsent } from '@clerk/nuxt/components'


So the component doesn't get automatically imported like other components in Nuxt? @jescalan @jfoshee

SarahSoutoul · 2026-06-09T21:36:24Z

+  <Tab>
+    ```vue {{ filename: 'src/pages/OAuthConsentPage.vue' }}
+    <script setup lang="ts">
+    import { OAuthConsent, Show } from '@clerk/vue'
+    </script>
+
+    <template>
+      <Show when="signed-in">
+        <OAuthConsent />
+      </Show>
+    </template>
+    ```
+
+    ```html {{ filename: 'index.html' }}
+    <meta name="referrer" content="strict-origin-when-cross-origin" />
+    ```
+  </Tab>


@jescalan @jfoshee Why is this example not using the same setup than what we have in the Vue example of <OAuthConsent /> component page? This example uses an index.html but the one in the component page uses a useHead hook?

SarahSoutoul · 2026-06-09T21:47:30Z

 > [!IMPORTANT]
 > Enabling the consent screen for all OAuth apps is **strongly recommended**. Without a consent screen, any logged-in user who visits an OAuth authorization URL automatically grants access to any requested scopes. The consent screen acts as a critical security checkpoint, preventing malicious apps from silently gaining access to user accounts.
+>
+> If you need to host the consent page on your own application domain, see [Customize the OAuth consent page](/docs/guides/configure/auth-strategies/oauth/custom-consent-page). Clerk strongly recommends using the default [Account Portal](/docs/guides/account-portal/overview) consent page unless you have a specific product requirement that it cannot satisfy.


We have slightly different wording for the scoped-access page -> If you need to host the consent page on your own application domain VS If you need to host the consent page yourself

Is that on purpose? If not, think it would be good to make the wording consistent across those two places. @jescalan @jfoshee

SarahSoutoul · 2026-06-09T21:53:16Z

+    ```tsx {{ filename: 'app/oauth-consent/page.tsx' }}
+    import { OAuthConsent, Show } from '@clerk/nextjs'
+
+    export const metadata = {


Why do we not use the Metada from next here like we did in the component page Next.js code example? @jescalan @jfoshee

SarahSoutoul · 2026-06-09T21:54:37Z

Got an overall question on the code examples in this file. They all use the <Show> component to display the <OAuthConsent /> component when signed in. This is not the case for all the code examples in the component page - why? @jescalan @jfoshee

SarahSoutoul · 2026-06-09T21:58:15Z

@@ -0,0 +1,154 @@
+---
+title: Customize the OAuth consent page


I have a slight preference for Set up a custom OAuth consent page as the title. I think it matches the content a bit better, since this guide is about creating and configuring a custom consent route and flow, not just visually customizing an existing page. Customize the OAuth consent page reads a little more like appearance/styling, while Set up... feels closer to the actual task the guide walks through. @jescalan @jfoshee

SarahSoutoul · 2026-06-09T22:01:45Z

@jescalan @jfoshee have left a bunch of comments and questions (sorry!) and pushed a minor docs review doing the following:

Adding a collapsible: true prop on the code examples within docs/_partials/components/oauth-consent-custom-flow-examples.mdx given their length.
Changed the wording of some of the instructions in the Custom consent page to align with the Dashboard UI.

I still need to test some of this so will do that while waiting for responses.

vercel Bot deployed to Preview June 1, 2026 23:27 View deployment

jescalan marked this pull request as ready for review June 1, 2026 23:39

jescalan requested a review from a team as a code owner June 1, 2026 23:39

chatgpt-codex-connector Bot reviewed Jun 1, 2026

View reviewed changes

Comment thread docs/_partials/components/oauth-consent-examples.mdx

Comment thread docs/_partials/components/oauth-consent-custom-flow-examples.mdx

Comment thread docs/_partials/components/oauth-consent-custom-flow-examples.mdx Outdated

jescalan force-pushed the je/docs-oauth-custom-consent-page-stack branch from 6ae5e88 to 7beb713 Compare June 1, 2026 23:47

vercel Bot deployed to Preview June 1, 2026 23:49 View deployment

chatgpt-codex-connector Bot reviewed Jun 1, 2026

View reviewed changes

Comment thread docs/_partials/components/oauth-consent-custom-flow-examples.mdx Outdated

jescalan requested review from jfoshee and wobsoriano June 2, 2026 15:44

wobsoriano approved these changes Jun 2, 2026

View reviewed changes

jescalan force-pushed the je/docs-oauth-custom-consent-page-stack branch from 7beb713 to 0bf3843 Compare June 2, 2026 15:53

vercel Bot deployed to Preview June 2, 2026 15:55 View deployment

chatgpt-codex-connector Bot reviewed Jun 2, 2026

View reviewed changes

Comment thread docs/reference/components/authentication/oauth-consent.mdx

jescalan force-pushed the je/docs-oauth-custom-consent-page-stack branch from 0bf3843 to e0e89bf Compare June 2, 2026 16:05

vercel Bot deployed to Preview June 2, 2026 16:07 View deployment

jfoshee mentioned this pull request Jun 2, 2026

Add custom OAuth consent page docs #3412

Closed

jfoshee approved these changes Jun 2, 2026

View reviewed changes

jescalan force-pushed the je/docs-oauth-custom-consent-page-stack branch from e0e89bf to 824e683 Compare June 2, 2026 21:31

vercel Bot deployed to Preview June 2, 2026 21:33 View deployment

Add custom OAuth consent security guide

d341a8e

jescalan force-pushed the je/docs-oauth-custom-consent-page-stack branch from 824e683 to d341a8e Compare June 8, 2026 19:19

vercel Bot deployed to Preview June 8, 2026 19:21 View deployment

SarahSoutoul reviewed Jun 9, 2026

View reviewed changes

SarahSoutoul self-assigned this Jun 9, 2026

SarahSoutoul reviewed Jun 9, 2026

View reviewed changes

docs review

f838911

vercel Bot deployed to Preview June 9, 2026 22:01 View deployment


		These examples display the full redirect hostname and an expandable full URL. For a production custom flow, use a public-suffix-aware approach for root-domain summaries, handle IP addresses and localhost explicitly, and test long redirect URIs to make sure the real destination remains visible.

		These examples also do not implement organization selection. If an OAuth application can request `user:org:read`, use `<OAuthConsent />` or add an organization selector that submits the selected `organization_id` with the allow action.

Conversation

jescalan commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes in this repo

Preview links

Parent PR

Validation

Uh oh!

vercel Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

jescalan commented Jun 2, 2026

Uh oh!

jescalan commented Jun 2, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jun 2, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jfoshee commented Jun 8, 2026

Uh oh!

jescalan commented Jun 8, 2026

Uh oh!

SarahSoutoul Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SarahSoutoul commented Jun 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jescalan commented Jun 1, 2026 •

edited

Loading

vercel Bot commented Jun 1, 2026 •

edited

Loading

SarahSoutoul Jun 9, 2026 •

edited

Loading