|
| 1 | +================= |
| 2 | +Custom Grant type |
| 3 | +================= |
| 4 | + |
| 5 | +Writing a custom grant type can be useful to implement a specification |
| 6 | +which is in an early draft, or implement a grant provided by a |
| 7 | +specific OAuth2.0 Authorization Server documentation but not provided |
| 8 | +by oauthlib. For information, any grant types with a clear |
| 9 | +specification can be integrated in oauthlib, just make a PR for that ! |
| 10 | +See :doc:`how to contribute here </contributing>`. |
| 11 | + |
| 12 | +Please find how to create a new grant and use it in an endpoint: |
| 13 | + |
| 14 | +.. contents:: Tutorial Contents |
| 15 | + :depth: 3 |
| 16 | + |
| 17 | + |
| 18 | +1. Define your Grant Type |
| 19 | +------------------------- |
| 20 | +The heart of your code is done by subclassing |
| 21 | +:py:class:`GrantTypeBase`. If you want to use it in the Authorize |
| 22 | +endpoint, you will have to implement |
| 23 | +:py:meth:`create_authorization_response`, if you want to use the Token |
| 24 | +endpoint, implement :py:meth:`create_token_response`. You can also |
| 25 | +implement both. |
| 26 | + |
| 27 | +2. Implement the grant |
| 28 | +---------------------- |
| 29 | +Inside the method's implementation, you will have to: |
| 30 | + |
| 31 | +* add validations of the request (syntax, parameters, ...) |
| 32 | +* call and orchestrate one or multiple Request Validators calls |
| 33 | +* generate and return HTTP response |
| 34 | + |
| 35 | +You can define new Request Validator methods if needed, or reuse the |
| 36 | +existing ones. |
| 37 | + |
| 38 | +3. Associate it with Endpoints |
| 39 | +------------------------------ |
| 40 | +Then, once implemented, you have to instanciate the grant object and |
| 41 | +bind it to your endpoint. Either :py:class:`AuthorizationEndpoint`, |
| 42 | +:py:class:`TokenEndpoint` or both. |
| 43 | + |
| 44 | +4. Example |
| 45 | +---------- |
| 46 | +This example shows how to add a simple extension to the `Token endpoint`: |
| 47 | + |
| 48 | +* creation of a new class ``MyCustomGrant``, and implement ``create_token_response``. |
| 49 | +* do basics and custom request validations, then call a custom method |
| 50 | + of `Request Validator` to extend the interface for the implementor. |
| 51 | +* instanciate the new grant, and bind it with an existing ``Server``. |
| 52 | + |
| 53 | +.. code-block:: python |
| 54 | +
|
| 55 | + grant_name = 'urn:ietf:params:oauth:grant-type:my-custom-grant' |
| 56 | +
|
| 57 | + class MyCustomGrant(GrantTypeBase): |
| 58 | + def create_token_response(self, request, token_handler): |
| 59 | + if not request.grant_type == grant_name: |
| 60 | + raise errors.UnsupportedGrantTypeError(request=request) |
| 61 | +
|
| 62 | + # implement your custom validation checks |
| 63 | + # .. |
| 64 | + self.request_validator.your_custom_check(request) |
| 65 | +
|
| 66 | + token = token_handler.create_token(request) |
| 67 | + return self._get_default_headers(), json.dumps(token), 200 |
| 68 | +
|
| 69 | + def setup_oauthlib(): |
| 70 | + my_custom_grant = MyCustomGrant() |
| 71 | + server = Server(request_validator) |
| 72 | + server.grant_types[grant_name] = my_custom_grant |
| 73 | +
|
| 74 | +
|
| 75 | +You can find concrete examples directly in the code source of existing |
| 76 | +grants and existing servers. See Grant Types in |
| 77 | +:py:mod:`oauthlib.oauth2.rfc749.grant_types`, and Servers in |
| 78 | +:py:mod:`oauthlib.oauth2.rfc749.endpoints.pre_configured` |
0 commit comments