OIDC Code Flow with PKCE for Manually Built Facebook Login Flows

For developers interested in building and maintaining their own login integrations, Facebook Login supports the OpenID Connect (OIDC) standard’s Authorization Code flow with Proof Key for Code Exchange (PKCE), providing a path for developers to improve how they verify the identity of users that interact with their application(s).

Prerequisites

Developers should review the Manually Build a Login Flow guide which covers the core concepts needed to offer Facebook Login outside of Facebook’s officially supported SDKs. Additionally, developers should review the OIDC Specification and PKCE Specification, which highlights the details needed to request and handle responses from Login Service providers offering OIDC supported login flows.

Limitations

While OIDC Authentication Token support is available for manually built login flows, Limited Login isn’t available for this version of Facebook’s login flow. To learn more about supporting Limited Login in your iOS applications, we recommend reviewing the Limited Login documentation.

Logging People In

Creating a Code Verifier and Code Challenge

Before sending users through Facebook’s login dialog, you’ll need to generate a code verifier for each session. A code verifier is a cryptographically random string using alphanumeric and punctuation (-._~) characters, ensuring that each login session is unique. This string should be between 43 and 128 characters long with enough randomness to make it impractical to guess the value.

Once generated, you can then use the code verifier to calculate a code challenge for the login session. There are two ways to generate this value:

1. S256 (Recommended): The code challenge is a Base64URL (with no padding) encoded SHA256 hash of the code verifier:
   code_challenge = BASE64URL_ENCODE(SHA256(code_verifier).
2. plain: The code challenge is the same value as the code verifier:
   code_challenge = code_verifier.

   Use this method only if your app has technical difficulty generating a SHA256 hash.

Sending the Authorization Request

When constructing the link to direct users towards Facebook’s Login Dialog, the following parameters are relevant based on the OIDC specification:

An example link that your application might generate would look as follows:

https://www.facebook.com/v11.0/dialog/oauth?
  client_id={app-id} // Replace with your application’s ID
  &scope=openid
  &response_type=code
  &redirect_uri={"https://www.domain.com/login"}  // Replace with your Redirect URI      
  &state={"state123abc"} // Replace with your State param
  &code_challenge={"E91k-123k123-115X"} // Replace with your generated code_challenge
  &code_challenge_method=S256 // Replace with the method used to generate the code_challenge
  $nonce={"123"} // Replace with a randomly generated nonce value

Once the user completes the login flow, an example response would look as follows:

https://www.domain.com/login?state=state123abc&code={authorization-code}

Exchanging an Authorization Code Once your application receives the Authorization Code at your specified Redirect URI, your application should prepare to exchange the code for an Authentication Token and an Access Token. Facebook provides the /oauth/access_token endpoint to perform this exchange, which you can follow the Exchanging Code for an Access Token guide to configure your request.

Two of the parameters have been updated for OIDC Code Flow with PKCE support: The client_secret parameter is now optional. If not included in your request, you must specify the code_verifier. The code_verifier is an optional parameter, but is required if the client_secret parameter isn’t included. The value of this parameter should be the code_verifier generated before sending the user to Facebook’s Login Dialog.

A request to the Token Exchange Endpoint should look as follows:

Exchanging an Authorization Code

Once your application receives the Authorization Code at your specified Redirect URI, your application should prepare to exchange the code for an Authentication Token and an Access Token. Facebook provides the /oauth/access_token endpoint to perform this exchange, which you can follow the Exchanging Code for an Access Token guide to configure your request.

Two of the parameters have been updated for OIDC Code Flow with PKCE support:

1. The client_secret parameter is now optional. If not included in your request, you must specify the code_verifier.
2. The code_verifier is an optional parameter, but is required if the client_secret parameter isn’t included. The value of this parameter should be the code_verifier generated before sending the user to Facebook’s Login Dialog.

A request to the Token Exchange Endpoint should look as follows:

GET https://graph.facebook.com/v11.0/oauth/access_token?
  client_id={app-id} // Replace with your application’s ID
  &redirect_uri={"https://www.domain.com/login"}  // Must match the Redirect URI stated in the Authorization Request
  &code_verifier={code-verifier} // Replace with generated code verifier
  &code={authorization-code} // Replace with Authorization Code 

If successful, your application will receive this response:

{
     "access_token": {access-token},
     "token_type": {type},
     "expires_in": {seconds-til-expiration},
     "id_token": {id-token}
}

Reading the Authentication Token

The Authentication Token is a JSON Web Token (JWT) containing basic details shared by the user with your application. You can use a JWT Parser to review the contents of the token as well as validate the response from Facebook.

Next Steps

With the Authentication and Access Tokens returned to your application, it is recommended that your application validate the Authentication token sent from Facebook. To validate the OIDC Authentication Token, developers should follow the Validating the Limited Login OIDC Token documentation.