From 3a4459bdd83744a3cd3a698997a6a4b483b0c6e0 Mon Sep 17 00:00:00 2001 From: Jonathan Huot Date: Fri, 18 Oct 2019 17:17:43 +0200 Subject: 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. --- docs/oauth2/grants/custom_grant.rst | 49 +++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/oauth2/grants/custom_grant.rst (limited to 'docs/oauth2/grants/custom_grant.rst') 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 `. + +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) + ... + -- cgit v1.2.1 From f68ec220d9ff5ec8e710d3e916318dad0de3e2d2 Mon Sep 17 00:00:00 2001 From: Jonathan Huot Date: Fri, 25 Oct 2019 11:28:51 +0200 Subject: Add custom grant example --- docs/oauth2/grants/custom_grant.rst | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) (limited to 'docs/oauth2/grants/custom_grant.rst') diff --git a/docs/oauth2/grants/custom_grant.rst b/docs/oauth2/grants/custom_grant.rst index ba5446c..7408cf6 100644 --- a/docs/oauth2/grants/custom_grant.rst +++ b/docs/oauth2/grants/custom_grant.rst @@ -1,5 +1,6 @@ +================= 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 @@ -38,12 +39,25 @@ for examples. 3. Example ---------- -To be completed. +Sample below shows the creation of a new custom `grant_type` parameter +and declare it in the `/token` endpoint of your `Server`. Note that +you can reuse `pre_configured.Server` or use your own class inheriting +of the `Endpoint` classes you have decided. .. code-block:: python - class XXXZZZGrant(GrantTypeBase): + + class MyCustomGrant(GrantTypeBase): def create_token_response(self, request, token_handler): - if not request.grant_type == 'xxx_zzz': + if not request.grant_type == 'urn:ietf:params:oauth:grant-type:my-custom-grant': raise errors.UnsupportedGrantTypeError(request=request) - ... - + # implement your custom validation checks + # .. + + token = token_handler.create_token(request, + refresh_token=self.issue_new_refresh_tokens) + return self._get_default_headers(), json.dumps(token), 200 + + def setup_oauthlib(): + my_custom_grant = MyCustomGrant() + server = Server(request_validator) + server.grant_types["urn:ietf:params:oauth:grant-type:my-custom-grant"] = my_custom_grant -- cgit v1.2.1 From 1645cd3f0f3142384b76b402859474a6d0cd68e7 Mon Sep 17 00:00:00 2001 From: Jonathan Huot Date: Mon, 28 Oct 2019 18:09:27 +0100 Subject: Improve clarity around howto define a grant. --- docs/oauth2/grants/custom_grant.rst | 67 +++++++++++++++++++++++-------------- 1 file changed, 41 insertions(+), 26 deletions(-) (limited to 'docs/oauth2/grants/custom_grant.rst') diff --git a/docs/oauth2/grants/custom_grant.rst b/docs/oauth2/grants/custom_grant.rst index 7408cf6..b47131c 100644 --- a/docs/oauth2/grants/custom_grant.rst +++ b/docs/oauth2/grants/custom_grant.rst @@ -7,10 +7,9 @@ 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 `. +! See :doc:`how to contribute here `. -Please find below an example of how to create a new grant and use it -in an endpoint: +Please find how to create a new grant and use it in an endpoint: .. contents:: Tutorial Contents :depth: 3 @@ -18,46 +17,62 @@ in an endpoint: 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`. +:py:class:`GrantTypeBase`. If you want to use it in the Authorize +endpoint, you will have to implement +:py:meth:`create_authorization_response`, if you want to use the Token +endpoint, implement :py:meth:`create_token_response`. You can also +implement both. + +2. Implement the grant +---------------------- +Inside the method's implementation, you will have to: +* add validations of the request (syntax, parameters, ...) +* call and orchestrate one or multiple Request Validators calls +* generate and return HTTP response -2. Associate it with Endpoints +You can define new Request Validator methods if needed, or reuse the +existing ones. + +3. 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 +Then, once implemented, you have to instanciate the grant object and +bind it to your endpoint. Either :py:class:`AuthorizationEndpoint`, +:py:class:`TokenEndpoint` or both. + +4. Example ---------- +This example shows how to add a simple extension to the `Token endpoint`: -Sample below shows the creation of a new custom `grant_type` parameter -and declare it in the `/token` endpoint of your `Server`. Note that -you can reuse `pre_configured.Server` or use your own class inheriting -of the `Endpoint` classes you have decided. +* creation of a new class ``MyCustomGrant``, and implement ``create_token_response``. +* do basics and custom request validations, then call a custom method + of `Request Validator` to extend the interface for the implementor. +* instanciate the new grant, and bind it with an existing ``Server``. .. code-block:: python + grant_name = 'urn:ietf:params:oauth:grant-type:my-custom-grant' + class MyCustomGrant(GrantTypeBase): def create_token_response(self, request, token_handler): - if not request.grant_type == 'urn:ietf:params:oauth:grant-type:my-custom-grant': + if not request.grant_type == grant_name: raise errors.UnsupportedGrantTypeError(request=request) + # implement your custom validation checks # .. + self.request_validator.your_custom_check(request) - token = token_handler.create_token(request, - refresh_token=self.issue_new_refresh_tokens) + token = token_handler.create_token(request) return self._get_default_headers(), json.dumps(token), 200 def setup_oauthlib(): my_custom_grant = MyCustomGrant() server = Server(request_validator) - server.grant_types["urn:ietf:params:oauth:grant-type:my-custom-grant"] = my_custom_grant + server.grant_types[grant_name] = my_custom_grant + + +You can find concrete examples directly in the code source of existing +grants and existing servers. See Grant Types in +:py:mod:`oauthlib.oauth2.rfc749.grant_types`, and Servers in +:py:mod:`oauthlib.oauth2.rfc749.endpoints.pre_configured` -- cgit v1.2.1 From 6e4fb41ffb04024d5301cadad662e6bbb4893901 Mon Sep 17 00:00:00 2001 From: Jonathan Huot Date: Wed, 15 Jan 2020 10:48:03 +0100 Subject: Removed newline/autoformatting mistake fixed --- docs/oauth2/grants/custom_grant.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/oauth2/grants/custom_grant.rst') diff --git a/docs/oauth2/grants/custom_grant.rst b/docs/oauth2/grants/custom_grant.rst index b47131c..8c4571c 100644 --- a/docs/oauth2/grants/custom_grant.rst +++ b/docs/oauth2/grants/custom_grant.rst @@ -6,8 +6,8 @@ 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 `. +specification can be integrated in oauthlib, just make a PR for that ! +See :doc:`how to contribute here `. Please find how to create a new grant and use it in an endpoint: -- cgit v1.2.1