== 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.
