diff --git a/src/content/changelog/fundamentals/2026-06-03-public-oauth-clients.mdx b/src/content/changelog/fundamentals/2026-06-03-public-oauth-clients.mdx new file mode 100644 index 00000000000..3067a68ccd7 --- /dev/null +++ b/src/content/changelog/fundamentals/2026-06-03-public-oauth-clients.mdx @@ -0,0 +1,50 @@ +--- +title: Introducing self-managed OAuth clients +description: Developers can now create self-managed OAuth clients that integrate with Cloudflare. +products: + - fundamentals +date: 2026-06-03 +publish_future_dated_entry: true +--- + +import { DashButton } from "~/components"; + +Today we are launching self-managed OAuth, enabling developers to build third-party applications that integrate with Cloudflare via OAuth. This provides a more secure, user-friendly, and manageable alternative to API tokens. + +OAuth lets third-party applications act on behalf of a user to access their Cloudflare account. For example, after a user grants consent, Wrangler can deploy Workers into that account. + +## What is new + +Cloudflare Developers can now create and manage their own OAuth applications to integrate with Cloudflare. + +### Create an application + +To create an application, go to **Manage account** > **OAuth clients** in your account on the Cloudflare dashboard. + + + +### Select limited scopes + +If you have used an API token to call Cloudflare APIs, OAuth client scopes will look familiar. Select only the scopes your application needs during application creation, and include that scope list when sending users to Cloudflare for consent. + +Users can review the requested scopes before they consent. + +### Apps for both private and public use + +Applications start with `private` visibility. Private applications can only be used by members of the account where the application was created. + +To make an application available to any Cloudflare user, complete the prerequisites for `public` visibility. + +For more information, refer to [client visibility](/fundamentals/oauth/create-an-oauth-client/#private-and-public-clients). + +### Client domain verification + +Before an application can be made public, you must verify the client domain. Domain verification helps users confirm that the application owner controls the domain shown on the consent page. + +After verification, users see a verified badge on the consent page. + +For more information, refer to [domain verification](/fundamentals/oauth/create-an-oauth-client/#client-url-domain-ownership-verification). + +## Learn more + +For more information, refer to [OAuth clients](/fundamentals/oauth/). diff --git a/src/content/dash-routes/core.json b/src/content/dash-routes/core.json index a22af19066f..f864ddbd178 100644 --- a/src/content/dash-routes/core.json +++ b/src/content/dash-routes/core.json @@ -421,6 +421,16 @@ "deeplink": "/?to=/:account/api-tokens", "parent": ["Manage account"] }, + { + "name": "OAuth clients", + "deeplink": "/?to=/:account/oauth-clients", + "parent": ["Manage account"] + }, + { + "name": "Manage OAuth authorizations", + "deeplink": "/?to=/profile/access-management/authorization", + "parent": ["Manage account"] + }, { "name": "Audit logs", "deeplink": "/?to=/:account/audit-log", diff --git a/src/content/directory/cloudflare-one-appliance.yaml b/src/content/directory/cloudflare-one-appliance.yaml index f26efd8f6dc..67bad726bf6 100644 --- a/src/content/directory/cloudflare-one-appliance.yaml +++ b/src/content/directory/cloudflare-one-appliance.yaml @@ -1,4 +1,4 @@ -id: SmaYeH +id: tsJEfe name: Cloudflare One Appliance entry: diff --git a/src/content/directory/oauth.yaml b/src/content/directory/oauth.yaml new file mode 100644 index 00000000000..6a0f9cf5053 --- /dev/null +++ b/src/content/directory/oauth.yaml @@ -0,0 +1,13 @@ +id: UtGqsm +name: OAuth documentation + +entry: + title: OAuth documentation + url: /fundamentals/oauth/ + group: Core platform + additional_groups: [Docs collections] + +meta: + title: Cloudflare OAuth docs + description: Create and integrate with Cloudflare using OAuth + author: "@cloudflare" diff --git a/src/content/docs/fundamentals/new-features/index.mdx b/src/content/docs/fundamentals/new-features/index.mdx index 8f052702ba7..e9c49e03436 100644 --- a/src/content/docs/fundamentals/new-features/index.mdx +++ b/src/content/docs/fundamentals/new-features/index.mdx @@ -3,15 +3,15 @@ pcx_content_type: concept title: RSS Feeds description: Subscribe to Cloudflare RSS feeds to stay informed about product updates and new features. sidebar: - order: 10 + order: 11 group: hideIndex: true products: - fundamentals --- -import { DirectoryListing } from "~/components" +import { DirectoryListing } from "~/components"; Cloudflare offers several RSS feeds to help you consume content programmatically. - + diff --git a/src/content/docs/fundamentals/oauth/authorizing-an-application.mdx b/src/content/docs/fundamentals/oauth/authorizing-an-application.mdx new file mode 100644 index 00000000000..99382892cc7 --- /dev/null +++ b/src/content/docs/fundamentals/oauth/authorizing-an-application.mdx @@ -0,0 +1,44 @@ +--- +title: Authorizing an application +pcx_content_type: reference +description: Learn more about what it means to authorize a third-party application on Cloudflare +sidebar: + order: 10 +products: + - fundamentals + - oauth +--- + +import { DashButton } from "~/components"; + +## Overview + +When you authorize a third-party OAuth application, you grant it permission to access specific Cloudflare resources on your behalf. Cloudflare provides tools to view, manage, and revoke these authorizations at any time. + +## Authorize a third-party application + +When a third-party application requests access to your Cloudflare account, you will see a consent screen that displays: + +- **Application name and logo**: The name and branding of the requesting application +- **Publisher domain**: The verified domain of the application publisher +- **Account selection**: Choose which Cloudflare account(s) the application can access +- **Requested permissions**: After selecting the account(s) the application may access, the specific scopes the application is requesting will be displayed before consent is complete. To finish the authorization process, review the permissions the application is requesting and click “**Authorize**” + +## View and revoke authorized applications + +Application authorizations may be viewed and revoked at any time from the profile page on the Cloudflare dashboard. + +1. Log in to the Cloudflare dashboard. +2. +3. View the list of applications you have authorized. + - If you wish to revoke access to an application, click the “Revoke” button for that row + +## Account administrator controls + +If an account is not available for selection during the consent flow, it may be due to an administrator of that account disabling access to account resources via OAuth. + +Account administrators can restrict OAuth applications from accessing account resources via **Manage Account** \> **Members \> Settings \> Public OAuth App access**. + +:::caution +This will not prevent existing authorizations account members may already have in place, and will only prevent new authorizations from accessing account resources. +::: diff --git a/src/content/docs/fundamentals/oauth/create-an-oauth-client.mdx b/src/content/docs/fundamentals/oauth/create-an-oauth-client.mdx new file mode 100644 index 00000000000..c61a249cb90 --- /dev/null +++ b/src/content/docs/fundamentals/oauth/create-an-oauth-client.mdx @@ -0,0 +1,226 @@ +--- +title: Create your OAuth client +pcx_content_type: how-to +description: Create an OAuth client that can access Cloudflare API resources on behalf of users. +sidebar: + order: 1 +products: + - fundamentals + - oauth +--- + +import { DashButton, Steps, Tabs, TabItem } from "~/components"; + +## Prerequisites + +To create an OAuth client, you must have one of these roles for the associated account: Super Administrator, Administrator, or OAuth Client Write. + + + + + 1. Log in to the Cloudflare dashboard. + 2. Select your account. + 3. Go to **Manage Account** > **OAuth clients**. + 4. Select **Create client**. + 5. Enter the required configuration details: + - Client name + - Response type + - Grant type + - Token authentication method + - Redirect URLs + 6. Optional: Add non-required fields. + 7. Select **Continue** and define the scopes required for your client. + 8. Select **Create client**. + 9. Save your **Client ID** and **Client Secret** in a secure location. + + + + + + To create OAuth clients with the Cloudflare API, create an API token with the `OAuth Clients Write` permission. + + ```bash + curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $API_TOKEN" \ + -d '{ + "client_name": "Cloudflare OAuth Client", + "grant_types": ["authorization_code"], + "redirect_uris": ["https://example.com/oauth/callback"], + "scopes": ["workers-platform.read"], + "post_logout_redirect_uris": ["https://example.com/logout"], + "response_types": ["code"], + "token_endpoint_auth_method": "client_secret_basic", + "logo_uri": "https://example.com/logo.png", + "policy_uri": "https://example.com/policy", + "tos_uri": "https://example.com/tos", + "client_uri": "https://example.com", + "allowed_cors_origins": ["https://example.com"] + }' + ``` + + + +:::note +After you create an OAuth client, Cloudflare displays the client secret if the client requires one. Copy it to a secure location. You cannot view the secret again after you leave the page. If you lose the secret, rotate it to get a new one. +::: + +## Select scopes + +OAuth scope names correspond to Cloudflare API token permission names. Use the Cloudflare API documentation to identify the permissions your client needs. + + + + When you create or edit an OAuth client, all available scopes are displayed. Search for and select the scopes required for your client. + + + Fetch the available scopes from the API. Use the scope ID when you create a client through the API. + + ```bash + curl "https://api.cloudflare.com/client/v4/oauth/scopes" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $API_TOKEN" + ``` + + + +## Supported OAuth flows + +Cloudflare OAuth clients support the OAuth 2.0 Authorization Code flow. + +Cloudflare does not support Client Credentials, Implicit, Resource Owner Password Credentials, Device Authorization, or other OAuth grant types for third-party clients. + +### Choose a flow + +Use the following guidance to choose an OAuth flow: + +| Client type | Flow | Token endpoint authentication | PKCE | +| ------------------------------------------ | --------------------------------------- | --------------------------------------------- | --------------------- | +| Server-side web app or backend service | Authorization Code with a client secret | `client_secret_basic` or `client_secret_post` | Optional/not required | +| Browser-based, mobile, desktop, or CLI app | Authorization Code with PKCE | `none` | Required, `S256` | + +### Client secret + +The Authorization Code flow is intended for secure server-side applications that can protect a client secret from exposure. + +- **Use when:** Your OAuth client is a server-side web application or backend service. +- **How it works:** Your client redirects the user to the authorization page. After authorization, Cloudflare returns an authorization code to your backend. Your backend exchanges the code and client secret for an access token. +- **Security note:** Never expose your client secret in client-side code or embed it in mobile client binaries. + +### PKCE + +Proof Key for Code Exchange (PKCE) extends the Authorization Code flow for public clients, such as mobile or single-page apps, where a client secret cannot be securely stored. + +- **Use when:** Your OAuth client is a single-page, mobile, desktop, or CLI application. +- **How it works:** Your application generates a unique code verifier and code challenge for every login request instead of using a static client secret. +- **Security note:** Clients that use PKCE do not need a client secret. + +## Private and public clients + +New OAuth clients default to private visibility. Private clients can only be authorized by members of the parent Cloudflare account. Public clients allow authorization from any Cloudflare user. + +Before you make a client public, complete the required actions and populate the required fields. + +### Required fields + +- Client name +- Logo +- Client URL +- Scopes + +### Required actions + +OAuth clients must complete [domain verification](#client-url-domain-ownership-verification) for the client URL before they can be made public. + +### Promote a client to public + +:::caution +Setting a client's visibility to public is permanent. You cannot change the visibility back to private. +::: + + + + + 1. Go to **Manage Account** > **OAuth clients**. + 2. Open the action menu for your client. + 3. Select **Change Visibility**. + + + + + + ```bash + curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients/$CLIENT_ID" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $API_TOKEN" \ + -d '{ "visibility": "public" }' + ``` + + + +## Client URL domain ownership verification + +Cloudflare requires client URL domain ownership verification before a client can become public. If your client is only for private use by members of the account, domain ownership verification is not required. + +:::caution +After Cloudflare verifies domain ownership, you cannot change the domain of the client URL. You can still update the route for that domain. +::: + +Copy the verification code and create a `TXT` record in your DNS configuration with that value. The record must include all text, including the `cloudflare_oauth_client_publisher=` prefix. + +Cloudflare polls this DNS record until it is found or until the request times out after two days. + +### Restart verification + + + + If the verification process times out, select **Restart verification** in the client action menu. + + + To restart a failed or timed out verification, send a `PATCH` request with the existing `client_uri` unchanged. + + ```bash + curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients/$CLIENT_ID" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $API_TOKEN" \ + -d '{ "client_uri": "https://example.com" }' + ``` + + + +## Rotate client secrets + +Each client can have two secrets. This lets you create a new secret, update your client to use the new secret, and delete the old secret. + + + + + 1. Go to **Manage Account** > **OAuth clients**. + 2. Open the action menu for your client. + 3. Select **Rotate client secret**. + 4. Save the new secret in a secure location. + 5. After your client uses the new secret, delete the old secret. + + + + + + To check whether a client is in the middle of a secret rotation, look for `has_rotated_secret` in the `GET` response. If the value is `true`, delete the old secret before you create another secret. + + #### Create a new secret + + ```bash + curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients/$CLIENT_ID/rotate_secret" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $API_TOKEN" + ``` + + #### Delete the old secret + + ```bash + curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients/$CLIENT_ID/rotate_secret" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $API_TOKEN" + ``` + + diff --git a/src/content/docs/fundamentals/oauth/index.mdx b/src/content/docs/fundamentals/oauth/index.mdx new file mode 100644 index 00000000000..be5ec46925d --- /dev/null +++ b/src/content/docs/fundamentals/oauth/index.mdx @@ -0,0 +1,18 @@ +--- +title: OAuth Applications on Cloudflare +description: Create and integrate with Cloudflare using OAuth +pcx_content_type: navigation +sidebar: + order: 9 +products: + - fundamentals + - oauth +--- + +import { FeatureTable, Render } from "~/components"; + +## Availability + + + + diff --git a/src/content/docs/fundamentals/oauth/integrate-with-cloudflare.mdx b/src/content/docs/fundamentals/oauth/integrate-with-cloudflare.mdx new file mode 100644 index 00000000000..50b33f56f48 --- /dev/null +++ b/src/content/docs/fundamentals/oauth/integrate-with-cloudflare.mdx @@ -0,0 +1,20 @@ +--- +title: Integrate your OAuth client with Cloudflare +pcx_content_type: how-to +description: After registering an application, use these endpoints to integrate your OAuth client with Cloudflare. +sidebar: + order: 5 +products: + - fundamentals + - oauth +--- + +After [registering an application](/fundamentals/oauth/create-an-oauth-client/), use these endpoints to integrate your OAuth client with Cloudflare. + +- Jwks: `https://dash.cloudflare.com/.well-known/jwks.json` +- Open ID config: `https://dash.cloudflare.com/.well-known/openid-configuration` +- Authorization: `https://dash.cloudflare.com/oauth2/auth` +- Token: `https://dash.cloudflare.com/oauth2/token` +- Revoke: `https://dash.cloudflare.com/oauth2/revoke` +- Session logout: `https://dash.cloudflare.com/oauth2/logout` +- User info: `https://dash.cloudflare.com/oauth2/userinfo` diff --git a/src/content/docs/fundamentals/reference/index.mdx b/src/content/docs/fundamentals/reference/index.mdx index edf24d7ad79..80dd568e5f8 100644 --- a/src/content/docs/fundamentals/reference/index.mdx +++ b/src/content/docs/fundamentals/reference/index.mdx @@ -3,7 +3,7 @@ pcx_content_type: navigation title: Reference description: Find Cloudflare reference material including network details, HTTP headers, policies, and troubleshooting resources. sidebar: - order: 9 + order: 10 group: hideIndex: true head: @@ -13,6 +13,6 @@ products: - fundamentals --- -import { DirectoryListing } from "~/components" +import { DirectoryListing } from "~/components"; diff --git a/src/content/partials/fundamentals/self-managed-oauth.mdx b/src/content/partials/fundamentals/self-managed-oauth.mdx new file mode 100644 index 00000000000..5b0aade75ac --- /dev/null +++ b/src/content/partials/fundamentals/self-managed-oauth.mdx @@ -0,0 +1,7 @@ +--- +{} +--- + +OAuth allows third-party applications to securely access Cloudflare resources without requiring users to share long-lived API tokens. As an industry-standard protocol for authorization, OAuth 2.0 enables applications to obtain limited access to user accounts on an HTTP service. + +[Learn more about OAuth](https://www.cloudflare.com/learning/access-management/what-is-oauth/) diff --git a/src/content/plans/index.json b/src/content/plans/index.json index 39621d8cdcd..dcae5fbff76 100644 --- a/src/content/plans/index.json +++ b/src/content/plans/index.json @@ -15,6 +15,20 @@ } } }, + "self_managed_oauth": { + "title": "Self-managed OAuth Apps", + "link": "/fundamentals/oauth/", + "properties": { + "availability": { + "title": "Availability", + "summary": "Available on all plans", + "free": "Yes", + "pro": "Yes", + "biz": "Yes", + "ent": "Yes" + } + } + }, "version_management": { "title": "Version Management", "link": "/version-management/",