[WIP] OIDC implementation proposal

[tevariou]

OIDC

Requirements

• The authorization server may not share the same domain
• All Arkhn applications share the same domain.
• A user session should be shared between the Arkhn applications (Pyrog, Hapi Fhir, ...)
• Each application is responsible for the user permissions in its scope

Specification

   +-------------+  +--------------+ +---------------+
   |             |  |              | |               |
   |Authorization|  |    Token     | |   Resource    |
   |  Endpoint   |  |   Endpoint   | |    Server     |
   |             |  |              | |               |
   +-------------+  +--------------+ +---------------+

          ^                ^                   ^
          |             (D)|                (G)|
          |                v                   v
          |
          |         +--------------------------------+
          |         |                                |
          |         |          Application           |
       (B)|         |            Server              |
          |         |                                |
          |         +--------------------------------+
          |
          |           ^     ^     +          ^    +
          |        (A)|  (C)|  (E)|       (F)|    |(H)
          v           v     +     v          +    v

   +-------------------------------------------------+
   |                                                 |
   |                   Browser                       |
   |                                                 |
   +-------------------------------------------------+

This flow enable the ability to keep all of the steps involved in obtaining
an access token outside of the Javascript application (the browser).

In this case, the Application Server initiates the OAuth flow itself,
by redirecting the browser to the authorization endpoint (B). When
the user is redirected back, the browser delivers the authorization
code to the application server (C), where it can then exchange it for
an access token at the token endpoint (D) using its client secret.
The application server then keeps the access token and refresh token
stored internally, and creates a separate session with the browser-
based app via a traditional browser cookie (E).

When the JavaScript application in the browser wants to make a
request to the Resource Server, it instead makes the request to the
Application Server (F), and the Application Server will make the
request with the access token to the Resource Server (H), and forward
the response (H) back to the browser.

The Application Server SHOULD be considered a confidential client,
and issued its own client secret. The Application Server SHOULD use
the OAuth 2.0 Authorization Code grant with PKCE to initiate a
request for an access token.
https://www.ory.sh/oauth2-for-mobile-app-spa-browser/
https://www.liip.ch/en/blog/authorization-code-with-pkce-on-django-using-django-oauth-toolkit

Security of the connection between code running in the browser and
this Application Server is assumed to utilize browser-level
protection mechanisms. Details are out of scope of this document,
but many recommendations can be found in the OWASP Cheat Sheet series
(https://cheatsheetseries.owasp.org/), such as setting an HTTP-only
and Secure cookie to authenticate the session between the browser and
Application Server.

In this scenario, the session between the browser and Application
Server SHOULD be a session cookie provided by the Application Server.

Django

In a Django backend, the Application Server would be the auth backend and a middleware through
which the requests are processed.

The Javascript application should have a link to a route of the backend api,
typically /oidc/authenticate/, which will redirect the user to the authorization endpoint.
The user is then a redirected back to the redirect_uri /oidc/callback which will redirect
the user back to the Javascript application.
The refresh token is stored in the database and a
separate Django session is created. In Django Rest Framework, we would use
a Session Authentication.
https://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication

The refresh token is used to check every now and then the user state by retrieving another access
token. If it fails, the session is destroyed. No need to store the access token.

A Session Authentication creates two cookies: a CSRF cookie and a session cookie.
The session cookie is a SameSite HTTP-Only cookie sent along every requests made by
the Javascript application to the Application Server. The CSRF cookie can be accessed by the
javascript code and its token should be added to every request headers.

Hapi FHIR

Keeping the same session across the stack

Scenario 1: API access through a browser

The API shares the same domain with the Django backend and has access to the session cookie.
The Django backend could communicate the session state and user infos to the API.
CSRF tokens should also be handled in some way...

Scenario 2: direct API access from another third party backend (no frontend)

Maybe an application password should be set for this...

References

https://tools.ietf.org/html/draft-ietf-oauth-browser-based-apps-07#page-6
https://oauth.net/articles/authentication/

[vmttn]

Architecture

1. hospitals may have OAuth2 or OpenID (most likely) provider in place, or nothing.
2. hospitals may have an authentication layer in place (e.g. LDAP)
3. we need end-users of our applications (e.g. pyrog, pypa) to authenticate against whatever is in place and safely
4. we need to restrict access to the resource providers managed by us (i.e. FHIR storage)
5. we want end-users to logged once and be able to use our different applications.

Note on permissions

• OAuth2 (by extension OpenID) is a delegation protocol. Not permission, not stricly authz. A user can delegate permissions he does not have.
• OAuth2 does not alleviate the need for a permission framework

OpenID/OAuth2

• OpenID is an extension of OAuth2
• While OAuth2 be abused for auth, OpenID provides true and secure auth
• Both provides the same set of flows:
  • authz code : the most secure
  • implicit : several threats for browser based application
  • client credentials : machine-to-machine
  • resource owner password credentials

Which flow for our application (pyrog, pypa, etc.) ?

The question is implicit flow or authz code flow ?

Implicit

• in the implicit flow, the access token is retrieve directly. A browser-based app could do for instance contact the resource provider directly.
• the implicit flow opens up the way for several security threats, some are impossible to mitigate.
• more on the implicit flow flaws:
  • attacks on the implicit flows https://tools.ietf.org/html/draft-ietf-oauth-browser-based-apps-07#section-9.8.1
  • disadvantages of the implicit flows https://tools.ietf.org/html/draft-ietf-oauth-browser-based-apps-07#section-9.8.3
  • following the implicit flow we can expect more CORS configuration

Authz code

• in the authz code flow, the access token is never exposed to the browser. The back takes care of the access token.
• this flow requires the back (e.g. pyrog back) to proxy all requests to a resource provider (e.g. FHIR storage)

Implementing the Authz code flow

Browser side (pyrog front, pypa front, etc.)

• nothing to do

Clients (Pyrog back, river, pypa back, etc.)

• must implement the client part of OpenID and OAuth2 protocols
• some opinionated client implementations are not compatible with both, but changing of implementations will stay simple.
• because of 1., we should focus on OpenID.
• implementations:
  • mozilla-django-oidc (python)
    • not compatible with OAuth2, but could be made compatible

Resource providers

• must :

  • check every incoming for an access token.
  • verify that token.
  • optionally can get user information :
    • from the UserInfo OpenID provider endpoint in the case of OpenID
    • from the token introspection OAuth2 provider endpoint in the case of OAuth2

• implementations may already exists depending on the language. If not, we can implement w/o overreaching.

• implementations:

  • django-oauth-toolkit (python)
    • OAuth2 and OpenID

OpenID/OAuth2 provider

• the OpenID/OAuth2 provider must authenticate the user.

• because of 2., it may have to rely on external authentication. In this case, we have to bridge so that the provider calls the preexisting auth.

• in the OpenID/OAuth spec, the O provider is responsible for both authz and auth. But the spec does not concern itself with the implementation. The auth can be done externally (this is for instance the case with hydra) or internally (in this case, the provider manages also user and credentials).

• hydra (+ additional auth service we have to implement)

  • OpenID and OAuth2 compatible
  • much opinionated and adds complexity
  • no authentication implemented. We have to implement it in yet another service : forces a split between the auth and the authz.
  • no user management system. ory/kratos is close but not intended to that.
  • enough for now

• django-oauth-toolkit

  • OpenID and OAuth2 compatible
  • fully-featured
  • user management available inhouse
  • default authentication provided

About the end-users logging in only once (point 5.)

• each application (pyrog back, pypa back, etc.) must have its own session management:
  • the application creates users internally (after the authz/auth flow has been validated)
  • the application sends session cookie to the client
• the OpenID/OAuth2 also has its own session management
  • once a user has logged in, the provider itself set another session cookie
• when an enduser has logged on 1 application, it has a session with the provider.
• hence if the enduser connects to another application, he/she will redirected to the provider but not be prompt for credentials again.

Which flow for direct access and CLI applications ?

• client credentials flow
• resource owner password credentials

References

• OpenID spec
• OpenID Connect guidelines by Mozilla
• OpenID vs pseudo-auth with OAuth2
• RFC6749: The OAuth 2.0 Authorization Framework
• RFC7662: OAuth 2.0 Token Introspection
• RFC8252: OAuth 2.0 for Native Apps
• RFC7636: Proof Key for Code Exchange by OAuth Public Clients
• draft: OAuth 2.0 for Browser-Based Apps