Understanding client side flow and server side flow

This section details security matters in oauthd and explains how the client-side flow and server-side flow work when using this solution.

The client-side flow

Definition: By client-side flow we mean that the calls to the oauthd API are made directly from the front-end by using one of our front-end SDKs, and not from the back-end.

Here are the steps that are followed when using this flow:

• The user calls a popup method in one of our SDKs. It opens a popup, sending a request to oauthd telling it which provider is needed
• oauthd redirects the user to the provider's authorization form
• Once the user authorizes the app, the provider redirects the user back to oauthd, which will automatically retrieve the token and send it back to the SDK

We added an implicit state to check the flow integrity:

1. This state is generated in the front-end SDK when showing the popup / redirection, and is stored client-side
2. When receiving oauthd's response, the returned state is compared to the local one immediately before giving the response to the developer (usually in a callback)

The server-side flow

Definition: By server-side flow we mean that the back-end makes the API call to our API endpoint.

Here are the steps that are followed when using this flow:

• The user calls a popup method in one of our SDKs. It opens a popup, sending a request to oauthd telling it which provider is needed
• oauthd redirects the user to the provider's authorization form
• Once the user authorizes the app, the provider redirects the user back to oauthd, which will automatically retrieve access code (instead of a token) that is exchanged by calling oauthd's endpoint /auth/access_token (see the REST API reference) from your backend.

This flow means that token are not store in the user's browser, so that it cannot be exploited with a XSS / CSRF vulnerability.

The state is no longer optional when calling the OAuth.popup method or its equivalents in other SDKs. The state must be generated from your server, and checked once the code is exchanged. This step is required to avoid any CSRF exploit.

All of this is done automatically by our server-side SDKs (NodeJs and PHP).

Security concerns

• The received codes are single use codes, and have a short expiration time, to prevent a third person from using them
• The valid domains/url depend on the details level. The user can restrict this to a single URL scheme://domain:port/path: the more detailed the URL is, the smaller the attack surface
• The "state" parameter is mandatory when doing server-side auth, to avoid CSRF exploits
• The client-side/server-side setting (token/code) is chosen when you select a backend (or none) in your app
• We don't store any access tokens

And more generally:

• We have avoided URL fragment leak (to get an access_token from a referrer)
• We have checked lots of CSRF/XSS potential security exploits
• The website is API based/driven, so security is easier to manage