PR#40 Add documentation on authentication for Fedora apps

Proposed 10 days ago by jcline
Modified 2 days ago
From forks/jcline/infra-docs auth  into infra-docs master

Signed-off-by: Jeremy Cline jeremy@jcline.org

file added

 1 @@ -0,0 +1,91 @@ 

 2 + ==============

 3 + Authentication

 4 + ==============

 5 + 

 6 + Fedora applications that require authentication should support, at a minimum,

 7 + authentication against `Ipsilon`_. Ipsilon is an Identity Provider that uses

 8 + a separate Identity Management system to perform authentication. In Fedora,

 9 + Ipsilon is currently backed by the `Fedora Account System`_. In the future, it

10 + will be backed by `FreeIPA`_.

11 + 

12 + Ipsilon supports `OpenID 2.0`_, `OpenID Connect`_, `OAuth 2.0`_, and more.

13 + 

14 + 

15 + Authentication

16 + ==============

17 + 

18 + All new applications should use OpenID Connect for user authentication.

19 + 

20 + .. note::

21 +     Many existing applications use OpenID 2.0 and should eventually

22 +     migrate to OpenID Connect.

23 + 

24 + OpenID Connect is an authentication layer built on top of OAuth 2.0 so

25 + to understand OpenID Connect you should first be familiar with OAuth 2.0 and

26 + its various flows prior to learning about OpenID Connect.

27 + 

28 + When requesting an access token in OAuth 2.0, clients are allowed to specify

29 + the `scope`_ of the access token. This scope indicates what the token is allowed

30 + to be used for. In most cases, your application should require a scope or scopes

31 + of its own so users can issue access tokens that can only be used with a

32 + particular application. To do so, consult the `Authentication Wiki page`_.

33 + 

34 + 

35 + .. warning:: OpenID Connect `requires that the "openid" scope is requested

36 +     <https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>`_.

37 +     Failing to do so will result in undefined behavior.

The behavior is not "undefined" in our case: you just won't have access to UserInfo or an id_token.

Yup, but as far as the spec goes it's undefined. I really just wanted to highlight that (as a developer) you need to do this or weird things will happen and they'll differ from provider to provider.

Do you think there's a better way to get that point across?

38 + 

39 + 

40 + Libraries

41 + =========

42 + 

43 + OAuthLib

OAuthLib is not an OpenID Connect/OAuth2 client implementation, but rather the framework for a server implementation....

44 + --------

45 + 

46 + `OAuthLib`_ is a low-level implementation of OAuth 2.0 with OpenID Connect

47 + support. It does not tie itself to a HTTP request framework. Typically, you

48 + will only use this library indirectly.

49 + 

50 + 

51 + Requests-OAuthlib

52 + -----------------

53 + 

54 + `Requests-OAuthlib`_ uses the `Requests`_ library with OAuthLib to provide an

55 + easy-to-use interface for OAuth 2.0 clients. If you need to add support to an

56 + application that doesn't have an extension for OAuthLib, you should use this

57 + library.

58 + 

59 + 

60 + Flask-OAuthlib

61 + --------------

62 + 

63 + `Flask-OAuthlib`_ is a Flask extension that builds on top of Requests-OAuthlib.

64 + It comes with plenty of examples in the `examples`_ directory of the repository.

65 + Flask applications within Fedora Infrastructure should use this extension unless

66 + there is a good reason not to (and that reason is documented here).

67 + 

68 + 

69 + Pyramid-OAuthLib

70 + ----------------

71 + 

72 + `Pyramid-OAuthLib`_ is a Pyramid extension that uses OAuthlib. It does not appear

73 + to be actively maintained, but it is a reasonable starting point for our few

I do not like the idea of starting with a non-actively maintained auth system... The OpenID Connect specs are still in heavy movement.

I expect those Pyramid applications will need to make adjustments and push their changes upstream or (worst case) fork the project. It's just the glue between Pyramid and OAuthlib (which is actively maintained) so I don't see it as a huge problem. However, I can remove the whole section if you'd prefer us to not recommend a currently unmaintained project.

74 + Pyramid applications.

75 + 

76 + 

77 + .. _Authentication Wiki page:

78 +     https://fedoraproject.org/wiki/Infrastructure/Authentication

79 + .. _examples: https://github.com/lepture/flask-oauthlib/tree/master/example

80 + .. _Fedora Account System: https://admin.fedoraproject.org/accounts/

81 + .. _Flask-OAuthlib: https://flask-oauthlib.readthedocs.io/en/latest/

82 + .. _FreeIPA: http://www.freeipa.org/

83 + .. _Ipsilon: https://ipsilon-project.org/

84 + .. _OAuth 2.0: https://tools.ietf.org/html/rfc6749

85 + .. _OAuthLib: https://oauthlib.readthedocs.io/

86 + .. _OpenID 2.0: https://openid.net/specs/openid-authentication-2_0.html

87 + .. _OpenID Connect: https://openid.net/connect/

88 + .. _oauth2client: https://oauth2client.readthedocs.io/

89 + .. _Pyramid-OAuthLib: https://github.com/tilgovi/pyramid-oauthlib

90 + .. _Requests-OAuthlib: https://requests-oauthlib.readthedocs.io/

91 + .. _Requests: http://docs.python-requests.org/

92 + .. _scope: https://tools.ietf.org/html/rfc6749#section-3.3
file changed

1 @@ -22,5 +22,6 @@ 

2      dev-environment

3      documentation

4      writing-tests

5 +    auth

6      sops

7      source_control
puiterwijk commented on line 37 of docs/dev-guide/auth.rst.
10 days ago
(Show)
The behavior is not "undefined" in our case: you just won't have access to UserInfo or an id_token.
jcline commented on line 37 of docs/dev-guide/auth.rst.
8 days ago
(Show)
Yup, but as far as the spec goes it's undefined. I really just wanted to highlight that (as a developer) you need to do this or weird things will happen and they'll differ from provider to provider. Do you think there's a better way to get that point across?
puiterwijk commented on line 73 of docs/dev-guide/auth.rst.
8 days ago
(Show)
I do not like the idea of starting with a non-actively maintained auth system... The OpenID Connect specs are still in heavy movement.
puiterwijk commented on line 43 of docs/dev-guide/auth.rst.
8 days ago
(Show)
OAuthLib is not an OpenID Connect/OAuth2 client implementation, but rather the framework for a server implementation....
jcline commented on line 73 of docs/dev-guide/auth.rst.
8 days ago
(Show)
I expect those Pyramid applications will need to make adjustments and push their changes upstream or (worst case) fork the project. It's just the glue between Pyramid and OAuthlib (which is actively maintained) so I don't see it as a huge problem. However, I can remove the whole section if you'd prefer us to not recommend a currently unmaintained project.
Changes summary
+91
file added
+1 -0
file changed