chrisjsherm/fusionauth-javascript-sdk-express

Example: FusionAuth Web SDKs Server Implementation

This repository provides an example server implementation for FusionAuth Web SDKs. FusionAuth Web SDKs can be utilized in one of two ways:

1. Hosting Your Own Server: Implementing a server that handles OAuth token exchange and fulfills the server code requirements for FusionAuth Web SDKs.
2. Using the FusionAuth Hosted Server: Leveraging the server hosted on your FusionAuth instance, eliminating the need to write your own server code.

If you opt for hosting your own server, this repository will serve as an example. The provided example is in JavaScript and utilizes Express. If you opt to implement your own server you are free to use any technology stack as long as it meets the server code requirements.

Setup

To get started, follow these steps:

1. From the root directory, run npm install.
2. Run npm run start.

You should observe the console output FusionAuth example server listening on port 9000.

Server code requirements

The endpoints described below serve as a summary of requirements and expected behaviors of each endpoint. For additional details on these endpoints you can reference the Hosted Backend documentation.

Your server must have the following endpoints:

GET /app/login

This endpoint must:

1. Generate PKCE code.
   • The code verifier should be saved in a secure HTTP-only cookie.
   • The code challenge is passed along
2. Encode and save redirect_url from the client app to state.
3. Redirect browser to /oauth2/authorize with a redirect_uri to /app/token-exchange

Example implementation

GET /app/callback

This endpoint must:

1. Call /oauth2/token to complete the Authorization Code Grant request. The code comes from the request query parameter and code_verifier should be available in the secure HTTP-only cookie, while the rest of the parameters should be set/configured on the server side.

2. Once the token exchange succeeds, read the app.at from the response body and set it as a secure, HTTP-only cookie with the same name.

3. If you wish to support refresh tokens, repeat step 2 for the app.rt cookie.

4. Save the expiration time in a readable app.at_exp cookie. This value should be represented as seconds since the epoch.

5. And save the app.idt id token in a readable cookie.

6. Redirect browser back to encoded url saved in state.

Example implementation

GET /app/register

This endpoint is similar to /login. It must:

1. Generate PKCE code.
   • The code verifier should be saved in a secure HTTP-only cookie.
   • The code challenge is passed along
2. Encode and save redirect_url from the client app to state.
3. Redirect browser to /oauth2/register with a redirect_uri to /app/callback

Example implementation

GET /app/me

This endpoint must:

1. Use app.at from cookie and use as the Bearer token to call /oauth2/userinfo
2. Return json data

Example implementation

GET /app/logout

This endpoint must:

1. Clear the app.at and app.rt secure, HTTP-only cookies.
2. Clear the app.at_exp and app.idt secure cookies.
3. Redirect to /oauth2/logout

Example implementation

POST /app/refresh (optional)

This endpoint is necessary if you wish to use refresh tokens. This endpoint must:

1. Call /oauth2/token to get a new app.at and app.rt.

2. Update the app.at, app.at_exp, app.idt, and app.rt cookies from the response.

Example implementation

Upgrade Policy

This library may periodically receive updates with bug fixes, security patches, tests, code samples, or documentation changes.

These releases may also update dependencies, language engines, and operating systems, as we'll follow the deprecation and sunsetting policies of the underlying technologies that the libraries use.

This means that after a dependency (e.g. language, framework, or operating system) is deprecated by its maintainer, this library will also be deprecated by us, and may eventually be updated to use a newer version.