sgo.to

The OpenID Connect Protocol

Sam Goto

This is a write down of the OpenID Connect protocol as if the messages were exchanged over instant messaging.

The OpenID Connect Protocol is built on top of OAuth 2.0 to add authentication and profile information. Instead (or in addition to) of giving an access token back, it provides back an IdToken (the equivalent of a badge with the user's information).

User Yo @example.com!
example.com joined
example.com Hey, whats up?
User Not much. Can I log in?
example.com Sure. You can use federation to login. Does that work?
User Yep, let me get you an IdToken, brb.
example.com Neat. My client id is 123123122.

The user then switches to a different group chat / tab to chat with their IDP:

User Yo @IDP!
IDP joined
IDP Hey, whats up?
User Not much. Can you generate an id token for 123123122 with my basic profile info?
IDP Sure.
IDP I attest that @User has account here. His name is Sam Goto and his email address is foobar@gmail.com. If you get this message after 2020, ignore it.
User Neat, thanks!

Here is an example of what an IdToken looks like in real life:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlNhbSBHb3RvIiwiaWF0IjoxNTE2MjM5MDIyLCJhdWQiOiJodHRwczovL2V4YW1wbGUuY29tIn0.6rer-dY2up87sVkI4lsl4ydaCLG1CVgsgl-uwWWqCw4

If you Base64 decode this, you get a header:

{
  "alg": "HS256",
  "typ": "JWT"
}

A body:

{
  "sub": "1234567890",
  "name": "Sam Goto",
  "iat": 1516239022,
  "aud": "https://example.com"
}

And a signature.

With the IdToken, the user sends that back to the relying party:

User Here it goes:
IDP I attest that @User has account here. His name is Sam Goto and his email address is foobar@gmail.com. If you get this message after 2020, ignore it.
example.com Ah, neat, thanks Sam!
example.com How can I help you?

This is a large oversimplification, but should give you a sense of the kinda of privacy property it has.

Specifically, the IDP is involved at every step of the way, from sign-up to sign-in. It is aware of:

  • which relying party the user is signing-in to
  • at which moment the user is signing in

Notably, the browser / user agent is mostly unaware of what's going on here: it is never invoked.