Logo / Articles

Login & Auth Workflows

Single-Page Application OAuth Login Using Authorization Code Grant With Sessions And Refresh Tokens

By Brian Pontarelli

This workflow is used by single-page applications using the FusionAuth OAuth login interface. The single-page application navigates away from its interface and over to FusionAuth’s OAuth interface. Once the user completes their login, FusionAuth redirects back to the single-page application. This requires that the single-page application re-initialize itself, but the browser should cache the application files and be able to restart it quickly. Below is a diagram that describes the primary components of this workflow and how they interact. Keep in mind that not every interaction is covered here, just the primary login interactions. At the bottom of the diagram is a discussion of the key steps.

For all of our examples, we use a store and a forum for the same company. The store requires a user to login to view their shopping cart and the forum requires the user to login to view forum posts. We also provide a couple of example attack vectors that hackers could use if portions of the system are compromised. These cases might be theoretical or based on known exploits such as XSS (cross-site scripting).

Diagram

Legend

() --> request/response bodies
{} --> request parameters
[] --> cookies
BrowserStoreForumsFusionAuthHackerInitializeLogin (browser navigates away from SPA)Shopping cart loadSession expiresRefresh token still validShopping cart loadSession expiresRefresh token expiresRe-loginSSO login to forumsInitializeLogin (browser navigates away from SPA but auto-logs-in since the session exists)Forum loadAttack vectorsStolen refresh tokenStolen session idGET /1(SPA HTML, CSS & JavaScript)2AJAX GET /api/user[No cookies]3404 Missing4GET /oauth2/authorize {response_type=code}5(Login form HTML)6POST /oauth2/authorize(response_type=code)7302 Location: {redirect_uri w/ code}[SessionId HttpOnly w/ domain: example.fusionauth.io]8GET {redirect_uri w/ code}9POST /oauth2/token(code, client_secret)10200 Ok(Refresh token and JWT)11Create new session12302 Location: /[SessionId and Refresh token HttpOnly w/ domain: store.example.com]13GET /14(SPA HTML, CSS & JavaScript)15AJAX GET /api/user[SessionId and Refresh token HttpOnly w/ domain: store.example.com]16200 Ok(User)17AJAX GET /api/load-shopping-cart[SessionId and Refresh token HttpOnly w/ domain: store.example.com]18Session extended19(Shopping cart contents)20AJAX GET /api/load-shopping-cart[SessionId and Refresh token HttpOnly w/ domain: store.example.com]21POST /oauth2/token or POST /api/jwt/refresh(grant_type=refresh and refresh token)22(JWT)23Create new session24(Shopping cart contents)[New SessionId HttpOnly w/ domain: store.example.com]25AJAX GET /api/load-shopping-cart[SessionId and Refresh token HttpOnly w/ domain: store.example.com]26POST /oauth2/token or POST /api/jwt/refresh(grant_type=refresh and refresh token)27404 Missing28401 Not Authorized29Login same as above30GET /[No cookies]31(SPA HTML, CSS & JavaScript)32GET /api/user[No cookies]33404 Missing34GET /oauth2/authorize {response_type=code}[SessionId HttpOnly w/ domain: example.fusionauth.io]35302 Location: {redirect_uri w/ code}[SessionId HttpOnly w/ domain: example.fusionauth.io]36GET {redirect_uri w/ code}37POST /oauth2/token(code, client_secret)38200 Ok(Refresh token and JWT)39Create session andstore User in it40302 Location: /[SessionId HttpOnly w/ domain: store.example.com]41GET /42(SPA HTML, CSS & JavaScript)43AJAX GET /api/user[SessionId HttpOnly w/ domain: store.example.com]44200 Ok(User)45AJAX GET /api/load-posts[SessionId and Refresh token HttpOnly w/ domain: forums.example.com]46Session extended47(Forum posts)48GET /shopping-cart[Refresh token and bad session id HttpOnly w/ domain: store.example.com]49POST /oauth2/token or POST /api/jwt/refresh(grant_type=refresh and refresh token)50(JWT)51Create session andstore User in52(Shopping cart contents)[New session id HttpOnly w/ domain: store.example.com]53GET /api/load-shopping-cart[SessionId HttpOnly w/ domain: store.example.com]54Session extended55(Shopping cart contents)56BrowserStoreForumsFusionAuthHacker

Explanation

  1. The browser requests the shopping cart single-page application from the application backend
  2. The application backend responds with the HTML, CSS & JavaScript of the application
  3. The browser loads the application and as part of the initialization process, it makes a request to the application backend to see if the user is logged in
  4. The application backend responds with a 404 indicating the user is not logged in
  5. The user clicks the login link and the browser navigates away from the single-page application to FusionAuth's OAuth 2 interface. The browser requests the OAuth 2 login page from FusionAuth with a response_type of code indicating that it is using the authorization code grant
  6. FusionAuth responds with the HTML, CSS & JavaScript of the login page (including the form)
  7. The user inputs their credentials and clicks the submit button. The browser POSTs the form data to FusionAuth
  8. FusionAuth returns a redirect to the application backend's OAuth 2 redirect_uri. This redirect includes the authorization code from FusionAuth. Also, this response includes a session id for the FusionAuth OAuth 2 interface as an HTTP cookie. This cookie is HttpOnly, which prevents JavaScript from accessing it, making it less vulnerable to theft
  9. The browser requests the application backend's OAuth redirect_uri with the authorization code from FusionAuth
  10. The application backend calls FusionAuth's OAuth 2 token endpoint with the authorization code and optionally the client_secret
  11. FusionAuth verifies the authorization code and client_secret. It returns a 200 along with a JWT and refresh token in JSON
  12. The application backend receives the 200 from FusionAuth and creates a server-side session and stores the User object (or JWT) in it
  13. The application backend returns a redirect back to the single-page application. The id for the server-side session is written back to the browser in an HTTP cookie. The refresh token from FusionAuth is also written back to the browser in an HTTP cookie. These cookies are HttpOnly, which prevents JavaScript from accessing them, making them less vulnerable to theft. Additionally, all requests from the browser to the application backend will include these cookies so that the backend can retrieve the User object from the server-side session and refresh their session if it expires
  14. The browser requests the shopping cart single-page application from the application backend
  15. The application backend responds with the HTML, CSS & JavaScript of the application
  16. The browser loads the application and as part of the initialization process, it makes a request to the application backend to see if the user is logged in
  17. The application backend responds with a 200 and the User object (usually in JSON)
  18. The browser requests the user's shopping cart from the application backend via AJAX and includes the session and refresh token cookies
  19. The application backend looks up the server-side session associated with the session cookie and extends the expiration date
  20. The application backend loads the User object (or JWT) from the server-side session. The backend then looks up the user's shopping cart from the database (or similar location). Finally, the application backend returns the user's shopping cart contents (usually as JSON)
  21. A while later, the user's session expires and the user clicks on their shopping cart again. The browser requests the shopping cart from the application backend via AJAX and sends the session id and refresh token cookies to the application backend
  22. The application backend attempts to load the server-side session associated with session cookie and realizes it is expired. Since the browser also sent across the refresh token, the application backend calls the JWT refresh API in FusionAuth with the refresh token
  23. FusionAuth looks up the refresh token and returns a new JWT
  24. The application backend receives the 200 from FusionAuth and creates a server-side session and stores the User object (or JWT) in it
  25. The application backend responds with the user's shopping cart contents (usually as JSON). It also includes the new session id as a cookie that replaces the old session id in the browser
  26. A while later, the user's server-side session and refresh token both expire and the user clicks on their shopping cart again. The browser requests the shopping cart from the application backend via AJAX and sends the session and refresh token cookies to the application backend
  27. The application backend attempts to load the server-side session associated with session cookie and realizes it is expired. Since the browser also sent across the refresh token, the application backend calls the JWT refresh API in FusionAuth with the refresh token
  28. Since the refresh token has expired, FusionAuth returns a 404 status code
  29. Since FusionAuth returned a 404 status code, the application backend returns a 401 indicating that the user is no longer logged in
  30. At this point, the application can allow the user to log in the same way they did above
  31. The browser requests the forum single-page application from the application backend. This is a standard SSO login that is fully supported by FusionAuth
  32. The application backend responds with the HTML, CSS & JavaScript of the application
  33. The browser loads the application and as part of the initialization process, it makes a request to the application backend to see if the user is logged in
  34. The application backend responds with a 404 indicating the user is not logged in
  35. The user clicks the login link and the browser navigates away from the single-page application to FusionAuth's OAuth 2 interface. The browser requests the OAuth 2 login page from FusionAuth with a response_type of code indicating that it is using the authorization code grant. Additionally, the session cookie that was set during the first login is also sent by the browser to FusionAuth
  36. FusionAuth realizes that the user already has a session and is already logged in. Therefore, it returns a redirect to the application backend's OAuth 2 redirect_uri. This redirect includes the authorization code from FusionAuth
  37. The browser requests the application backend's OAuth redirect_uri with the authorization code from FusionAuth
  38. The application backend calls FusionAuth's OAuth 2 token endpoint with the authorization code and optionally the client_secret
  39. FusionAuth verifies the authorization code and client_secret. It returns a 200 along with a JWT and refresh token in JSON. **NOTE**: all of this happens without any user interaction, hence the SSO nature of this login
  40. The application backend receives the 200 from FusionAuth and creates a server-side session and stores the User object (or JWT) in it
  41. The application backend returns a redirect back to the single-page application. The id for the server-side session is written back to the browser in an HTTP cookie. The refresh token from FusionAuth is also written back to the browser in an HTTP cookie. These cookies are HttpOnly, which prevents JavaScript from accessing them, making them less vulnerable to theft. Additionally, all requests from the browser to the application backend will include these cookies so that the backend can retrieve the User object from the server-side session and refresh their session if it expires
  42. The browser requests the forums single-page application from the application backend
  43. The application backend responds with the HTML, CSS & JavaScript of the application
  44. The browser loads the application and as part of the initialization process, it makes a request to the application backend to see if the user is logged in
  45. The application backend responds with a 200 and the User object (usually in JSON)
  46. The browser requests the user's forum posts from the application backend via AJAX and includes the session and refresh token cookies
  47. The application backend looks up the server-side session associated with the session cookie and extends the expiration date
  48. The application backend loads the User object (or JWT) from the session associated with the session cookie. The backend then looks up the user's forum posts from the database (or similar location). Finally, the application backend returns the user's forum posts (usually as JSON)
  49. This is an attack vector where the attacker has stolen the user's refresh token. Here, the attacker requests the user's shopping cart with the stolen refresh token and an invalid session id
  50. The application backend verifies the session id and realizes it is invalid. Since the attacker also sent across the refresh token, the application backend calls the JWT refresh API in FusionAuth with the refresh token
  51. FusionAuth looks up the refresh token and returns a new JWT
  52. The application backend receives the 200 from FusionAuth and creates a server-side session and stores the User object (or JWT) in it
  53. The application backend uses the JWT to look up the user's shopping cart. It responds to the attacker with the user's shopping cart contents (usually as JSON). It also includes the new session id as a cookie that attacker can now use
  54. This is an attack vector where the attacker has stolen the user's session cookie. Here, the attacker requests the user's shopping cart with the stolen session cookie
  55. The application backend looks up the server-side session associated with the session cookie and extends the expiration date
  56. The application backend uses the session to look up the user's shopping cart. It responds to the attacker with the user's shopping cart contents (usually as JSON)

Security considerations

This is one the safest and most feature rich login workflow in FusionAuth. It has the benefit that passwords are only provided directly to FusionAuth. It also has the benefit of full SSO capabilities when the user is automatically logged into the forum application by FusionAuth. Also, the session and refresh tokens are HttpOnly cookies that are domain locked to the application backend that needs them. Plus, the User object (or JWT) is secured on the server inside a server-side session.

APIs used

Here are the FusionAuth APIs used in this example: