Struct Client

pub struct Client<TE, TR, TT, TIR, RT, TRE>
where
    TE: ErrorResponse,
    TR: TokenResponse<TT>,
    TT: TokenType,
    TIR: TokenIntrospectionResponse<TT>,
    RT: RevocableToken,
    TRE: ErrorResponse,
{ /* private fields */ }

Stores the configuration for an OAuth2 client.

Error Types

To enable compile time verification that only the correct and complete set of errors for the Client function being invoked are exposed to the caller, the Client type is specialized on multiple implementations of the ErrorResponse trait. The exact ErrorResponse implementation returned varies by the RFC that the invoked Client function implements:

• Generic type TE (aka Token Error) for errors defined by RFC 6749 OAuth 2.0 Authorization Framework.
• Generic type TRE (aka Token Revocation Error) for errors defined by RFC 7009 OAuth 2.0 Token Revocation.

For example when revoking a token, error code unsupported_token_type (from RFC 7009) may be returned:

let res = client
    .revoke_token(AccessToken::new("some token".to_string()).into())
    .unwrap()
    .request(http_client);

assert!(matches!(res, Err(
    RequestTokenError::ServerResponse(err)) if matches!(err.error(),
        RevocationErrorResponseType::UnsupportedTokenType)));

Implementations

impl<TE, TR, TT, TIR, RT, TRE> Client<TE, TR, TT, TIR, RT, TRE>

where TE: ErrorResponse + 'static, TR: TokenResponse<TT>, TT: TokenType, TIR: TokenIntrospectionResponse<TT>, RT: RevocableToken, TRE: ErrorResponse + 'static,

pub fn new( client_id: ClientId, client_secret: Option<ClientSecret>, auth_url: AuthUrl, token_url: Option<TokenUrl>, ) -> Self

Initializes an OAuth2 client with the fields common to most OAuth2 flows.

Arguments

• client_id - Client ID
• client_secret - Optional client secret. A client secret is generally used for private (server-side) OAuth2 clients and omitted from public (client-side or native app) OAuth2 clients (see RFC 8252).
• auth_url - Authorization endpoint: used by the client to obtain authorization from the resource owner via user-agent redirection. This URL is used in all standard OAuth2 flows except the Resource Owner Password Credentials Grant and the Client Credentials Grant.
• token_url - Token endpoint: used by the client to exchange an authorization grant (code) for an access token, typically with client authentication. This URL is used in all standard OAuth2 flows except the Implicit Grant. If this value is set to None, the exchange_* methods will return Err(RequestTokenError::Other(_)).

pub fn set_auth_type(self, auth_type: AuthType) -> Self

Configures the type of client authentication used for communicating with the authorization server.

The default is to use HTTP Basic authentication, as recommended in Section 2.3.1 of RFC 6749. Note that if a client secret is omitted (i.e., client_secret is set to None when calling Client::new), AuthType::RequestBody is used regardless of the auth_type passed to this function.

pub fn set_redirect_uri(self, redirect_url: RedirectUrl) -> Self

Sets the redirect URL used by the authorization endpoint.

pub fn set_introspection_uri(self, introspection_url: IntrospectionUrl) -> Self

Sets the introspection URL for contacting the (RFC 7662) introspection endpoint.

pub fn set_revocation_uri(self, revocation_url: RevocationUrl) -> Self

Sets the revocation URL for contacting the revocation endpoint (RFC 7009).

See: revoke_token()

pub fn set_device_authorization_url( self, device_authorization_url: DeviceAuthorizationUrl, ) -> Self

Sets the the device authorization URL used by the device authorization endpoint. Used for Device Code Flow, as per RFC 8628.

pub fn authorize_url<S>(&self, state_fn: S) -> AuthorizationRequest<'_>

where S: FnOnce() -> CsrfToken,

Generates an authorization URL for a new authorization request.

Arguments

• state_fn - A function that returns an opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client.

Security Warning

Callers should use a fresh, unpredictable state for each authorization request and verify that this value matches the state parameter passed by the authorization server to the redirect URI. Doing so mitigates Cross-Site Request Forgery attacks. To disable CSRF protections (NOT recommended), use insecure::authorize_url instead.

pub fn exchange_code( &self, code: AuthorizationCode, ) -> CodeTokenRequest<'_, TE, TR, TT>

Exchanges a code produced by a successful authorization process with an access token.

Acquires ownership of the code because authorization codes may only be used once to retrieve an access token from the authorization server.

See https://tools.ietf.org/html/rfc6749#section-4.1.3.

pub fn exchange_password<'a, 'b>( &'a self, username: &'b ResourceOwnerUsername, password: &'b ResourceOwnerPassword, ) -> PasswordTokenRequest<'b, TE, TR, TT>

where 'a: 'b,

Requests an access token for the password grant type.

See https://tools.ietf.org/html/rfc6749#section-4.3.2.

pub fn exchange_client_credentials( &self, ) -> ClientCredentialsTokenRequest<'_, TE, TR, TT>

Requests an access token for the client credentials grant type.

See https://tools.ietf.org/html/rfc6749#section-4.4.2.

pub fn exchange_refresh_token<'a, 'b>( &'a self, refresh_token: &'b RefreshToken, ) -> RefreshTokenRequest<'b, TE, TR, TT>

where 'a: 'b,

Exchanges a refresh token for an access token

See https://tools.ietf.org/html/rfc6749#section-6.

pub fn exchange_device_code( &self, ) -> Result<DeviceAuthorizationRequest<'_, TE>, ConfigurationError>

Perform a device authorization request as per https://tools.ietf.org/html/rfc8628#section-3.1.

pub fn exchange_device_access_token<'a, 'b, 'c, EF>( &'a self, auth_response: &'b DeviceAuthorizationResponse<EF>, ) -> DeviceAccessTokenRequest<'b, 'c, TR, TT, EF>

where EF: ExtraDeviceAuthorizationFields, 'a: 'b,

Perform a device access token request as per https://tools.ietf.org/html/rfc8628#section-3.4.

pub fn introspect<'a>( &'a self, token: &'a AccessToken, ) -> Result<IntrospectionRequest<'a, TE, TIR, TT>, ConfigurationError>

Query the authorization server RFC 7662 compatible introspection endpoint to determine the set of metadata for a previously received token.

Requires that set_introspection_uri() have already been called to set the introspection endpoint URL.

Attempting to submit the generated request without calling set_introspection_uri() first will result in an error.

pub fn revoke_token( &self, token: RT, ) -> Result<RevocationRequest<'_, RT, TRE>, ConfigurationError>

Attempts to revoke the given previously received token using an RFC 7009 OAuth 2.0 Token Revocation compatible endpoint.

Requires that set_revocation_uri() have already been called to set the revocation endpoint URL.

Attempting to submit the generated request without calling set_revocation_uri() first will result in an error.

pub fn client_id(&self) -> &ClientId

Returns the Client ID.

pub fn auth_url(&self) -> &AuthUrl

Returns the authorization endpoint.

pub fn auth_type(&self) -> &AuthType

Returns the type of client authentication used for communicating with the authorization server.

pub fn token_url(&self) -> Option<&TokenUrl>

Returns the token endpoint.

pub fn redirect_url(&self) -> Option<&RedirectUrl>

Returns the redirect URL used by the authorization endpoint.

pub fn introspection_url(&self) -> Option<&IntrospectionUrl>

Returns the introspection URL for contacting the (RFC 7662) introspection endpoint.

pub fn revocation_url(&self) -> Option<&RevocationUrl>

Returns the revocation URL for contacting the revocation endpoint (RFC 7009).

See: revoke_token()

pub fn device_authorization_url(&self) -> Option<&DeviceAuthorizationUrl>

Returns the the device authorization URL used by the device authorization endpoint.

Trait Implementations

impl<TE, TR, TT, TIR, RT, TRE> Clone for Client<TE, TR, TT, TIR, RT, TRE>

where TE: ErrorResponse + Clone, TR: TokenResponse<TT> + Clone, TT: TokenType + Clone, TIR: TokenIntrospectionResponse<TT> + Clone, RT: RevocableToken + Clone, TRE: ErrorResponse + Clone,

fn clone(&self) -> Client<TE, TR, TT, TIR, RT, TRE>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<TE, TR, TT, TIR, RT, TRE> Debug for Client<TE, TR, TT, TIR, RT, TRE>

where TE: ErrorResponse + Debug, TR: TokenResponse<TT> + Debug, TT: TokenType + Debug, TIR: TokenIntrospectionResponse<TT> + Debug, RT: RevocableToken + Debug, TRE: ErrorResponse + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.