From 96dbbef0ca750acb30dd3ebbb699007d807ec685 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 25 Apr 2020 10:17:40 +0300 Subject: Change: more use cases, fix errors --- yuck.html | 49 +++++++++-- yuck.md | 295 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 321 insertions(+), 23 deletions(-) diff --git a/yuck.html b/yuck.html index 1f5cce5..6074c8f 100644 --- a/yuck.html +++ b/yuck.html @@ -15,22 +15,53 @@

Yuck or OIDC

2020-04-25 08:01

2020-04-25 10:16

1 OIDC protocol

The OIDC protocol involves the following entities:

1 Overview

1.1 Concepts

Some basic concepts in this document:

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
identity: data about who you are to tell you apart from everyone else
authentication: proving your identity
authorization: giving permission to do something

1.2 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 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.

1.3 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

2 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

2.1 Successful resource access by a logged-out user

2.2 Successful resource access by a logged-in user

+ +

diff --git a/yuck.md b/yuck.md index 6e8578f..b4154fd 100644 --- a/yuck.md +++ b/yuck.md @@ -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 ... -- cgit v1.2.1