PR#40 Closed Add documentation on authentication for Fedora apps

Proposed 2 months ago by jcline
Modified 2 months 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,95 @@ 

 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. In the case of Ipsilon,

38 +     you won't have access to the UserInfo or recieve an ID token.

39 + 

40 + 

41 + Libraries

42 + =========

43 + 

44 + OAuthLib

45 + --------

46 + 

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

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

49 + will only use this library indirectly. If you are investigating this library,

50 + note that it is a library for both OAuth clients and OAuth providers. You

51 + will be most interested in the `OAuth client`_ sub-package.

52 + 

53 + 

54 + Requests-OAuthlib

55 + -----------------

56 + 

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

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

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

60 + library.

61 + 

62 + 

63 + Flask-OAuthlib

64 + --------------

65 + 

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

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

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

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

70 + 

71 + 

72 + Pyramid-OAuthLib

73 + ----------------

74 + 

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

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

77 + Pyramid applications.

78 + 

79 + 

80 + .. _Authentication Wiki page:

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

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

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

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

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

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

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

88 + .. _OAuth Client: https://oauthlib.readthedocs.io/en/latest/oauth2/clients/client.html

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

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

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

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

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

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

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

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

1 @@ -24,5 +24,6 @@ 

2      code-style

3      db

4      writing-tests

5 +    auth

6      sops

7      source_control
puiterwijk commented on line 37 of docs/dev-guide/auth.rst.
2 months ago
(Hide)
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.
2 months ago
(Hide)
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.
2 months ago
(Hide)
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.
2 months ago
(Hide)
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.
2 months ago
(Hide)
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.
jcline commented on line 43 of docs/dev-guide/auth.rst.
2 months ago
(Hide)
I know that a good portion of the library is for providers, but It has a [client](https://oauthlib.readthedocs.io/en/latest/oauth2/clients/client.html) so I'm not sure what you're talking about. Can you expand on your comment?
puiterwijk commented on line 73 of docs/dev-guide/auth.rst.
2 months ago
(Hide)
Hmm, okay. Looking at the amount of code that they have, this seems reasonable to me.
puiterwijk commented on line 43 of docs/dev-guide/auth.rst.
2 months ago
(Hide)
Aha. I had not seen that part of the code! Thanks for that specific link. Maybe it's an idea to add that in the doc?
puiterwijk commented on line 37 of docs/dev-guide/auth.rst.
2 months ago
(Hide)
Nah, this is fine. Just wanted to point out what happened in our case for completeness sake :).

The main concern I have here is that the current suggestions are mostly OAuth2-centric, and will likely lag behind some of the new OIDC specs.
Disregarding that, I think this is a reasonable start.
Maybe you can also update the Infrastructure/Authentication wiki page?

Thanks!

Thanks for the feedback!

I've updated the sections you've noted to be more clear/complete and pointed directly to the client section of the oauthlib library (although I don't think anyone will need to poke around in there except for academic reasons).

2 months ago

rebased

2 months ago

Pull-Request has been closed by jcline

I merged this via the CLI and forgot that's not reflected in the web UI.

Changes summary
+95
file added
+1 -0
file changed