API Gateways

    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.

    API gateway sample architecture.
    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.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.