Base Client

class oauthlib.oauth2.Client(client_id, default_token_placement='auth_header', token_type='Bearer', access_token=None, refresh_token=None, mac_key=None, mac_algorithm=None, token=None, scope=None, state=None, redirect_url=None, state_generator=<function generate_token>, code_verifier=None, code_challenge=None, code_challenge_method=None, **kwargs)[source]

Base OAuth2 client responsible for access token management.

This class also acts as a generic interface providing methods common to all client types such as prepare_authorization_request and prepare_token_revocation_request. The prepare_x_request methods are the recommended way of interacting with clients (as opposed to the abstract prepare uri/body/etc methods). They are recommended over the older set because they are easier to use (more consistent) and add a few additional security checks, such as HTTPS and state checking.

Some of these methods require further implementation only provided by the specific purpose clients such as oauthlib.oauth2.MobileApplicationClient and thus you should always seek to use the client class matching the OAuth workflow you need. For Python, this is usually oauthlib.oauth2.WebApplicationClient.

add_token(uri, http_method='GET', body=None, headers=None, token_placement=None, **kwargs)[source]

Add token to the request uri, body or authorization header.

The access token type provides the client with the information required to successfully utilize the access token to make a protected resource request (along with type-specific attributes). The client MUST NOT use an access token if it does not understand the token type.

For example, the “bearer” token type defined in [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access token string in the request:

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer mF_9.B5f-4.1JqM

while the “mac” token type defined in [I-D.ietf-oauth-v2-http-mac] is utilized by issuing a MAC key together with the access token which is used to sign certain components of the HTTP requests:

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: MAC id="h480djs93hd8",
                    nonce="274312:dj83hs9s",
                    mac="kDZvddkndxvhGRXZhvuDjEWhGeE="
create_code_challenge(code_verifier, code_challenge_method=None)[source]

Create PKCE code_challenge derived from the code_verifier. See RFC7636 Section 4.2

Parameters:
  • code_verifier – REQUIRED. The code_verifier generated from create_code_verifier().
  • code_challenge_method –

    OPTIONAL. The method used to derive the code_challenge. Acceptable values include S256. DEFAULT is plain.

    The client then creates a code challenge derived from the code verifier by using one of the following transformations on the code verifier:

    plain
   code_challenge = code_verifier
S256
   code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

    If the client is capable of using S256, it MUST use S256, as S256 is Mandatory To Implement (MTI) on the server. Clients are permitted to use plain only if they cannot support S256 for some technical reason and know via out-of-band configuration that the server supports plain.

    The plain transformation is for compatibility with existing deployments and for constrained environments that can’t use the S256 transformation.
create_code_verifier(length)[source]

Create PKCE code_verifier used in computing code_challenge. See RFC7636 Section 4.1

Parameters:length – REQUIRED. The length of the code_verifier.

The client first creates a code verifier, “code_verifier”, for each OAuth 2.0 [RFC6749] Authorization Request, in the following manner:

code_verifier = high-entropy cryptographic random STRING using the
unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
from Section 2.3 of [RFC3986], with a minimum length of 43 characters
and a maximum length of 128 characters.
parse_request_body_response(body, scope=None, **kwargs)[source]

Parse the JSON response body.

If the access token request is valid and authorized, the authorization server issues an access token as described in Section 5.1. A refresh token SHOULD NOT be included. If the request failed client authentication or is invalid, the authorization server returns an error response as described in Section 5.2.

Parameters:
  • body – The response body from the token request.
  • scope – Scopes originally requested. If none is provided, the ones provided in the constructor are used.
Returns:

Dictionary of token parameters.
Raises:

Warning if scope has changed. oauthlib.oauth2.errors.OAuth2Error if response is invalid.

These response are json encoded and could easily be parsed without the assistance of OAuthLib. However, there are a few subtle issues to be aware of regarding the response which are helpfully addressed through the raising of various errors.

A successful response should always contain

access_token
The access token issued by the authorization server. Often a random string.
token_type
The type of the token issued as described in Section 7.1. Commonly Bearer.

While it is not mandated it is recommended that the provider include

expires_in
The lifetime in seconds of the access token. For example, the value “3600” denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.
scope
Providers may supply this in all responses but are required to only if it has changed since the authorization request.
parse_request_uri_response(*args, **kwargs)[source]

Abstract method used to parse redirection responses.

populate_code_attributes(response)[source]

Add attributes from an auth code response to self.

populate_token_attributes(response)[source]

Add attributes from a token exchange response to self.

prepare_authorization_request(authorization_url, state=None, redirect_url=None, scope=None, **kwargs)[source]

Prepare the authorization request.

This is the first step in many OAuth flows in which the user is redirected to a certain authorization URL. This method adds required parameters to the authorization URL.

Parameters:
  • authorization_url – Provider authorization endpoint URL.
  • state – CSRF protection string. Will be automatically created if not provided. The generated state is available via the state attribute. Clients should verify that the state is unchanged and present in the authorization response. This verification is done automatically if using the authorization_response parameter with prepare_token_request.
  • redirect_url – Redirect URL to which the user will be returned after authorization. Must be provided unless previously setup with the provider. If provided then it must also be provided in the token request.
  • scope – List of scopes to request. Must be equal to or a subset of the scopes granted when obtaining the refresh token. If none is provided, the ones provided in the constructor are used.
  • kwargs – Additional parameters to included in the request.
Returns:

The prepared request tuple with (url, headers, body).
prepare_refresh_body(body='', refresh_token=None, scope=None, **kwargs)[source]

Prepare an access token request, using a refresh token.

If the authorization server issued a refresh token to the client, the client makes a refresh request to the token endpoint by adding the following parameters using the application/x-www-form-urlencoded format in the HTTP request entity-body:

Parameters:
  • refresh_token – REQUIRED. The refresh token issued to the client.
  • scope – OPTIONAL. The scope of the access request as described by Section 3.3. The requested scope MUST NOT include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner. Note that if none is provided, the ones provided in the constructor are used if any.
prepare_refresh_token_request(token_url, refresh_token=None, body='', scope=None, **kwargs)[source]

Prepare an access token refresh request.

Expired access tokens can be replaced by new access tokens without going through the OAuth dance if the client obtained a refresh token. This refresh token and authentication credentials can be used to obtain a new access token, and possibly a new refresh token.

Parameters:
  • token_url – Provider token refresh endpoint URL.
  • refresh_token – Refresh token string.
  • body – Existing request body (URL encoded string) to embed parameters into. This may contain extra parameters. Default ‘’.
  • scope – List of scopes to request. Must be equal to or a subset of the scopes granted when obtaining the refresh token. If none is provided, the ones provided in the constructor are used.
  • kwargs – Additional parameters to included in the request.
Returns:

The prepared request tuple with (url, headers, body).
prepare_request_body(*args, **kwargs)[source]

Abstract method used to create request bodies.

prepare_request_uri(*args, **kwargs)[source]

Abstract method used to create request URIs.

prepare_token_request(token_url, authorization_response=None, redirect_url=None, state=None, body='', **kwargs)[source]

Prepare a token creation request.

Note that these requests usually require client authentication, either by including client_id or a set of provider specific authentication credentials.

Parameters:
  • token_url – Provider token creation endpoint URL.
  • authorization_response – The full redirection URL string, i.e. the location to which the user was redirected after successful authorization. Used to mine credentials needed to obtain a token in this step, such as authorization code.
  • redirect_url – The redirect_url supplied with the authorization request (if there was one).
  • state –
  • body – Existing request body (URL encoded string) to embed parameters into. This may contain extra parameters. Default ‘’.
  • kwargs – Additional parameters to included in the request.
Returns:

The prepared request tuple with (url, headers, body).
prepare_token_revocation_request(revocation_url, token, token_type_hint='access_token', body='', callback=None, **kwargs)[source]

Prepare a token revocation request.

Parameters:
  • revocation_url – Provider token revocation endpoint URL.
  • token – The access or refresh token to be revoked (string).
  • token_type_hint – "access_token" (default) or "refresh_token". This is optional and if you wish to not pass it you must provide token_type_hint=None.
  • body –
  • callback – A jsonp callback such as package.callback to be invoked upon receiving the response. Not that it should not include a () suffix.
  • kwargs – Additional parameters to included in the request.
Returns:

The prepared request tuple with (url, headers, body).

Note that JSONP request may use GET requests as the parameters will be added to the request URL query as opposed to the request body.

An example of a revocation request

POST /revoke HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token

An example of a jsonp revocation request

GET /revoke?token=agabcdefddddafdd&callback=package.myCallback HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

and an error response

package.myCallback({"error":"unsupported_token_type"});

Note that these requests usually require client credentials, client_id in the case for public clients and provider specific authentication credentials for confidential clients.

token_types

Supported token types and their respective methods

Additional tokens can be supported by extending this dictionary.

The Bearer token spec is stable and safe to use.

The MAC token spec is not yet stable and support for MAC tokens is experimental and currently matching version 00 of the spec.