Logo / Articles

Login & Auth Workflows

WebApp OAuth Login Using Authorization Code Grant With Sessions - Recommended

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 WebApp)Shopping cart loadSession expiresRe-loginSSO login to forumsInitializeLogin (browser navigates away from WebApp but auto-logs-in since the session exists)Forum loadAttack vectorsStolen session idGET /1(HTML, CSS & JavaScript - with login link)2GET /oauth2/authorize {response_type=code}3(Login form HTML)4POST /oauth2/authorize (response_type=code)5302 Location: {redirect_uri w/ code}[SessionId HttpOnly w/ domain: example.fusionauth.io]6GET {redirect_uri w/ code}7POST /oauth2/token(code, client_secret)8200 Ok(Refresh token and JWT - ignored)9Create session andstore User in it10302 Location: /shopping-cart[SessionId HttpOnly w/ domain: store.example.com]11GET /shopping-cart[SessionId HttpOnly w/ domain: store.example.com]12Session extended13(Shopping cart HTML)14GET /shopping-cart[SessionId HttpOnly w/ domain: store.example.com]15302 Location: /login16Login same as above17GET /[No cookies]18(HTML, CSS & JavaScript - with login link)19GET /oauth2/authorize {response_type=code}[SessionId HttpOnly w/ domain: example.fusionauth.io]20302 Location: {redirect_uri w/ code}[SessionId HttpOnly w/ domain: example.fusionauth.io]21GET {redirect_uri w/ code}22POST /oauth2/token(code, client_secret)23200 Ok(Refresh token and JWT - ignored)24Create session andstore User in it25302 Location: /posts[SessionId HttpOnly w/ domain: forums.example.com]26GET /posts[SessionId HttpOnly w/ domain: forums.example.com]27Session extended28(Forum posts HTML)29GET /shopping-cart[SessionId HttpOnly w/ domain: store.example.com]30Session extended31(Shopping cart HTML)32BrowserStoreForumsFusionAuthHacker

Explanation

  1. The browser requests the shopping cart webapp's homepage from the application backend
  2. The application backend responds with the HTML, CSS & JavaScript of the homepage
  3. The user clicks the login link and the browser navigates away from the webapp 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
  4. FusionAuth responds with the HTML, CSS & JavaScript of the login page (including the form)
  5. The user inputs their credentials and clicks the submit button. The browser POSTs the form data to FusionAuth
  6. 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
  7. The browser requests the application backend's OAuth redirect_uri with the authorization code from FusionAuth
  8. The application backend calls FusionAuth's OAuth 2 token endpoint with the authorization code and optionally the client_secret
  9. FusionAuth verifies the authorization code and client_secret. It returns a 200 along with a JWT and refresh token in JSON
  10. The application backend receives the 200 from FusionAuth and creates a server-side session and stores the User object (or JWT) in it
  11. The application backend returns a redirect to the browser instructing it to navigate to the user's shopping cart. The id of the server-side session is written back to the browser in an HTTP cookie. This cookie is HttpOnly, which prevents JavaScript from accessing it, making it less vulnerable to theft. Additionally, all requests from the browser to the application backend will include this cookie so that the backend can retrieve the User object from the server-side session
  12. The browser requests the user's shopping cart from the application backend and includes the session cookie
  13. The application backend looks up the server-side session associated with the session cookie and extends the expiration date
  14. 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 shopping cart from the database (or similar location). Finally, the application backend returns the user's shopping cart as HTML, CSS & JavaScript that the browser renders
  15. A while later, the user's server-side session expires and the user clicks on their shopping cart again. The browser requests the shopping cart from the application backend and sends the session cookie to the application backend
  16. The application backend attempts to load the server-side session associated with session cookie and realizes it is expired. The backend then returns a redirect to the browser that sends the user to the login page
  17. The user can log in the same way they did above
  18. The browser requests the forum webapp's homepage from the application backend. This is a standard SSO login that is fully supported by FusionAuth
  19. The application backend responds with the HTML, CSS & JavaScript of the homepage
  20. The user clicks the login link and the browser navigates away from the webapp 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
  21. 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
  22. The browser requests the application backend's OAuth redirect_uri with the authorization code from FusionAuth
  23. The application backend calls FusionAuth's OAuth 2 token endpoint with the authorization code and optionally the client_secret
  24. 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
  25. The application backend receives the 200 from FusionAuth and creates a server-side session and stores the User object (or JWT) in it
  26. The application backend returns a redirect to the browser instructing it to navigate to the user's forum posts. The id of the server-side session is written back to the browser in an HTTP cookie. This cookie is HttpOnly, which prevents JavaScript from accessing it, making it less vulnerable to theft. Additionally, all requests from the browser to the application backend will include this cookie so that the backend can retrieve the User object from the server-side session
  27. The browser requests the user's forum posts from the application backend and includes the session cookie
  28. The application backend looks up the server-side session associated with the session cookie and extends the expiration date
  29. The application backend loads the User object (or JWT) from the session associated with the session cookie. The backend looks up the user's forum posts from the database (or similar location). Finally, the application backend returns the user's forum posts as HTML, CSS & JavaScript that the browser renders
  30. 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
  31. The application backend looks up the server-side session associated with the session cookie and extends the expiration date
  32. 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 HTML, CSS & JavaScript

Security considerations

This a safe and feature rich login workflow in FusionAuth. It has the benefit that passwords are only ever 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. The downside of this workflow is that the sessions might be shorter lived than refresh tokens, forcing the user to login more regularly. If this is the preferred behavior, than this workflow might be the best fit.

APIs used

Here are the FusionAuth APIs used in this example: