Registry / security / keycloak-connect-graphql

keycloak-connect-graphql

library0.7.0jsnpmunverified

A comprehensive solution for adding Keycloak authentication and authorization to Express-based GraphQL servers. Version 0.7.0 works with graphql ^0.12.0 to ^15.0.0 and keycloak-connect >=9.0.0. It provides auth at the GraphQL layer via declarative `@auth`, `@hasRole`, and `@hasPermission` directives (Apollo Server) or resolver middleware, with support for subscriptions and token/user info in context. Maintained by AeroGear, it differs from alternatives by focusing solely on Keycloak integration with Express/GraphQL.

security

npm install keycloak-connect-graphql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KEYCLOAK-CONNECT-G

keycloak-connect-graphql

securityjavascriptv0.7.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KeycloakContext

✓ import { KeycloakContext } from 'keycloak-connect-graphql'

✗ const KeycloakContext = require('keycloak-connect-graphql').KeycloakContext

ESM and CJS both supported; named export works in both environments.

KeycloakTypeDefs

✓ const { KeycloakTypeDefs } = require('keycloak-connect-graphql')

✗ import KeycloakTypeDefs from 'keycloak-connect-graphql'

Default export is not provided; use named import to get KeycloakTypeDefs.

KeycloakSchemaDirectives

✓ import { KeycloakSchemaDirectives } from 'keycloak-connect-graphql'

✗ const KeycloakSchemaDirectives = require('keycloak-connect-graphql')

Must destructure to get the directives object; not a default export.

Sets up an Apollo Server Express app with Keycloak auth, using the @auth directive on the 'hello' query.

const { ApolloServer, gql } = require('apollo-server-express'); const Keycloak = require('keycloak-connect'); const express = require('express'); const { KeycloakContext, KeycloakTypeDefs, KeycloakSchemaDirectives } = require('keycloak-connect-graphql'); const app = express(); const keycloak = new Keycloak(); app.use('/graphql', keycloak.middleware()); const typeDefs = gql` type Query { hello: String @auth } `; const resolvers = { Query: { hello: (_, __, context) => { return `Hello ${context.kauth.accessToken.content.preferred_username}`; }, }, }; const server = new ApolloServer({ typeDefs: [KeycloakTypeDefs, typeDefs], schemaDirectives: KeycloakSchemaDirectives, resolvers, context: ({ req }) => ({ kauth: new KeycloakContext({ req }, keycloak), }), }); server.applyMiddleware({ app }); app.listen({ port: 4000 }, () => console.log(`Server ready at http://localhost:4000${server.graphqlPath}`) );

Debug

Known issues

deprecatedschemaDirectives is deprecated in Apollo Server 3. Use @graphql-tools/schema or federation for custom directives.

fix

Upgrade to Apollo Server 4 and use the new directive API, or stick with Apollo Server 2.x.

affects: >=0.7.0

gotchaThe `keycloak.middleware()` must be applied to the GraphQL endpoint for token parsing; without it, `kauth` will lack token info.

fix

Ensure `app.use('/graphql', keycloak.middleware())` is called before creating the ApolloServer.

affects: >=0.0.0

gotchaGraphQL subscriptions require additional WebSocket setup; `keycloak-connect-graphql` does not automate this.

fix

Manually configure subscriptions with Keycloak authentication on the WebSocket upgrade.

affects: >=0.0.0

deprecatedNode.js 10 and earlier are not supported; keycloak-connect-graphql may have issues on legacy Node versions.

fix

Use Node.js 12 or later.

affects: >=0.7.0

Errors

Common errors & fixes

Cannot find module 'keycloak-connect-graphql'

Missing npm install or incorrect import path.

fix

Run `npm install keycloak-connect-graphql` and ensure the import matches the package name.

TypeError: keycloak.middleware is not a function

keycloak-connect not installed or incorrectly referenced.

fix

Run `npm install keycloak-connect` and ensure `keycloak = new Keycloak()` is used.

GraphQLError: Unknown directive "auth"

KeycloakTypeDefs not included in typeDefs array or schemaDirectives not set.

fix

Add `KeycloakTypeDefs` to the typeDefs array and set `schemaDirectives: KeycloakSchemaDirectives` in ApolloServer config.

Cannot read property 'accessToken' of undefined

KeycloakContext not instantiated or missing from context.

fix

Ensure `kauth: new KeycloakContext({ req }, keycloak)` is in the context object passed to ApolloServer.

Upgrade

Version history

0.7.0latest on npm

Audit

Dependencies

graphqlrequiredpeer dependency - required for GraphQL integration

keycloak-connectrequiredpeer dependency - required for Keycloak middleware and token handling

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/aerogear/keycloak-connect-graphql ↗

packagekeycloak-connect-graphql ↗

homepagehttp://aerogear.org ↗