Struct oxide_auth::code_grant::extensions::Pkce

pub struct Pkce { /* fields omitted */ }

Proof Key for Code Exchange by OAuth Public Clients

Auth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack. This specification describes the attack as well as a technique to mitigate against the threat through the use of Proof Key for Code Exchange (PKCE, pronounced "pixy").

(from the respective RFC 7636)

In short, public clients share a verifier for a secret token when requesting their initial authorization code. When they then make a second request to the autorization server, trading this code for an access token, they can credible assure the server of their identity by presenting the secret token.

The simple plain method only prevents attackers unable to snoop on the connection from impersonating the client, while the S256 method, which uses one-way hash functions, makes any attack short of reading the victim client's memory infeasible.

Support for the plain method is OPTIONAL and must be turned on explicitely.

Methods

impl Pkce

pub fn required() -> Pkce

A pkce extensions which requires clients to use it.

pub fn optional() -> Pkce

Pkce extension which will check verifiers if present but not require them.

pub fn allow_plain(&mut self)

Allow usage of the less secure plain verification method. This method is NOT secure an eavesdropping attacker such as rogue processes capturing a devices requests.

pub fn challenge(
    &self,
    method: Option<Cow<str>>,
    challenge: Option<Cow<str>>
) -> Result<Option<Value>, ()>

Create the encoded method for proposed method and challenge.

The method defaults to plain when none is given, effectively offering increased compatibility but less security. Support for plain is optional and needs to be enabled explicitely through Pkce::allow_plain. This extension may also require clients to use it, in which case giving no challenge also leads to an error.

The resulting string MUST NOT be publicly available to the client. Otherwise, it would be trivial for a third party to impersonate the client in the access token request phase. For a SHA256 methods the results would not be quite as severe but still bad practice.

pub fn verify(
    &self,
    method: Option<Value>,
    verifier: Option<Cow<str>>
) -> Result<(), ()>

Verify against the encoded challenge.

When the challenge is required, ensure again that a challenge was made and a corresponding method data is present as an extension. This is not strictly necessary since clients should not be able to delete private extension data but this check does not cost a lot.

When a challenge was agreed upon but no verifier is present, this method will return an error.

Trait Implementations

impl AuthorizationAddon for Pkce

fn execute(&self, request: &dyn AuthorizationRequest) -> AddonResult

Provides data for this request or signals faulty data.

impl AccessTokenAddon for Pkce

fn execute(
    &self,
    request: &dyn AccessTokenRequest,
    data: Option<Value>
) -> AddonResult

Process an access token request, utilizing the extensions stored data if any.

impl GrantExtension for Pkce

fn identifier(&self) -> &'static str

An unique identifier distinguishing this extension type for parsing and storing. Obvious choices are the registered names as administered by IANA or private identifiers.