Configure Authentication

Published: 2022-05-23

Authentication is a crucial part of every application.

WunderGraph allows you to use cookie-based authentication for web apps.

For non-browser based environments, you can use token based authentication.

To configure authentication in WunderGraph, you have to set up the auth providers and define authorized redirect URIs.

Cookie-Based Authentication is the best possible authentication flow to be used with a web-based application. The WunderGraph Server acts as a Token Handler in this case. The whole flow is handled server-side, on the WunderGraph server, meaning that an auth code is obtained via the browser but exchanged via the secure back-channel (server-to-server).

Once the authentication flow is complete, a secure encrypted cookie is set, which keeps the user logged in.

Authentication Providers#

WunderGraph relies on OpenID Connect (OIDC) Identity Providers to be able to authenticate users. Possible providers could be:

GitHub
Google
Auth0
Okta
Keycloak
any other OIDC compatible provider

Authorized Redirect URIs#

The WunderGraph authentication workflow looks like this. First, the web Application starts the login flow and redirects the user to the WunderGraph Server (WunderNode). The WunderNode will then redirect the user to the auth provider. Once the login flow is successful, the user will be redirected back to the web application.

To make this flow as secure as possible, we have to configure a whitelist of authorized redirect URIs. These URIs are the only allowed targets to redirect to after a successful authentication flow. You have to explicitly allow all URIs.

Configuration#

Find below an annotated version of configureWunderGraphApplication.

configureWunderGraphApplication({
    ...
    authentication: {
        cookieBased: {
            providers: [
                authProviders.demo(), // default auth provider (GitHub demo account, don't use in production)
                authProviders.github({
                    id: "github", // you have to choose this ID
                    clientId: "XXX", // client ID from GitHub
                    clientSecret: "XXX" // client secret from GitHub
                }),
                authProviders.google({
                    id: "google", // you have to choose this ID
                    clientId: "XXX.apps.googleusercontent.com", // client ID from Google
                    clientSecret: "XXX" // client secret from Google
                }),
                authProviders.openIDConnect({
                    id: "auth0", // you have to choose this ID
                    clientId: "XXX", // client ID from Auth0
                    clientSecret: "XXX" // client secret from Auth0
                }),
                authProviders.openIDConnect({
                    id: "okta", // you have to choose this ID
                    clientId: "XXX", // client ID from Okta
                    clientSecret: "XXX" // client secret from Okta
                }),
            ],
            // authorizedRedirectUris are the allowed redirect URIs
            authorizedRedirectUris: [
                // the two URIs below are allowed redirect targets
                "http://localhost:3000/demo",
                "http://localhost:3000/generatedform"
            ]
        }
    },
    ...
});

Token-Based Authentication#

Token-Based Authentication is very flexible and gives you a lot of different ways of authenticating client against your WunderGraph applications. This way, you're able to use WunderGraph with code- or device flows. The responsibility to obtain an access token in this scenario is on the client itself.

Usage#

Using token based authentication with WunderGraph follows a simple principle. Your client obtains a token any way they want. They then set the token as the Authorization Header. The header value needs to be prefixed with "Bearer ".

`Authorization: Bearer ${TOKEN}`

The WunderGraph Server will then use a JSON Web Key Set from your OpenID Connect Server to validate the token, in case of a JWT. If the token is opaque (just a reference), the JWKS step will be skipped.

Finally, we're using the userInfo Endpoint of the OpenID Connect Server to obtain all available claims from the user, e.g. their username and email, which are then stored within the WunderGraph user Identity.

Calling the userInfo Endpoint might be expensive, and it also takes some time. For that reason, you're able to configure a time to live to allow the WunderGraph server to cache the userInfo response.

Configuration#

Configuring token-based Authentication is straight forward. You can set the jwks URL as well as the userInfoEndpoint like so:

configureWunderGraphApplication({
    authentication: {
        tokenBased: {
            providers: [
                {
                    jwksURL: "https://wundergraph.fusionauth.io/.well-known/jwks.json",
                    userInfoEndpoint: "https://wundergraph.fusionauth.io/oauth2/userinfo",
                }
            ]
        }
    },
});

Alternatively, you can also pass the jwks as a JSON String.

configureWunderGraphApplication({
    authentication: {
        tokenBased: {
            providers: [
                {
                    userInfoEndpoint: "https://wundergraph.fusionauth.io/oauth2/userinfo",
                    jwksJSON: "...",
                }
            ]
        }
    },
});

Finally, you're able to set the TTL to cache the userInfo response. The default TTL is: 60 * 60 = 1 hour

configureWunderGraphApplication({
    authentication: {
        tokenBased: {
            providers: [
                {
                    jwksURL: "https://wundergraph.fusionauth.io/.well-known/jwks.json",
                    userInfoEndpoint: "https://wundergraph.fusionauth.io/oauth2/userinfo",
                    userInfoCacheTtlSeconds: 60 * 60
                }
            ]
        }
    },
});