Struct OAuthClient

Source

pub struct OAuthClient { /* private fields */ }

Expand description

An application’s registration with one provider.

Debug redacts the secret. This type ends up in application state and in the development error page, and a client secret in either is a credential that has to be rotated.

Implementations§

Source §

impl OAuthClient

Source

pub fn new(provider: Provider) -> OAuthClient

Source

pub fn credentials( self, client_id: impl Into<String>, client_secret: impl Into<String>, ) -> OAuthClient

Source

pub fn redirect_uri(self, uri: impl Into<String>) -> OAuthClient

The URL the provider redirects back to.

It must match what is registered with the provider byte for byte, including the scheme and any trailing slash — a mismatch is rejected at the token endpoint, after the visitor has already consented, which is why the error is so often reported as “it worked yesterday”.

Source

pub fn scopes(self, scopes: impl Into<Scopes>) -> OAuthClient

Ask for these scopes instead of the provider’s defaults.

Source

pub fn scope(self, scope: impl Into<String>) -> OAuthClient

Add one scope to whatever is already being asked for.

Source

pub fn with( self, name: impl Into<String>, value: impl Into<String>, ) -> OAuthClient

A provider-specific authorisation parameter: prompt, access_type, login_hint, hd.

Setting a name the provider preset already sets replaces it rather than sending it twice — two prompt values in one URL is a request most providers reject and none interpret the way the caller meant.

Source

pub fn using(self, http: Client) -> OAuthClient

Use a particular HTTP client — a shared one, or Http::fake() in tests.

Source

pub fn requested_scopes(&self) -> Scopes

What is actually being asked for: the application’s scopes, or the provider’s defaults when it did not say.

Source

pub fn authorize_url(&self) -> Authorization

Leg one: the URL to send a visitor to, with a fresh state and verifier.

The caller has to keep both — see OAuthClient::begin, which keeps them for you.

Source

pub fn begin(&self, guard: &StateGuard) -> Result<Authorization, OAuthError>

Leg one, with the state issued and remembered by a guard.

Source

pub fn authorize_url_for(&self, state: &str, pkce: &Pkce) -> String

The authorisation URL for a state and verifier chosen elsewhere.

PKCE is not a parameter here and there is no overload without it: OAuth 2.1 requires it for every authorisation code flow, and a client that could be talked into omitting it is a client that will be.

Source

pub async fn callback( &self, query: &str, guard: &StateGuard, ) -> Result<TokenResponse, OAuthError>

Leg two: everything the callback has to do, in one call.

query is the raw query string the provider redirected to — in a handler, req.target()’s query part.

The state is checked before the provider’s own error is read. An error response is still a response to a request somebody made, and answering an unsolicited one — even to say “access denied” — is a page an attacker can drive.

Source

pub async fn exchange( &self, code: &str, verifier: &str, ) -> Result<TokenResponse, OAuthError>

Trade an authorisation code for a token.

Source

pub async fn refresh( &self, refresh_token: &str, ) -> Result<TokenResponse, OAuthError>

Trade a refresh token for a new access token, RFC 6749 §6.

The response may or may not carry a new refresh token. Providers disagree, and one that rotates them means the old one stops working the moment this returns — so store whatever comes back rather than assuming the one you had is still good.

Source

pub async fn revoke(&self, token: &str, hint: &str) -> Result<(), OAuthError>

Revoke a token, RFC 7009.

hint is access_token or refresh_token; it is advisory, and a provider that ignores it still has to search both. Revoking a refresh token usually revokes the access tokens issued from it — usually, because RFC 7009 §2.1 only recommends it.

Source