diff options
author | Jonathan Huot <jonathan.huot@gmail.com> | 2019-10-18 17:17:43 +0200 |
---|---|---|
committer | Jonathan Huot <jonathan.huot@gmail.com> | 2019-10-18 17:17:43 +0200 |
commit | 3a4459bdd83744a3cd3a698997a6a4b483b0c6e0 (patch) | |
tree | dc12ec8c3d21d22ec5d2b1452fe4a4c1d1bad432 | |
parent | 2063ac37d63502f4db7ade95078cac6c28787215 (diff) | |
download | oauthlib-3a4459bdd83744a3cd3a698997a6a4b483b0c6e0.tar.gz |
Initial custom grant type documentation.
Improved Grant Type section to let developers create or implement their own custom grant type. Or also help them implementing new RFC.
-rw-r--r-- | docs/oauth2/grants/custom_grant.rst | 49 | ||||
-rw-r--r-- | docs/oauth2/grants/custom_validators.rst | 12 | ||||
-rw-r--r-- | docs/oauth2/grants/grants.rst | 28 | ||||
-rw-r--r-- | docs/oauth2/grants/refresh.rst | 6 | ||||
-rw-r--r-- | tox.ini | 2 |
5 files changed, 85 insertions, 12 deletions
diff --git a/docs/oauth2/grants/custom_grant.rst b/docs/oauth2/grants/custom_grant.rst new file mode 100644 index 0000000..ba5446c --- /dev/null +++ b/docs/oauth2/grants/custom_grant.rst @@ -0,0 +1,49 @@ +Custom Grant type +----------------- + +Writing a custom grant type can be useful to implement a specification +which is in an early draft, or implement a grant provided by a +specific OAuth2.0 Authorization Server documentation but not provided +by oauthlib. For information, any grant types with a clear +specification can be integrated in oauthlib, just make a PR for that +!. See :doc:`how to contribute here </contributing>`. + +Please find below an example of how to create a new grant and use it +in an endpoint: + +.. contents:: Tutorial Contents + :depth: 3 + + +1. Define your Grant Type +------------------------- + +The heart of your code is done by subclassing +:py:class:`oauthlib.oauth2.rfc6749.grant_types.base.GrantTypeBase`. +If you want to use it in the Authorize endpoint, you will have to +implement `create_authorization_response`, if in the Token endpoint, +implement `create_token_response`. + + +2. Associate it with Endpoints +------------------------------ +Then, once declared, you have to create an instance of your grant and +add it to your +endpoint. I.e. :py:class:`oauthlib.oauth2.rfc6749.endpoints.AuthorizationEndpoint` +or :py:class:`oauthlib.oauth2.rfc6749.endpoints.TokenEndpoint`. You +can see concrete examples in +:py:class:`oauthlib.oauth2.rfc6749.endpoints.pre_configured.Server` +for examples. + +3. Example +---------- + +To be completed. + +.. code-block:: python + class XXXZZZGrant(GrantTypeBase): + def create_token_response(self, request, token_handler): + if not request.grant_type == 'xxx_zzz': + raise errors.UnsupportedGrantTypeError(request=request) + ... + diff --git a/docs/oauth2/grants/custom_validators.rst b/docs/oauth2/grants/custom_validators.rst index 4629e6f..9917dd7 100644 --- a/docs/oauth2/grants/custom_validators.rst +++ b/docs/oauth2/grants/custom_validators.rst @@ -1,5 +1,15 @@ Custom Validators ----------------- -.. autoclass:: oauthlib.oauth2.rfc6749.grant_types.base.ValidatorsContainer +The Custom validators are useful when you want to change a particular +behavior of an existing grant. That is often needed because of the +diversity of the identity softwares and to let the oauthlib framework to be +flexible as possible. + +However, if you are looking into writing a custom grant type, please +refer to the :doc:`Custom Grant Type </oauth2/grants/custom_grant>` +instead. + +.. autoclass:: + oauthlib.oauth2.rfc6749.grant_types.base.ValidatorsContainer :members: diff --git a/docs/oauth2/grants/grants.rst b/docs/oauth2/grants/grants.rst index 16b17be..d2d9dcc 100644 --- a/docs/oauth2/grants/grants.rst +++ b/docs/oauth2/grants/grants.rst @@ -9,23 +9,30 @@ Grant types implicit password credentials - custom_validators + refresh jwt + custom_validators + custom_grant -Grant types are what make OAuth 2 so flexible. The Authorization Code grant is -very similar to OAuth 1 (with less crypto), the Implicit grant serves less -secure applications such as mobile applications, the Resource Owner Password -Credentials grant allows for legacy applications to incrementally transition to -OAuth 2, the Client Credentials grant is excellent for embedded services and -backend applications. +Grant types are what make OAuth 2 so flexible. The :doc:`Authorization +Code grant </oauth2/grants/authcode>` is the default for almost all +Web Applications, the :doc:`Implicit grant </oauth2/grants/implicit>` +serves less secure applications such as Mobile Applications or +Single-Page Applications, the :doc:`Client Credentials grant +</oauth2/grants/credentials>` is excellent for embedded services and +backend applications. We have also the :doc:`Resource Owner Password +Credentials grant </oauth2/grants/password>` for legacy applications +to incrementally transition to OAuth 2. The main purpose of the grant types is to authorize access to protected resources in various ways with different security credentials. Naturally, OAuth 2 allows for extension grant types to be defined and OAuthLib -attempts to cater for easy inclusion of this as much as possible. +attempts to cater for easy inclusion of this as much as possible. See +:doc:`Custom Grant Type </oauth2/grants/custom_grant>`. -OAuthlib also offers hooks for registering your own custom validations for use +OAuthlib also offers hooks for registering your own :doc:`Custom +Validators </oauth2/grants/custom_validators>` for use with the existing grant type handlers (:py:class:`oauthlib.oauth2.rfc6749.grant_types.base.ValidatorsContainer`). In some situations, this may be more convenient than subclassing or writing @@ -36,6 +43,7 @@ client to request new tokens for as long as you as provider allow them too. In general, OAuth 2 tokens should expire quickly and rather than annoying the user by require them to go through the authorization redirect loop you may use the refresh token to get a new access token. Refresh tokens, contrary to what their -name suggest, are components of a grant type rather than token types (like +name suggest, are components of a grant type (see :doc:`Refresh Token +grant </oauth2/grants/refresh>`) rather than token types (like Bearer tokens), much like the authorization code in the authorization code grant. diff --git a/docs/oauth2/grants/refresh.rst b/docs/oauth2/grants/refresh.rst new file mode 100644 index 0000000..df925ff --- /dev/null +++ b/docs/oauth2/grants/refresh.rst @@ -0,0 +1,6 @@ +Refresh Token Grant +------------------------ + +.. autoclass:: oauthlib.oauth2.RefreshTokenGrant + :members: + :inherited-members: @@ -11,7 +11,7 @@ commands= # tox -e docs to mimick readthedocs build. # as of today, RTD is using python2.7 and doesn't run "setup.py install" [testenv:docs] -basepython=python2.7 +basepython=python3.6 skipsdist=True deps= sphinx |