Skip to content

Reciprocal OAuth2 authorization explainer

Will Murphy edited this page May 26, 2021 · 5 revisions

In Immers Space, each immer serves as both an OAuth2 authorization server and an OAuth2 client. When users log into the same immer their account is registered on, their "home immer," that local immer serves as a both the client and the authorization server. When a user visits a different immer, that destination immer will act as a client to the user's home immer authorization server in order to connect with their account, fetch their avatar, and post updates.

It can get pretty mind bending, so here's an explainer of the flow, which currently uses the implicit grant pattern.

At home

  1. User arrives in a room
  2. Login popup points to immer authorization endpoint (/auth/authorize) to request access token with redirect_uri set to return to room and the immer's client_id
  3. Request redirected to immer login (/auth/login)
  4. User enters their Immers Space handle
  5. Recognized as local account, prompt for password
  6. Return to authorization endpoint (/auth/authorize)
  7. Authorization granted automatically because client and server are the same
  8. Redirect to redirect_uri to return to room with access token

Abroad

  1. User arrives in a room in destination immer
  2. Login popup points to destination immer authorization endpoint (destination.com/auth/authorize) to request access token, with redirect_uri set to return to room and the destination immer's client_id
  3. Redirected to destination immer login (destination.com/auth/login)
  4. User enters their Immers Space handle
  5. Recognized as remote account, redirect to home immer authorization endpoint (home.com/auth/authorize) with original redirect_uri and the destination immer's client_id
  6. Redirect interrupted with redirect to home immer login (home.com/auth/login)
  7. Recognized as local account, prompt for password
  8. Resume redirect to home immer authorization endpoint (home.com/auth/authorize)
  9. Authorization grant dialog for destination immer to access account
  10. Redirect to redirect_uri to return to destination immer with access token for home immer
Clone this wiki locally