okta-login-flow.md

This page describes the flow of requests, tokens etc. when using the Okta sign-in widget with a backend (such as Spring Boot) that's configured for OAuth2 based authentication.

Okta Login flow

If I have a web-app running on myapp.mycompany.com and an Okta organization running on dev-993392.oktapreview.com then there are 3 actors involved in the login flow:

• The server that serves up the myapp.mycompany.com pages.
• Browser pages with origin myapp.mycompany.com.
• Browser pages with origin dev-993392.oktapreview.com

At the start of the login flow the browser knows nothing, the server however knows a few things - it knows about dev-993392.oktapreview.com and some things relating to it:

• The client ID.
• The client secret, aka the API token.
• The URI of the corresponding authorization server.

There's no need to know what these mean at the moment - they're only used in step 7 below where the server retrieves an access_token.

The Javascript behind the login.html page knows the Okta server involved, i.e. dev-993392.oktapreview.com, but has no other information baked in.

1. At the start of the login flow the browser loads myapp.mycompany.com/login.html.
2. The user enters their username and password and presses submit, causing the page to:
   • Send an AJAX OPTIONS request to dev-993392.oktapreview.com/authn.
   • Send an AJAX POST request to dev-993392.oktapreview.com/authn with the username and password. The headers in the response blank any existing session ID (sid) cookie and give pages with origin dev-993392.oktapreview.com the right to request authorization codes.
3. To finish up the submit process, the Javascript behind login.html triggers the browser to load dev-993392.oktapreview.com/sessionCookieRedirect
   The response is a 302 redirect and the headers contain a cookie that provides a new sid.
4. The redirect causes the browser to load the myapp.mycompany.com/login endpoint.
   The response is a 302.
5. The redirect causes the browser to load dev-993392.oktapreview.com/authorize.
   The cookies acquired from the authn POST above gives this request the right to retrieve an authorization code (valid for 60 seconds).
   The response is a 302 (and the retrieved authorization code is included as a parameter in the redirect location).
6. The redirect causes the browser to load the myapp.mycompany.com/login again but this time with the authorization code as a parameter.
7. Now the server, rather than the browser, makes a request, i.e. the logic behind the login endpoint uses the passed in authorization code.
   It does a POST request to dev-993392.oktapreview.com/token passing in the authorization code and getting an access_token in return.

At this point all actors have all the information they will ever have:

• Browser pages with origin myapp.mycompany.com essentially still know nothing.
• Browser pages with origin dev-993392.oktapreview.com know the sid and have the cookies necessary to retrieve authorization codes.
• The myapp.mycompany.com server has an access_token that e.g. allows it to retrieve user info (the login endpoint actually does this straight after getting the access_token).

Update: acutally it's not true that pages with origin myapp.mycompany.com know nothing. CORS is in play such that these pages can interact with dev-993392.oktapreview.com.

Note: I've shortened all the URLs above, i.e. just given the hostname and the important bit, e.g. token, of the path.