Enable Single-Sign-On and Group-based-access-control in a Next.js app with a Grafbase API using Grafbase Auth capabilities and Authdog IdP
ContextGrafbase is a platform to enable developers to ship faster GraphQL APIs on the Edge and simplify connectivity with 3rd party technologies as a federated GraphQL endpoint.
Authdog is a Customer Identity and Access Management platform to centralize Identity and access control management for Web Applications/APIs/Backend services.
Grafbase offers granular access control compatible with external Identity Providers.
This guide will walk through the steps to get started with Authdog and Grafbase Auth, to get in minutes a functional Next.js connected securely to a backend, with groups managed in the Authdog platform and session token validated on Grafbase. The code for this example is available in this repository: https://github.com/authdog-samples/grafbase-auth
- Codebase: Turborepo
- Frontend application: Next.js / Tailwind starter
- Backend service: Grafbase SDK/API
- Authentication as a service: Authdog SDK/API
Application creationTo enable users to authenticate in the front-end application, the first step consists in registering an Application in Authdog Console Dashboard, first thing to do is to follow console.authdog.com and create an account.
You’ll be invited to create a Tenant, once done, you’ll see a Page like this one:
To get to the new Application form, click on the
New Applicationbutton on the top right. You’ll be redirected to a multi-step form, to define basic information about your project, respectively naming your application, adding connections to it, and defining redirections.
Once you’ve defined the basic information of your project, you’ll see a list of providers.
Simply click on the gear button, and you’ll see a form to configure your provider.
Go to your Identity Provider to figure out where to find your Client ID, Client Secret obtained when creating an OAuth2 Client; paste the Redirect URI copied from this form into your provider-authorized URI for your connection.
Note that the Redirect URI is unique per provider, connection and per environment
Once ready, click on Save.
To have your Login Form working, you need to define a Redirection after successful login, for your local instance, it can be localhost:3000/dashboard to be the path the user will be redirected to after a successful Authentication. Click on
Now that we’ve configured our Application in Authdog Console, we’ll need to create a Grafbase Project. We’ll use the Command Line Interface (CLI) to do so.
Grafbase Project creation
To create a Grafbase project from the CLI, you’ll need to pass a name, account and region to the `grafbase create` target.
Grafbase TypeScript configuration
Now that the project is created we’ll define our Grafbase configuration and a protected resolver. First, we import g, auth, config being respectively schema builder, auth configuration builder and grafbase configuration builder.
Then we’ll instantiate the auth configuration builder
We’ve created an Authdog auth config object for an OpenID configuration, with the issuer being `id.auth.dog (iss field in the token claims, and must have a jwks endpoint at https://id.auth.dog/.well-known/jwks.json). By default, when you’re creating an application in Authdog without creating signing keys, the default ones from the Authdog region will be used to sign your JSON Web Tokens. groupsClaim is the claim in your JWT that self-contains your user’s groups. It can be configured in Authdog JWT Manager.
Then we’ll create a resolver, in our Grafbase project in `grafbase/resolvers/hello-world.ts`. The goal is to enable access to this resolver to a user with specific group membership.
We’ll reference this resolver in our grafbase configuration, it’ll be `helloWorld` query in our schema.
Finally, we’ll define our auth block for the schema
Our auth block takes two parameters:
- providers, being the list of auth providers for the schema
- rules, being the rules applied to the schema
To enable access to a given group, you pass its id in the rules goups array parameter. Using a uuid is a deliberate choice to allow group renaming in the Authdog dashboard without breaking the access-control logic at scale.
Our config will look like this:
JWT group claims configuration
Add groups claims field
Go to console.authdog.com/jwt-manager, and make sure the environment is the same as the one used for connecting an SSO identity provider. The group claim field must match the one defined in the Grafbase configuration.
After saving, you’ll see the claims preview updated:
Now we’ll now enable Authentication in our app.
Frontend App configuration
React SDK in Next.js
Once the dependencies are installed, we’ll add AuthdogProvider to our app.
Next.js 12 (App Router will be soon supported)
You can grab the parameters from Authdog Console Dashboard, in Application configuration:
Once those parameters are populated, your application is ready to authenticate users.
Next.js project can be started with the make dev command. Here’s the view you’ll see once the project is started locally:
After pressing Access Dashboard, you’ll be redirected to a Login form (managed in Authdog Cloud Console) with the Auth provider we previously configured in Authdog Console.
Finally, after authenticating, you should see this screen with the authenticated user:
Let’s move on to Authdog Access Control: console.authdog.com/access-control
You’ll see a list of users in the first tab, corresponding to the users having logged into your application, for the given environment.
By default, you don’t have any group, so go to the groups tab, click on Create Group to add a new group to your environment, populate your group information and once ready, click on Save Group.
Go back to the Users tab, and click on “Manage Groups for Selection”, a new modal will appear with a transfer list. On the left, users are available and on the right users have been added to the selected group.
Use the checkboxes to select your users on the left, and click on the center arrow to transfer them to the right
The user on the right panel belongs now to the “Grafbase Granted Group”.
This user claim in the JWT will be something like this below, note the groups claim having populated.
Now let’s copy this group’s id to add it to the Grafbase configuration.
This means now, users authenticating with Authdog, having been assigned to this group, will be able to access Grafbase services with a Single-Sign-On.
Note that once users are authenticated, and the token embeds the groups, you won’t be able to change ownership dynamically with this setup, it can be achieved by revoking the current signing key and forcing the user to reauthenticate to have the new group added to the claims, after authenticating again.
You’ll need to deploy your Grafbase API whenever you change the configuration.
Grafbase Integration in Next.js application
Now that we’ve got a group configured with a user, we’ll configure our front-end application to access our group secured query from our Grafbase API. The token provided by Authdog API will be used to access our Grafbase backend.
Here’s our GraphQL client wrapper code:
We’ll replace the endpoint parameter, with the endpoint previously created with Grafbase CLI and query parameter with `helloWorld` query. Invocation from the front-end application would be something like:
After having integrated this wrapper, we can now test the result with our protected endpoint.
User A has the required group membership:
User B doesn’t have the required group membership: