🔐

Adding Local Authentication

Local Authentication

Local authentication can be used to secure access to Graphweaver using a set of credentials stored in a local datastore.

Let’s start by covering the key components that we will use.

Graphweaver Auth Package

The @exogee/graphweaver-auth package exports a number of properties that you need to understand before implementing authentication. Let’s take a look at these:

  1. AuthorizationContext: The AuthorizationContext is a typescript type. It represents the context object that is passed to resolvers and hooks during the execution of GraphQL operations. It contains information about the authenticated user, including their roles and authentication token. The AuthorizationContext is used to implement authorization logic and make decisions based on the user's access permissions.
  2. passwordAuthApolloPlugin: passwordAuthApolloPlugin is a plugin for the Apollo Server, which is the underlying GraphQL server used by Graphweaver. This plugin enhances the server's functionality by adding support for username/password authentication. It hooks into the authentication process, allowing you to define custom logic for authenticating users and generating their authentication tokens.
  3. setAdministratorRoleName: setAdministratorRoleName is a function used to set the role name for the administrator user in the authentication system. You can use this function to customize the role name according to your application's needs. The administrator role typically has elevated privileges and permissions within the system.
  4. createPasswordAuthResolver is a function that returns a base resolver class that you can extend. This class is used to expose password-based local authentication functionality in your GraphQL API. For example, this will add a login mutation to the GraphQL schema.

Next, let’s look at the steps we need to perform to get authentication working, which are:

  1. Creating an AuthResolver
  2. Creating a addUserToContext function that adds the logged-in user details to the context
  3. Optionally, restrict access to the admin-ui

But first, let’s cover the environment variables that need to be created:

Environment Variables

There are three environment variables required when implementing local authentication:

  • PASSWORD_AUTH_PUBLIC_KEY_PEM_BASE64: This environment variable contains the PEM-formatted, Base64 encoded public key which will be used to verify tokens provided in API requests.
  • PASSWORD_AUTH_PRIVATE_KEY_PEM_BASE64: This environment variable contains the PEM-formatted, Base64 encoded private key which will be used to sign tokens provided to API consumers upon successful authentication.
  • PASSWORD_AUTH_REDIRECT_URI: This environment variable represents the redirect URI you would like users to be sent to when they are challenged for authentication.

See this gist for more information on how to create the PEM.

Once you have your environment variables setup let’s look at the AuthResolver.

Creating an AuthResolver

The AuthResolver is used to add a login mutation to the schema. To create this resolver it is best to place the file in your ./src/schema directory. The AuthResolver will look like this: 

@Resolver()
export class AuthResolver extends createPasswordAuthResolver<OrmCredential>(
	Credential,
	new MikroBackendProvider(OrmCredential, myConnection)
) {
  // This is called when a user has logged in to get the profile
	async getUserProfile(
		id: string,
		operation: PasswordOperation,
		params: RequestParams
	): Promise<UserProfile> {
		// This is called when a user has logged in to get the profile
	}
}

As you can see above we have extended the createPasswordAuthResolver class with the PasswordAuthResolver. Yet, the implementation is not complete. To support authentication you must define a getUserProfile function. This function will be called when the login mutation is executed. A valid getUserProfile function will look like this: 

async getUserProfile(
		id: string,
		operation: PasswordOperation,
		params: RequestParams
	): Promise<UserProfile> {
		const user = User.fromBackendEntity(await BaseLoaders.loadOne({ gqlEntityType: User, id }));

		if (!user) throw new Error('Bad Request: Unknown user id provided.');

		if (operation === PasswordOperation.REGISTER) {
			// As an example we could send an email to the newly registered user
		}

		return mapUserToProfile(user);
	}
}

In the example above, we are fetching the User data for the logged-in user. Now we have created this AuthResolver make sure to include it in the Graphweaver configuration next to your existing resolvers: 

const resolvers = [...resolvers, AuthResolver];

Adding the User to the Context

Now that we have the resolver setup there is one more step. In order for authentication to be checked on each request we have to add the Apollo password auth plugin.

Let’s add the passwordAuthApolloPlugin to the Graphweaver server.

Password Authentication Apollo Plugin

This is what the Graphweaver configuration would look like with the plugin added:

import { passwordAuthApolloPlugin } from '@exogee/graphweaver-auth';

const graphweaver = new Graphweaver<AuthorizationContext>({
  ...
  apolloServerOptions: {
    introspection: isOffline,
    plugins: [passwordAuthApolloPlugin(addUserToContext)],
  },
	...
});

As you can see from the above example we are adding the PasswordAuthApolloPlugin to the plugins section of the apolloServerOptions. There is also a addUserToContext function.

Let’s look at this next and how it is used.

Add User to Context

The addUserToContext is used to populate the AuthorizationContext with a UserProfile.

The UserProfile is a normalized view of a User and it is the addUserToContext function that maps your User entity to the UserProfile. Here is an example:

export const addUserToContext = async (userId: string) => {
  const user = User.fromBackendEntity(
    await BaseLoaders.loadOne({ gqlEntityType: User, id: userId })
  );

  if (!user) {
    throw new Error('Bad Request: Unknown user id provided.');
  }

  return mapUserToProfile(user);
};

From the above, you can see we are receiving a userId and then fetching the user details. Finally, we are mapping the User entity to the UserProfile. This UserProfile will then be passed to the functions inside the ACL. For more information on this see the implementing authorization section.

Securing Requests Admin UI

The admin UI is populated using the _graphweaver query and there may be times when you need to control access to this query.

To do that we can use the Admin-UI’s beforeRead hook.

Here is an example of using the hook to only allow authenticated users:

export const beforeRead = (context: AuthorizationContext) => {
  // Ensure only logged in users can access the admin UI metadata
  if (!context.token) {
    throw new ForbiddenError('Forbidden');
  }
};

Testing Authentication

Finally, to test that the authentication is working open the Admin UI at http://localhost:9000 and you will be redirected to the login page:

image

Exogee