infra-docs-fpo/modules/developer_guide/pages/auth.adoc
Aurélien Bompard 66fcba764c
Update the developer doc
Mention the cookiecutter template.

Signed-off-by: Aurélien Bompard <aurelien@bompard.org>
2023-10-26 16:56:23 +02:00

99 lines
3.8 KiB
Text

== Authentication
Fedora applications that require authentication should support
https://accounts.fedoraproject.org/[Fedora Account System] backed
by http://www.freeipa.org/[FreeIPA] as an identity provider.
https://accounts.fedoraproject.org/[Fedora Account System] supports
https://github.com/fedora-infra/fasjson/[fasjson] as read-only API,
https://openid.net/connect/[OpenID Connect],
https://tools.ietf.org/html/rfc6749[OAuth 2.0], and more.
=== Authentication
All new applications should use OpenID Connect for user authentication.
[NOTE]
====
Many existing applications use OpenID 2.0 and should eventually migrate
to OpenID Connect.
====
OpenID Connect is an authentication layer built on top of OAuth 2.0
so to understand OpenID Connect you should first be familiar with OAuth
2.0 and its various flows prior to learning about OpenID Connect.
When requesting an access token in OAuth 2.0, clients are allowed to
specify the https://tools.ietf.org/html/rfc6749#section-3.3[scope] of
the access token. This scope indicates what the token is allowed to be
used for. In most cases, your application should require a scope or
scopes of its own so users can issue access tokens that can only be used
with a particular application. To do so, consult the
https://fedoraproject.org/wiki/Infrastructure/Authentication[Authentication
Wiki page].
[WARNING]
====
OpenID Connect
https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest[requires
that the "openid" scope is requested]. Failing to do so will result in
undefined behavior.
====
=== Libraries
==== OAuthLib
https://oauthlib.readthedocs.io/[OAuthLib] is a low-level implementation
of OAuth 2.0 with OpenID Connect support. It does not tie itself to a
HTTP request framework. Typically, you will only use this library
indirectly. If you are investigating this library, note that it is a
library for both OAuth clients and OAuth providers. You will be most
interested in the
https://oauthlib.readthedocs.io/en/latest/oauth2/clients/client.html[OAuth
client] sub-package.
==== Requests-OAuthlib
https://requests-oauthlib.readthedocs.io/[Requests-OAuthlib] uses the
http://docs.python-requests.org/[Requests] library with OAuthLib to
provide an easy-to-use interface for OAuth 2.0 clients. If you need to
add support to an application that doesn't have an extension for
OAuthLib, you should use this library.
==== Flask-OAuthlib
https://flask-oauthlib.readthedocs.io/en/latest/[Flask-OAuthlib] is a
Flask extension that builds on top of Requests-OAuthlib. It comes with
plenty of examples in the
https://github.com/lepture/flask-oauthlib/tree/master/example[examples]
directory of the repository. Flask applications within Fedora
Infrastructure should use this extension unless there is a good reason
not to (and that reason is documented here).
==== Pyramid-OAuthLib
https://github.com/tilgovi/pyramid-oauthlib[Pyramid-OAuthLib] is a
Pyramid extension that uses OAuthlib. It does not appear to be actively
maintained, but it is a reasonable starting point for our few Pyramid
applications.
==== Authlib
https://authlib.org/[Authlib] is a Python library to build OAuth and
OpenID Connect servers and clients. It has integration layers for Flask
and Django as protocol servers and clients, as well as client integration
layers for Requests, HTTPX, Starlette and FastAPI. As a client app
authenticating with OpenID Connect, it is most useful if several
authentication providers are to be supported (such as social networks).
==== Flask-OIDC
https://github.com/fedora-infra/flask-oidc/[Flask-OIDC] is a Flask
extension that makes using Authlib easier when using Flask with only one
authentication provider (such as Fedora's identity provider).
==== Mozilla-Django-OIDC
https://github.com/mozilla/mozilla-django-oidc[Mozilla-Django-OIDC] is a
Django extension for OpenID Connect.