From 0cd5197f5a74cf05afa8a6111376be19c62fc05d Mon Sep 17 00:00:00 2001 From: Aurélien Bompard Date: Sep 04 2025 19:01:12 +0000 Subject: Add a couple schemas to the Developer/Authentication page Signed-off-by: Aurélien Bompard --- diff --git a/modules/developer_guide/assets/attachments/AAA-FASJSON-Flow.drawio b/modules/developer_guide/assets/attachments/AAA-FASJSON-Flow.drawio new file mode 100644 index 0000000..65562d4 --- /dev/null +++ b/modules/developer_guide/assets/attachments/AAA-FASJSON-Flow.drawio @@ -0,0 +1,65 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/developer_guide/assets/attachments/AAA-Flow.drawio b/modules/developer_guide/assets/attachments/AAA-Flow.drawio new file mode 100644 index 0000000..bd38c92 --- /dev/null +++ b/modules/developer_guide/assets/attachments/AAA-Flow.drawio @@ -0,0 +1,114 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/modules/developer_guide/assets/images/AAA-FASJSON-Flow.png b/modules/developer_guide/assets/images/AAA-FASJSON-Flow.png new file mode 100644 index 0000000..7b2ebe9 Binary files /dev/null and b/modules/developer_guide/assets/images/AAA-FASJSON-Flow.png differ diff --git a/modules/developer_guide/assets/images/AAA-Flow.svg b/modules/developer_guide/assets/images/AAA-Flow.svg new file mode 100644 index 0000000..a29b48d --- /dev/null +++ b/modules/developer_guide/assets/images/AAA-Flow.svg @@ -0,0 +1,4 @@ + + + +
Application
Application
Ipsilon
Ipsilon
IPA
IPA
login button
login button
redirect
(with return_url)
redirect...
login page
login page
username + password + token
username + pass...
check credentials (sssd)
check credentia...
PASS / FAIL
PASS / FAIL
redirect with result & token
redirect with result & token
go to return_url
go to return_url
query profile if needed
query profile i...
profile info
profile info
profile info
profile info
profile info
profile info
display page
(or redirect to prev page)
display page... \ No newline at end of file diff --git a/modules/developer_guide/pages/auth.adoc b/modules/developer_guide/pages/auth.adoc index ec72a56..2f82950 100644 --- a/modules/developer_guide/pages/auth.adoc +++ b/modules/developer_guide/pages/auth.adoc @@ -1,4 +1,5 @@ == Authentication +:figure-caption!: Fedora applications that require authentication should support https://accounts.fedoraproject.org/[Fedora Account System] backed @@ -15,13 +16,14 @@ 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. +We used to provide OpenID 2.0 support but it is now deprecated and will +be dropped. ==== -OpenID Connect is an authentication layer built on top of OAuth 2.0 +OpenID Connect is a discovery 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. +2.0 and its various flows, OpenID Connect is not different on the +authentication side. 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 @@ -42,6 +44,21 @@ undefined behavior. === Libraries +==== 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). + ==== OAuthLib https://oauthlib.readthedocs.io/[OAuthLib] is a low-level implementation @@ -78,22 +95,31 @@ 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 +==== Mozilla-Django-OIDC -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). +https://github.com/mozilla/mozilla-django-oidc[Mozilla-Django-OIDC] is a +Django extension for OpenID Connect. -==== 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). +=== Flow -==== Mozilla-Django-OIDC +This is a schema of a classic OpenID Connect authentication flow. -https://github.com/mozilla/mozilla-django-oidc[Mozilla-Django-OIDC] is a -Django extension for OpenID Connect. +.(xref:attachment$AAA-Flow.drawio[diagram source] in https://draw.io[draw.io] format) +image::AAA-Flow.svg[OIDC authentication flow] + + +=== FASJSON + +The account data is stored in FreeIPA, but it is made available to users and +applications through http://fasjson.fedoraproject.org[FASJSON] as a REST API +with JSON responses. + +Authentication to FASJSON is done using Kerberos keytabs for applications, +and a Kerberos ticket for users. + +Here is the flow of a request to FASJSON, explaining how it proxies the queries +to IPA. + +.(xref:attachment$AAA-FASJSON-Flow.drawio[diagram source] in https://draw.io[draw.io] format) +image::AAA-FASJSON-Flow.png[FASJSON flow]