mirror of
https://github.com/LukeHagar/connexion.git
synced 2025-12-09 04:19:32 +00:00
6f600234fe
* Updated API Key example link to correct location * Fixed example href location per PR feedback
110 lines
5.2 KiB
ReStructuredText
110 lines
5.2 KiB
ReStructuredText
Security
|
|
========
|
|
|
|
OAuth 2 Authentication and Authorization
|
|
----------------------------------------
|
|
|
|
Connexion supports one of the three OAuth 2 handling methods.
|
|
With Connexion, the API security definition **must** include a
|
|
``x-tokenInfoFunc`` or set ``TOKENINFO_FUNC`` env var.
|
|
|
|
``x-tokenInfoFunc`` must contain a reference to a function
|
|
used to obtain the token info. This reference should be a string using
|
|
the same syntax that is used to connect an ``operationId`` to a Python
|
|
function when routing. For example, an ``x-tokenInfoFunc`` of
|
|
``auth.verifyToken`` would pass the user's token string to the function
|
|
``verifyToken`` in the module ``auth.py``. The referenced function accepts
|
|
a token string as argument and should return a dict containing a ``scope``
|
|
field that is either a space-separated list or an array of scopes belonging to
|
|
the supplied token. This list of scopes will be validated against the scopes
|
|
required by the API security definition to determine if the user is authorized.
|
|
You can supply a custom scope validation func with ``x-scopeValidateFunc``
|
|
or set ``SCOPEVALIDATE_FUNC`` env var, otherwise
|
|
``connexion.decorators.security.validate_scope`` will be used as default.
|
|
|
|
|
|
The recommended approach is to return a dict which complies with
|
|
`RFC 7662 <rfc7662_>`_. Note that you have to validate the ``active``
|
|
or ``exp`` fields etc. yourself.
|
|
|
|
The ``sub`` property of the Token Info response will be passed in the ``user``
|
|
argument to the handler function.
|
|
|
|
Deprecated features, retained for backward compability:
|
|
|
|
- As alternative to ``x-tokenInfoFunc``, you can set ``x-tokenInfoUrl`` or
|
|
``TOKENINFO_URL`` env var. It must contain a URL to validate and get the token
|
|
information which complies with `RFC 6749 <rfc6749_>`_.
|
|
When both ``x-tokenInfoUrl`` and ``x-tokenInfoFunc`` are used, Connexion
|
|
will prioritize the function method. Connexion expects the authorization
|
|
server to receive the OAuth token in the ``Authorization`` header field in the
|
|
format described in `RFC 6750 <rfc6750_>`_ section 2.1. This aspect represents
|
|
a significant difference from the usual OAuth flow.
|
|
- ``scope`` field can also be named ``scopes``.
|
|
- ``sub`` field can also be named ``uid``.
|
|
|
|
You can find a `minimal OAuth example application`_ in Connexion's "examples" folder.
|
|
|
|
|
|
Basic Authentication
|
|
--------------------
|
|
|
|
With Connexion, the API security definition **must** include a
|
|
``x-basicInfoFunc`` or set ``BASICINFO_FUNC`` env var. It uses the same
|
|
semantics as for ``x-tokenInfoFunc``, but the function accepts three
|
|
parameters: username, password and required_scopes. If the security declaration
|
|
of the operation also has an oauth security requirement, required_scopes is
|
|
taken from there, otherwise it's None. This allows authorizing individual
|
|
operations with oauth scope while using basic authentication for
|
|
authentication.
|
|
|
|
You can find a `minimal Basic Auth example application`_ in Connexion's "examples" folder.
|
|
|
|
ApiKey Authentication
|
|
---------------------
|
|
|
|
With Connexion, the API security definition **must** include a
|
|
``x-apikeyInfoFunc`` or set ``APIKEYINFO_FUNC`` env var. It uses the same
|
|
semantics as for ``x-basicInfoFunc``, but the function accepts two
|
|
parameters: apikey and required_scopes.
|
|
|
|
You can find a `minimal API Key example application`_ in Connexion's "examples" folder.
|
|
|
|
Bearer Authentication (JWT)
|
|
---------------------------
|
|
|
|
With Connexion, the API security definition **must** include a
|
|
``x-bearerInfoFunc`` or set ``BEARERINFO_FUNC`` env var. It uses the same
|
|
semantics as for ``x-tokenInfoFunc``, but the function accepts one parameter: token.
|
|
|
|
You can find a `minimal JWT example application`_ in Connexion's "examples/openapi3" folder.
|
|
|
|
Deploying Authentication
|
|
------------------------
|
|
|
|
Some production hosting environments, such as Apache with modwsgi, do not by default pass
|
|
authentication headers to WSGI applications. Therefore, to allow connexion to handle
|
|
authentication, you will need to enable passthrough.
|
|
|
|
Instructions for `enabling authentication passthrough in modwsgi`_ are available as
|
|
part of the `modwsgi documentation`_.
|
|
|
|
HTTPS Support
|
|
-------------
|
|
|
|
When specifying HTTPS as the scheme in the API YAML file, all the URIs
|
|
in the served Swagger UI are HTTPS endpoints. The problem: The default
|
|
server that runs is a "normal" HTTP server. This means that the
|
|
Swagger UI cannot be used to play with the API. What is the correct
|
|
way to start a HTTPS server when using Connexion?
|
|
|
|
.. _rfc6750: https://tools.ietf.org/html/rfc6750
|
|
.. _rfc6749: https://tools.ietf.org/html/rfc6749
|
|
.. _rfc7662: https://tools.ietf.org/html/rfc7662
|
|
.. _minimal OAuth example application: https://github.com/zalando/connexion/tree/master/examples/swagger2/oauth2
|
|
.. _minimal Basic Auth example application: https://github.com/zalando/connexion/tree/master/examples/swagger2/basicauth
|
|
.. _minimal API Key example application: https://github.com/zalando/connexion/blob/master/examples/openapi3/apikey
|
|
.. _minimal JWT example application: https://github.com/zalando/connexion/tree/master/examples/openapi3/jwt
|
|
.. _enabling authentication passthrough in modwsgi: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIPassAuthorization.html
|
|
.. _modwsgi documentation: https://modwsgi.readthedocs.io/en/develop/index.html
|