Facebook Login

OIDC Code Flow with PKCE for Manually Built Facebook Login Flows

Updated: Jul 18, 2023

Be aware that this functionality is still in testing.

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:

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).

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:

Parameter	Description	Required?	Example
`client_id`	The app ID for your Facebook app.	Required	`client_id=123456789`
`scope`	A comma or space separated list of permissions your application is requesting from the user through the Login Dialog To use OIDC, you must include openid in the list of permissions.	Required	`scope=openid`
`response_type`	Indicates the type of response to be returned To use the Authorization Code flow, response_type must be set to code.	Required	`response_type=code`
`redirect_uri`	The URI the user will be redirected towards after completing the login flow.	Required	`redirect_uri=https://www.domain.com/login`
`state`	This value will be returned, unchanged, to your redirect_uri and is used to prevent Cross-site Request Forgery.	Recommended	`state=state123abc`
`code_challenge`	Value generated by the developer to confirm that they originated the request. This value is required to use the PKCE protocol.	Required	`code_challenge=E91k-123k123-115X`
`code_challenge_method`	Indicates how the application calculated the code_challenge, defaulting to plain if not included. Values include S256 and plain.	Recommended	`code_challenge_method=S256`
`nonce`	A randomly generated string to further verify the Authentication Token.	Required	`nonce=123`

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:

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:

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.

Did you find this page helpful?