diff options
Diffstat (limited to 'yuck.md')
| -rw-r--r-- | yuck.md | 295 |
1 files changed, 281 insertions, 14 deletions
@@ -1,38 +1,305 @@ -# OIDC protocol +# Overview + +## Concepts + +Some basic concepts in this document: + +* identity: data about who you are to tell you apart from everyone + else +* authentication: proving your identity +* authorization: giving permission to do something + +## The protocols: OAuth 2.0 and OpenID Connect + +The OAuth 2.0 protocol is for authorization, not authentication, and +assumes an already existing way to authenticate users. It's mainly for +giving a service or application permission to do something on your +behalf. -The OIDC protocol involves the following entities: +The OpenID Connect (OIDC) protocol is for authenticating yourself to +one service or application by using a third party service. This allows +one authentication service (or identity provider) be used for any +number of other services or applications. Further, since the identity +provider can keep a login session open independently of the other +services and applications, this provides a single sign-on experience. -* the **end user**, who is trying to do something -* the **web browser**, used by the user -* the **web application**, which the user uses to do things, and as - part of that access resources + +## Entities involved in the protocols + +The protocols involves the following entities: + +* the **end user**, who is trying to do something; also the resource + owner +* the **web browser**, used by the user; might be a mobile or command + line application instead of a browser per se +* the **application**, which the user uses to do things, and as part + of that access resources * the **resource provider**, where the resources are, and which allows access to them via a web API -* the **identity provider**, which authenticates the user +* the **identity provider** (IDP), which authenticates the user + +# OIDC protocol + +This augments the plain OIDC with cookies: + +* an **app cookie** set by the application to tie a user and their + session together: this lets the application store data about the + user and what they're doing between HTTP requests +* a **login cookie** set by the IDP to remember this user has a valid + login session + + +## Successful resource access by a logged-out user ~~~plantuml @startuml + +actor "End user" as user +participant browser as "User agent \n (web browser)" +participant app as "Application \n (web, mobile)" +participant idp as "Identity provider" +database rp as "Resource provider" + user -> browser : clicks on something +note left + User initiates an action + that requires a protected + resource from the + resource provider. +endnote + browser -> app : GET /something -browser <- app : redirect to /login -browser -> app : GET /login -browser <- app: redirect to idp -browser -> idp : GET /login -browser <- idp : login form +note left + Browser asks the + application for what + the user asked for. +end note + +browser <- app : redirect to IDP /login?... +note right + Application does not have + a session open for user. + It redirects browser to + IDP for login and sets + an **app cookie**. It + remember what resource + the user was asking for. +end note + +browser -> idp : GET /login?... +note left + Browser follows redirect. + The URL contains the application's + client id, callback URL, and other + information the IDP will need later. +end note + +browser <- idp: login page +note right + IDP has no login session for + user (no **login cookie**). + It creates an internal + authentication process + record. +end note + user <- browser : show login form + user -> browser : enter login info + browser -> idp : POST login form -browser <- idp : redirect to app /callback with authz code -browser -> app : GET /callback with authz code +note left + URL includes identifier + for authentication record. +end note + +browser <- idp : redirect to app /callback?code=... +note right + IDP checks credentials, + generates **authorization code**, + stores it in the authentication + process record and in the + redirect URL. + + IDP sets **login cookie**. +end note + +browser -> app : GET /callback?code=... +note left + Browser follows redirect, + includes **app cookie**. +end note + app -> idp : request tokens using authz code +note left + Application gets access, + id, and refresh tokens from + IDP, using the **authorization code** + it just got. + + Application uses Basic Auth + to prove which application it is. +end note + app <- idp : access, id, and refresh tokens +note right + IDP checks applicaion + credential and generates + the tokens. + + IDP forgets the code + (it's single-use only). +end note +note left + Application stores the + cookies so they can + be found via the + **app cookie**. +end note + app -> rp : access resource with access token +note left + Application gets the resource + the user originally asked for. + It remembers what it was thank + so the **app cookie**. +end note + app <- rp : resource + browser <- app : page with resource + user <- browser : show what the user wanted + @enduml ~~~ +## Successful resource access by a logged-in user + +~~~plantuml +@startuml + +actor "End user" as user +participant browser as "User agent \n (web browser)" +participant app as "Application \n (web, mobile)" +participant idp as "Identity provider" +database rp as "Resource provider" + +user -> browser : clicks on something +note left + User initiates an action + that requires a protected + resource from the + resource provider. +endnote + +browser -> app : GET /something +note left + Browser asks the + application for what + the user asked for. + + The **app cookie** is + included in the request. +end note + +app -> rp : access resource with access token +note left + Application gets the resource + using the **access token** it + has associated with the + **app cookie**. +end note + +app <- rp : resource + +browser <- app : page with resource + +user <- browser : show what the user wanted + +@enduml +~~~ + + +## Successful request when an access cookie has expired + +~~~plantuml +@startuml + +actor "End user" as user +participant browser as "User agent \n (web browser)" +participant app as "Application \n (web, mobile)" +participant idp as "Identity provider" +database rp as "Resource provider" + +user -> browser : clicks on something +note left + User initiates an action + that requires a protected + resource from the + resource provider. +endnote + +browser -> app : GET /something +note left + Browser asks the + application for what + the user asked for. + + The **app cookie** is + included in the request. +end note + +app -> rp : access resource with access token +note left + Application gets the resource + using the **access token** it + has associated with the + **app cookie**. +end note + +app <- rp : access denied +note right + The RP sees the **access token** + is expired and returns an + error. +end note + +app -> idp : request new access cookie +note left + Application uses the + **refresh token** to get + a **new access token**. +end note + +app <- idp : new access token +note left + Application stores + **new access token** in + user's session. +end note + +app -> rp : access resource with new access token +note left + Application gets the resource + using the **new access token**. +end note + +app <- rp : resource + +browser <- app : page with resource + +user <- browser : show what the user wanted + +@enduml +~~~ + + + + + + + --- title: Yuck or OIDC ... |