Logo / Docs

API Gateways Overview

Overview

FusionAuth is an OIDC and OAuth server, which means it integrates with a variety of third party systems out of the box. One of those systems is an API gateway. It is a common architectural pattern to have an authentication system generate a token which is then presented to other services. These services can sit behind an API Gateway, which offers throttling, billing and checks for authenticated requests.

General Integration Guidance

In general, you’ll want to do the following to perform an API gateway integration using OIDC.

In FusionAuth:

  • Create an Application in FusionAuth.
  • Record the Client Id and the Client Secret .
  • Provide the Client Id and the Client Secret to the web application which will complete the Authorization Code grant. This may be the API gateway or a custom application.
  • Add the configured redirect URL to the Authorized redirect URLs field. This may be the API gateway or a custom application.

You typically need to ensure that FusionAuth is signing the JWT with an asymmetric key. Do that by navigating to Settings -> Key Master to create or import the key pair. Then configure the Application to use the key by navigating to Applications -> Your Application -> JWT.

In the API gateway:

  • Provide the URL for FusionAuth, often called the issuer.
  • Configure the API gateway with the client Id, and sometimes the secret, from the Application.
  • Configure which claims of the JWT the API gateway should inspect.
  • Add routes in the API gateway to forward requests to services.

If the API gateway does not support token exchange, but instead expects a token:

  • Create a web application which can receive the one-time Authorization Code and exchange it for an access token. Provide this web application with the client secret.
  • Have the web application securely provide the client the token.

After this is configured, when the user tries to access a service, they’ll be prompted to login. After they successfully do so, the API gateway will examine the token and allow access if applicable.

FusionAuth also supports SAML integrations. Learn more about how FusionAuth can act as a SAML IdP.

Sample Architecture

Here’s a sequence diagram with an example API gateway protecting two services.

UserFusionAuthToken ExchangerAPI GatewayService AService BRequests Service AToken validationfailure (it doesn't exist)Sends redirect to FusionAuthAuthenticatesVerifies credentialsRedirects user to exchangerRequests tokenIssues tokenRequests Service A and presents tokenValidates tokenForwards request for Service AData from Service ADataRequests Service B and presents tokenValidates tokenForwards request for Service BDataData from Service BUserFusionAuthToken ExchangerAPI GatewayService AService B

API gateway sample architecture.

Token Location

The location of the token in the request is typically in one of two places:

  • The Authorization header
  • A secure, HttpOnly cookie

The former is compatible with a variety of API gateways and open source libraries.

The latter is more secure when used for browser based clients such as SPAs, since JavaScript doesn’t have access to the token. It is also compatible with the Hosted Backend APIs, which use FusionAuth to perform the token exchange.

Example Integrations

Here are some example API gateway integrations.