pub struct AuthClient { /* private fields */ }Expand description
Drives the OAuth 2.0 Authorization Code + PKCE flow against a Scribe
server. This type does not open a browser or run a redirect listener;
the embedding application is responsible for presenting
AuthClient::authorization_url to the user and obtaining the
resulting code however fits its own UI.
Implementations§
Source§impl AuthClient
impl AuthClient
pub fn new(http: Client, base_url: Url, client_id: impl Into<String>) -> Self
Sourcepub fn with_locale(self, locale: impl Into<String>) -> Self
pub fn with_locale(self, locale: impl Into<String>) -> Self
Asks the server for its messages in locale, a language tag such as
de or pt-BR, usually the language the app’s own interface is in.
The sign-in page from Self::authorization_url opens in it too.
Without one, the server uses the account’s language, or English.
Builds the URL the user’s browser should be sent to. redirect_uri
must match one registered for client_id server-side.
The authorize request is wrapped in the server’s /auth/logout
redirect, so whatever session the browser is holding for this server is
dropped before the authorize request is reached. Signing out only
clears this device’s tokens: the browser’s cookie store belongs to the
system, and an app has no way to reach into it. Without this, a session
cookie surviving sign-out lets the next sign-in complete without asking
for anything.
Clearing it at sign-in rather than at sign-out is what keeps the browser’s SSO session with the identity provider intact, so a returning user is asked for their email address instead of the whole credential flow.
AuthClient::authorization_url for callers that hold the challenge on
its own rather than the whole PkceChallenge — the FFI hands the
verifier to the host application to keep between the two halves of the
flow, so by this point only the challenge string is left.
Sourcepub async fn exchange_code(
&self,
redirect_uri: &str,
code: &str,
verifier: &str,
) -> Result<TokenSet, ScribeError>
pub async fn exchange_code( &self, redirect_uri: &str, code: &str, verifier: &str, ) -> Result<TokenSet, ScribeError>
Exchanges an authorization code (obtained after the user completes
the browser flow at AuthClient::authorization_url) for a token
set. verifier must be the same PkceChallenge used to build
that URL.
§Errors
Returns ScribeError::InvalidGrant if the code or verifier is
wrong or expired, or ScribeError::Http/ScribeError::Api on
other request failures.
Sourcepub async fn refresh(
&self,
refresh_token: &str,
) -> Result<TokenSet, ScribeError>
pub async fn refresh( &self, refresh_token: &str, ) -> Result<TokenSet, ScribeError>
Exchanges a refresh token for a new token set.
§Errors
Returns ScribeError::InvalidGrant if the refresh token is wrong,
expired, or revoked, or ScribeError::Http/ScribeError::Api on
other request failures.
Sourcepub async fn revoke(&self, token: &str) -> Result<(), ScribeError>
pub async fn revoke(&self, token: &str) -> Result<(), ScribeError>
Asks the server to invalidate a token, so signing out ends the session there and then rather than leaving a refresh token usable until it expires on its own.
Pass the refresh token when there is one: revoking it takes the access tokens issued alongside it with it. Passing an access token instead revokes only that token.
Per RFC 7009 the server answers successfully whether or not it recognised the token, so a success here means the request was accepted, not that something was necessarily revoked.
§Errors
Returns ScribeError::Http if the request could not be sent, or
ScribeError::Api if the server refused it.