OAuth with Cloudflare

Cloudflare runs a global network that provides CDN, DNS, security, and developer services such as Workers. With Cloudflare OAuth, third-party apps can sign users in with their Cloudflare account and access Cloudflare resources on their behalf, without asking them to share long-lived API tokens.

How does the integration work?

You can use the Cloudflare OAuth adapter in Appwrite Auth to let users sign in with their Cloudflare account. Tools that manage Workers, DNS records, or other Cloudflare resources can sign users in with the same account they're about to manage. The session stores Cloudflare's access token as providerAccessToken, so your server can call the Cloudflare API for the user.

Appwrite requests user-details.read for the user's name and email, plus offline_access so the session gets a refresh token. Cloudflare requires PKCE, which Appwrite handles for you. Cloudflare doesn't report whether the email is verified, so Appwrite stores it as unverified. If another user in your project already has that email, Appwrite redirects to your failure URL instead of signing the user in. To connect Cloudflare to that account, have the user sign in first and then start the OAuth flow from the browser, which links Cloudflare as a new identity.

How to implement

To implement the Cloudflare OAuth adapter in Appwrite Auth, there are several steps you must complete:

Step 1: Create an OAuth client on Cloudflare

You need the Super Administrator, Administrator, or OAuth Client Write role on the Cloudflare account. Log in to the Cloudflare dashboard, select your account, go to Manage Account > OAuth clients, and select Create client.

Fill in the configuration details:

• Client name: the name users see on Cloudflare's consent screen.
• Response type and Grant type: use the authorization code flow.
• Token authentication method: choose the method that sends the client secret in the request body (client_secret_post). Appwrite posts the client ID and secret with each token request.
• Redirect URLs: temporarily enter https://temporary-endpoint.com/. You'll replace it with the URI from Appwrite in the next step.

Select Continue and add the user-details.read scope. Select Create client, then save the Client ID and Client Secret. Cloudflare shows the secret only once.

New clients are private, so only members of the Cloudflare account that owns the client can authorize it. To let any Cloudflare user sign in, make the client public. Cloudflare requires a logo, a client URL, and domain verification of that URL first, and the change can't be undone.

Step 2: Add Cloudflare OAuth adapter to your Appwrite project

For this step, you must create an account on Appwrite Cloud or self-host Appwrite if you haven't already. In your Appwrite project, head over to the Auth page, open the Settings tab, and click Cloudflare under the OAuth2 Providers section.

Paste the client's credentials into the Client ID and Client Secret fields, turn the provider on, and click Update. Appwrite checks the credentials with Cloudflare when you enable the provider and returns an error if Cloudflare rejects them.

Copy the Redirect URI shown in the form. On Appwrite Cloud it looks like https://<REGION>.cloud.appwrite.io/v1/account/sessions/oauth2/callback/cloudflare/<PROJECT_ID>, but always copy the exact value from the Console. Edit your OAuth client on Cloudflare and replace the temporary redirect URL with it.

Step 3: Test the provider

Start a session from your app with the OAuthProvider.Cloudflare value. With the Web SDK:

import { Client, Account, OAuthProvider } from 'appwrite';

const client = new Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>');

const account = new Account(client);

account.createOAuth2Session({
    provider: OAuthProvider.Cloudflare,
    success: 'https://example.com/success',
    failure: 'https://example.com/failed',
});

Add your app's domain as a web platform in your Appwrite project so Appwrite accepts the success and failure URLs. Follow the OAuth 2 login flow for other platforms and for server-side sign-in, and use refresh tokens to keep the Cloudflare access token current.

Read more about Cloudflare and Appwrite Auth

If you would like to learn more about Cloudflare and Appwrite Auth, we have some resources that you should visit: