Skip to main content

Initiating the OAuth Flow

To start the OAuth process using PKCE, you'll need to generate a code challenge and code verifier, redirect the user to the authorize URL, and handle the redirect after the user authorizes your application.

  1. Generate Code Verifier and Challenge: Use a suitable library or method to generate a code verifier and transform it into a code challenge. The verifier should be a random string, and the challenge is typically a SHA256 hash of the verifier, base64 URL encoded.

  2. Redirect User to Authorize URL: Construct the authorization URL with the necessary parameters and redirect the user to it. Your URL should look like this:

Dev Authorize URL
https://optimal-wren-60.clerk.accounts.dev/oauth/authorize
Prod Authorize URL
https://clerk.stiegleredtech.org/oauth/authorize
Authorize Params
?response_type=code&client_id=<YOUR_CLIENT_ID>&redirect_uri=<YOUR_CALLBACK_URL>&code_challenge=<YOUR_CODE_CHALLENGE>&code_challenge_method=S256
  1. User Authorization: The user will be asked to authorize your application. Upon successful authorization, they will be redirected back to your application with a code in the URL.

Handling the Redirect​

After the user authorizes your application, they will be redirected back to the specified callback URL with an authorization code.

  1. Capture the Authorization Code: On the page or route specified as your redirect URI, capture the authorization code from the query parameters.

  2. Store the Code Verifier: Ensure the code verifier used to generate the challenge is securely stored and accessible for the next step in the backend token exchange.

In the next section, I will discuss exchanging the authorization code for an access token using the PKCE method.

Exchanging the Authorization Code​

Once you have the authorization code from the OAuth provider, you need to exchange it for an access token. This is done in your backend to ensure the security of your code verifier.

  1. Prepare Token Request: Create a POST request to the token endpoint of the OAuth provider. Include the following parameters in the request:

    • grant_type: Should be set to authorization_code.
    • code: The authorization code received from the OAuth provider.
    • redirect_uri: The same redirect URI used in the authorization request.
    • client_id: Your application's client ID.
    • code_verifier: The code verifier stored from when you generated the code challenge.

    The request should be made to the token fetch URL:

    Dev Token URL
    https://optimal-wren-60.clerk.accounts.dev/oauth/token
    Prod Token URL
    https://clerk.stiegleredtech.org/oauth/token

  2. Make the Request: Use a server-side HTTP client to make the request to the token endpoint. Handle the response from the OAuth provider:

    • If successful, you will receive an access token and possibly a refresh token in the response.
    • Handle any errors that may occur during the token exchange process.

Fetching User Information​

Once you have the access token, you can use it to request user information from the OAuth provider's userinfo endpoint.

  1. Prepare Userinfo Request:
    • Endpoints:
    Dev User Info URL
      https://optimal-wren-60.clerk.accounts.dev/oauth/userinfo
    Prod User Info URL
    https://clerk.stiegleredtech.org/oauth/userinfo
    • Headers: Include the access token in the Authorization header as a Bearer token.
      • Authorization: Bearer <ACCESS_TOKEN>

The request should be made to the user info URL: https://optimal-wren-60.clerk.accounts.dev/oauth/userinfo.

  1. Make the Request: Use a server-side HTTP client to make the request to the userinfo endpoint. Parse the response to retrieve user details.

  2. Handle the Response:

  • If successful, the response will contain user details such as email, name, and other information based on the scopes you requested.
   {
       "object": "oauth_user_info",
       "instance_id": "ins_2O4Ak02T4fDmKKv6tK5h0WJ8ou8",
       "email": "me@oauth-client.com",
       "email_verified": true,
       "family_name": "first_name",
       "given_name": "last_name",
       "name": "first_name last_name",
       "username": "my_username",
       "picture": "https://profile_image_public_url/img.png",
       "user_id": "my_user_id",
   }

Error Handling​

During the OAuth process, various errors can occur, such as invalid requests, denied access, or server issues. Here's how to handle common errors:

  1. Invalid Request: Ensure all required parameters are correctly included in your requests. Double-check the error message for hints on what might be missing or incorrect.

  2. Access Denied: The user may deny authorization. Handle this gracefully in your application, providing the user with appropriate feedback and options.

  3. Server Errors: If the OAuth provider encounters an error, it will typically return a 500 series error. Log these errors and consider implementing retry logic or alerting mechanisms.

  4. Invalid or Expired Token: Access tokens can expire or be revoked. Ensure your application can handle token expiration gracefully, prompting the user to re-authenticate if necessary.

Support and Contact​

If you encounter issues or have further questions, please contact our support team:

We're here to ensure a smooth integration and deployment process for you and your team.