Skip to content

feat(embedded): add PKCE (S256) to the embedded authorize flow - #1141

Open
pmathew92 wants to merge 1 commit into
v5_developmentfrom
feat/embedded_pkce
Open

pmathew92 wants to merge 1 commit into
v5_developmentfrom
feat/embedded_pkce

Conversation

@pmathew92

@pmathew92 pmathew92 commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Changes

Adds PKCE to every embedded /e/authorize flow. The server accepts code_challenge and code_challenge_method on the first /e/authorize call, binds the authorization code to the challenge, and then requires the matching code_verifier at /oauth/token. Clients that enforce PKCE, and public clients on tenants with the PKCE-required setting, are rejected without it, so the SDK now always sends it.

How it works

  • authorize() creates a new code verifier for each flow, sends its code_challenge with code_challenge_method: "S256", and creates the flow state with the verifier.
  • Each continuation only updates the auth_session in that state, so the verifier is kept for the whole flow.
  • Final steps read the verifier when they are built and send it as code_verifier with the token exchange. This matters because the state is cleared as soon as the server issues the code, before the exchange runs.
  • If the challenge can't be created (SHA-256 unavailable), authorize() fails locally without sending a request. It never falls back to a flow without PKCE.
  • The verifier is never exposed to the app or logged, and there is no option to turn PKCE off.

Classes and methods

  • AlgorithmHelper moves from provider/AlgorithmHelper.java to util/AlgorithmHelper.kt as an internal open class, so the web-auth and embedded flows share one implementation. Behavior is unchanged. PKCE.java and its tests only change their import.
  • EmbeddedAuthState now holds codeVerifier and a nullable authSession. Its toString hides both.
  • EmbeddedAuthClient gains an internal constructor that takes an AlgorithmHelper, used by tests. The public EmbeddedAuthClient(auth0) constructor is unchanged.
  • No public API changes. examples/embedded-auth/authorize.md has a short note that PKCE is added automatically.

Testing

  • This change adds unit test coverage

  • This change adds integration test coverage

  • This change has been tested on the latest version of the platform/language or why not

Checklist

@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Team
  • Run ID: 709569ab-4935-4fd1-9903-e7b183287132

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@pmathew92 pmathew92 changed the title feat(embedded): add PKCE (S256) to the embedded authorize flow [non-main] feat(embedded): add PKCE (S256) to the embedded authorize flow Nov 16, 2026
/** A random, base64url-encoded code verifier made of 32 random bytes. */
open fun generateCodeVerifier(): String {
val code = ByteArray(32)
SecureRandom().nextBytes(code)
@pmathew92
pmathew92 marked this pull request as ready for review November 16, 2026 05:58
@pmathew92
pmathew92 requested a review from a team as a code owner November 16, 2026 05:58
)
)
}
transactionState = EmbeddedAuthState(codeVerifier = verifier)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The verifier is stored here, when the request is built, but the session is added later in updateSessionFromFailure when a response arrives. With two overlapping authorize() calls (a double tap, or one built while another starts) the state can end up as verifier 2 with session 1, and the user only finds out at the token exchange with SessionExpired. Consider capturing the verifier in the authorize request's failure handler and setting EmbeddedAuthState(verifier, session) when the continuation arrives, so the two always arrive together.

when (error.error) {
is EmbeddedAuthError.InsufficientAuthorization ->
error.authSession?.let { transactionState = EmbeddedAuthState(it) }
error.authSession?.let { session -> transactionState = transactionState?.copy(authSession = session) }

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

transactionState?.copy(...) silently drops the rotated session when the state is already null, for example an old authorize request re-run after the flow ended or after a terminal error. The next step then fails with NoActiveSession; before this change the state was always created here. Setting the full state for the authorize step (see the comment on line 94) would cover this too.

* Embedded Authorization is currently in [Beta](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#beta). Please reach out to Auth0 support to get it enabled for your tenant.
*/
public class EmbeddedAuthClient(private val auth0: Auth0) {
public class EmbeddedAuthClient internal constructor(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This internal constructor is callable from Java (Kotlin doesn't mangle internal constructors, and AlgorithmHelper is an open class), so an app can inject a fixed verifier and bypass PKCE. Consider a private primary constructor with an internal factory for tests.

/**
* The state of the flow in progress, created by `authorize()` with the PKCE [codeVerifier] that is sent with
* the token exchange. [authSession] is the latest session from the server, and is `null` until the first
* response arrives. Neither is ever logged.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Neither is ever logged" doesn't hold with DefaultClient.enableLogging(true): it logs request bodies at BODY level without redaction, so code_verifier appears in the /oauth/token request. Either redact it in the logging interceptor or reword to say the SDK itself doesn't log it.


// ── PKCE ─────────────────────────────────────────────────────────────────────

@Test

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please pin the exact key sets of the Initiate and /oauth/token bodies, since the Initiate schema rejects unknown fields and the exchange must not send redirect_uri. Also worth adding: no code_challenge or code_verifier in the identify, challenge and verifyOtp bodies, invalid_grant at the exchange giving SessionExpired, and the overlapping authorize case.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants