Portfolio note: This is a genericized version of internal developer documentation I wrote for a SaaS platform. Company names, hostnames, credentials, and internal paths have been replaced with placeholders.

Overview

FusionAuth is an OIDC-compliant OAuth2 provider. Moving authentication and login to a dedicated third-party provider gives the application a high level of security without the team having to build and maintain its own identity layer.

FusionAuth's own documentation is extensive and well-organized: FusionAuth docs. Enterprise plans include direct support channels; engineers can also get help by email or by opening a support ticket.

Endpoints

Environment Endpoint
Development https://auth-dev.example.com
Production https://accounts.example.com

Your organization's secrets manager stores login credentials for each environment. Never commit them to source control.

Configuration keys

The required keys and routes are found in the corresponding Application in FusionAuth. Add them to the stack's configuration table.

Development

OAUTH2_ENDPOINT=https://auth-dev.example.com
OAUTH2_CLIENT_ID=<dev-client-id>
OAUTH2_CLIENT_SECRET=<from secrets manager>
OAUTH2_CLIENT_ID_WIZARD=<dev-wizard-client-id>
OAUTH2_CLIENT_SECRET_WIZARD=<from secrets manager>

Production

OAUTH2_ENDPOINT=https://accounts.example.com
OAUTH2_CLIENT_ID=<prod-client-id>
OAUTH2_CLIENT_SECRET=<from secrets manager>
OAUTH2_CLIENT_ID_WIZARD=<prod-wizard-client-id>
OAUTH2_CLIENT_SECRET_WIZARD=<from secrets manager>

API keys and secrets

Generate API keys in FusionAuth under Settings → API Keys. Grant each key only the permissions it needs, and rotate keys every 3 to 6 months.

UI and themes

FusionAuth themes use the FreeMarker template language.

Note: FusionAuth uses FreeMarker's square-bracket syntax, [#command], not the HTML-like <#command> variant. Mixing them is a common source of template errors.

Keep production login and email templates in version control alongside the application code (for example, assets/fusionauth-templates and assets/fusionauth-email-templates).

Standard template workflow

  1. Edit the templates locally.
  2. Upload them to the development FusionAuth environment.
  3. Test them.
  4. If they work, commit them via a merge/pull request.
  5. After review, upload them to production.

Templates can be synced with FusionAuth through its API using a helper script. An example upload call:

node ./scripts/fusionauth-templates.js --mode put \
  --endpointUrl https://ENDPOINT_URL \
  --apiKey <api-key> \
  --tenantId <tenant-id> \
  --themeRootDir assets/fusionauth-templates \
  --themeId <theme-id>

Bulk user import

When migrating from another identity provider (such as Auth0), export user data from the old provider and import it using FusionAuth's bulk import API. Document the export format and import script in your repo's README so the migration is repeatable.

Serving multiple stacks from one application

A single FusionAuth Application can serve multiple stacks (for example, several dev or staging environments). Each stack must redirect back to its own API login URL.

  • Add each stack's login URL to Authorized Redirect URLs in the Application's OAuth settings, using the format <your-api-root-url>/api/login (for example, https://staging-api.example.com/api/login).
  • Make sure the API's logout handler redirects to /api/login using the post_logout_redirect_uri query parameter, so users land on the correct stack after logging out.

Adding name claims to the JWT

To include name, given_name, and family_name in the issued JWT, add a JWT-populate lambda under Settings → Lambdas and assign it to the Application.

Troubleshooting

My dev or local stack won't log me in.
Check the configuration table in your database. It should contain values similar to:

OAUTH2_CLIENT_ID      "<dev-client-id>"
OAUTH2_CLIENT_SECRET  ""
OAUTH2_ENDPOINT       "https://auth-dev.example.com"

If the table has OAUTH2_TENANT instead of OAUTH2_ENDPOINT, authentication will fail. Rename the key.

I need to develop offline.
Run FusionAuth locally using the official Docker images.

Additional references