# 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 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. ## 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** (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 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 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 ...