1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
# 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
...
|
