port over the development guide from pagure fedora-docs

Signed-off-by: Ryan Lerch <rlerch@redhat.com>

modules/developer_guide/pages/auth.adoc

@@ -0,0 +1,90 @@
+== Authentication
+
+Fedora applications that require authentication should support, at a
+minimum, authentication against https://ipsilon-project.org/[Ipsilon].
+Ipsilon is an Identity Provider that uses a separate Identity Management
+system to perform authentication. In Fedora, Ipsilon is currently backed
+by the https://admin.fedoraproject.org/accounts/[Fedora Account System].
+In the future, it will be backed by http://www.freeipa.org/[FreeIPA].
+
+Ipsilon supports
+https://openid.net/specs/openid-authentication-2_0.html[OpenID 2.0],
+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]
+.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]
+.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. In the case of Ipsilon, you won't have access to the
+UserInfo or recieve an ID token.
+======= 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.
+
+==== Flask-OIDC
+
+link:#flask-oidc[Flask-OIDC] is a Flask extension.
+
+==== Mozilla-Django-OIDC
+
+https://github.com/mozilla/mozilla-django-oidc[Mozilla-Django-OIDC] is a
+Django extension for OpenID Connect.