Constructing a PKCE-Compliant Registration URL in FusionAuth

[wesley]

We want to add a Sign-Up button on our non-FusionAuth-hosted website that redirects users to the FusionAuth registration page.

Since we have PKCE (Proof Key for Code Exchange) enabled, we cannot use the standard registration URL provided in the FusionAuth UI, as noted in GitHub Issue #686.

Questions:

1. Is there a FusionAuth-generated URL that automatically includes the required PKCE parameters, cookies, and redirects users to the registration page?
2. If not, how can we correctly construct a PKCE-compliant registration URL?

[wesley]

Yes, you can manually construct a registration URL that includes PKCE values.

1. Understanding the Registration URL with PKCE

The /oauth2/register endpoint works similarly to the /oauth2/authorize endpoint but is used for user registration. Both support PKCE.
Example URLs:

• Standard Authorization URL:

https://your-fusionauth-instance/oauth2/authorize?
client_id=yourClientId&
response_type=code&
redirect_uri=https://yourapp.com/oauth-callback

• Registration URL (Same Structure, Different Endpoint):

https://your-fusionauth-instance/oauth2/register?
client_id=yourClientId&
response_type=code&
redirect_uri=https://yourapp.com/oauth-callback

Since PKCE is enabled, you must append PKCE parameters:

• code_challenge (derived from code_verifier)
• code_challenge_method=S256

2. Generating PKCE Parameters

Your application must generate a code_verifier and code_challenge before redirecting to FusionAuth’s registration page.

Node.js Example:

const crypto = require('crypto');

function base64URLEncode(str) {
  return str.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
}

function sha256(buffer) {
  return crypto.createHash("sha256").update(buffer).digest();
}

function generateVerifier() {
  return base64URLEncode(crypto.randomBytes(32));
}

function generateChallenge(verifier) {
  return base64URLEncode(sha256(verifier));
}

// Generate PKCE values
const codeVerifier = generateVerifier();
const codeChallenge = generateChallenge(codeVerifier);

console.log("Code Verifier:", codeVerifier);
console.log("Code Challenge:", codeChallenge);

3. Constructing the Registration URL

Once you have the code challenge, construct the registration URL as follows:

https://your-fusionauth-instance/oauth2/register?
client_id=yourClientId&
response_type=code&
redirect_uri=https://yourapp.com/oauth-callback&
code_challenge=yourGeneratedCodeChallenge&
code_challenge_method=S256

4. Completing the PKCE Flow After Registration

After the user completes registration, FusionAuth will redirect them to your app with an authorization code.
Your app must then exchange this code for an access token by sending the code_verifier to /oauth2/token.

For full details on the PKCE flow, see:

• Using OAuth and PKCE with FusionAuth

Summary

• There’s no auto-generated PKCE registration URL, but you can manually construct one.
• Generate the PKCE values before redirecting users to /oauth2/register.
• Complete the PKCE flow by exchanging the authorization code with the code_verifier.