repository·main·Indexed 20 days ago
https://github.com/keycloak/keycloak-nodejs-connectA deprecated middleware module for integrating Node.js applications using Connect-style middleware with Keycloak for authentication and authorization. It provides the Keycloak class for configuration, middleware for Express apps, and methods like keycloak.protect() for role-based access control and keycloak.enforcer() for resource-based authorization via Keycloak Authorization Services.
This package is deprecated and will be removed in the future. Keycloak will provide details regarding the removal date and recommended alternatives in due course. Users should plan to migrate to supported alternatives as they become available.
To protect your application, install express and add the Keycloak middleware to your Express app using keycloak.middleware().
Important: Proxy Configuration
If your app is behind a proxy (e.g., Nginx, ELB) that terminates SSL, you must set trust proxy to true in Express to ensure correct redirect URIs are generated.
const express = require('express');
const app = express();
// Required if running behind a proxy
app.set('trust proxy', true);
// Install Keycloak middleware
app.use(keycloak.middleware());
app.listen(3000);const express = require('express');
const app = express();
app.set('trust proxy', true);
app.use(keycloak.middleware());
app.listen(3000, function () {
console.log('App listening on port 3000');
});To begin using the adapter and see it in action, you should use the official quickstart repositories. The adapter is designed to make it simple to implement Node.js Connect-friendly applications that leverage Keycloak for authentication and authorization.
Visit the [Keycloak QuickStarts](https://github.com/keycloak/keycloak-quickstarts) for runnable examples.To use the adapter, first create a client in the Keycloak Admin Console. Download the configuration by selecting Action -> Download adapter config, choosing Keycloak OIDC JSON as the format. Save this as keycloak.json in your project root.
Then, initialize your project and add keycloak-connect to your dependencies:
mkdir myapp && cd myapp
npm init
npm install keycloak-connectBefore running the NodeJS example, you must have a running Keycloak instance with the required realm imported. You can start Keycloak using Docker or a standard installation.
Run the following command to start Keycloak with default admin credentials:
docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin jboss/keycloakExecute the standalone script from your Keycloak directory:
/<Path-To-Keycloak>/bin/standalone.shnodejs-example-realm.json file (provided in the repository).To build the adapter from source, ensure you have Node.js 8 or newer and Git installed. Clone the repository, navigate to the directory, and run npm install to install the adapter and its dependencies.
# Check prerequisites
node --version
git --version
# Clone and build
git clone https://github.com/keycloak/keycloak-nodejs-connect.git
cd keycloak-nodejs-connect
npm installYou can execute the test suite using npm test to run all tests, or use tape to run a specific test file. The main tests are located in the test folder.
To run all tests:
npm testTo run a specific test file (e.g., test/grant-manager-spec.js):
tape test/grant-manager-spec.jsTo run the example project locally, follow these steps to link the keycloak-connect library and start the application:
example directory, link the parent directory containing the keycloak-connect source code: npm link ../
2. **Install dependencies**: Install the required Node.js packages:
```bash
npm install npm start
4. **Access the app**: Open your browser at `http://localhost:3000/`. You can log in using the following credentials:
- **Username**: `user`
- **Password**: `password`
npm link ../
npm install
npm startBefore submitting a pull request, run the linting command to ensure code formatting meets project expectations.
npm run lintWhen writing new tests, follow the existing patterns established in the test folder.
Before running integration tests, you must ensure a Keycloak server is running. Use the following command to start the server:
npm run server:startTo use the Keycloak adapter, create a new instance of Keycloak. You can provide a config object for adapter-specific settings and an optional keycloakConfig object for Keycloak-specific settings. If keycloakConfig is not provided, the adapter will automatically attempt to load configuration from a keycloak.json file located alongside your application.
config (Object):
store: A custom session-store implementation. Using a session-based store is recommended for better control from the Keycloak console.cookies: Set to true to use cookies as your authentication store. Note: This requires a cookie parser (like cookie-parser in Express.js) to be present in your middleware stack. You cannot use both store and cookies simultaneously.scope: A custom scope string.idpHint: An Identity Provider hint.keycloakConfig (Object):
keycloak.json).// Example using default keycloak.json
var keycloak = new Keycloak();
// Example with custom configuration
var keycloak = new Keycloak({
cookies: true,
scope: 'email profile'
}, {
realmUrl: 'https://keycloak.example.com/auth',
clientId: 'my-app'
});