### Link and Run Keycloak NodeJS Connect Example

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/example/README.md

Commands to link the keycloak-connect library locally, install Node.js dependencies, and start the example application.

```shell
npm link ../
npm install
npm start
```

--------------------------------

### Start Keycloak Standard

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/example/README.md

Starts a Keycloak instance using the standard Keycloak distribution script.

```shell
/<Path-To-Keycloak>/bin/standalone.sh
```

--------------------------------

### Install Keycloak Node.js Adapter (Product)

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Adds the keycloak-connect package from a local tarball for product deployments.

```json
    "dependencies": {
        "keycloak-connect": "file:keycloak-connect-{version_nodejs_adapter}.tgz"
    }
```

--------------------------------

### Installing Dependencies

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/docs/building.md

Installs the Node.js adapter and its dependencies using npm. This command should be run after cloning the repository.

```bash
npm install
```

--------------------------------

### Start Keycloak with Docker

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/example/README.md

Starts a Keycloak instance using Docker. It exposes port 8080 and sets the admin username and password.

```bash
docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin jboss/keycloak
```

--------------------------------

### Install and Configure Express

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Provides steps to install Express using npm and require it in a Node.js project.

```bash
npm install express
```

```javascript
const express = require('express');
const app = express();
```

--------------------------------

### Start Express Server

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Code snippet to start an Express server listening on a specified port.

```javascript
app.listen(3000, function () {
    console.log('App listening on port 3000');
});
```

--------------------------------

### Start Keycloak Server

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/docs/tests-development.md

Starts the Keycloak server required for running integration tests. This command ensures the necessary backend services are available for testing.

```bash
npm run server:start
```

--------------------------------

### Install Keycloak Node.js Adapter (Community)

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Adds the keycloak-connect package to your project's dependencies for community deployments.

```json
    "dependencies": {
        "keycloak-connect": "{version_nodejs_adapter}"
    }
```

--------------------------------

### Guide Macro Definition

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/templates/guide.adoc

Defines a macro for creating documentation guides. It sets various attributes like title, summary, priority, and version, and includes conditional logic for preview features and relevant options.

```adoc
<#import "/templates/options.adoc" as opts>

<#macro guide title summary priority=999 deniedCategories="" includedOptions="" preview="" tileVisible="true" previewDiscussionLink="">
:guide-id: ${id}
:guide-title: ${title}
:guide-summary: ${summary}
:guide-priority: ${priority}
:guide-tile-visible: ${tileVisible}
:version: ${version}
:version_nodejs_adapter: ${version}

include::../attributes.adoc[]

[[${id}]]
= ${title}

ifeval::["${preview}" == "true"]
WARNING: This {section} is describing a feature which is currently in preview.
ifeval::["${previewDiscussionLink}" == ""]
Please provide your feedback while we’re continuing to work on this.
endif::[]
ifeval::["${previewDiscussionLink}" != ""]
Please provide your feedback by link:${previewDiscussionLink}[joining this discussion] while we’re continuing to work on this.
endif::[]
endif::[]

<#nested>

<#if includedOptions?has_content>
== Relevant options

<@opts.list options=ctx.options.getOptions(includedOptions, deniedCategories) anchor=false></@opts.list>
</#if>
</#macro>
```

--------------------------------

### Prerequisites Check

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/docs/building.md

Verifies that Node.js and Git are installed and meet the minimum version requirements for building the adapter.

```bash
node --version
git --version
```

--------------------------------

### Initialize Keycloak with Express.js

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Demonstrates basic initialization of the Keycloak adapter with Express.js using session memory store.

```javascript
    const session = require('express-session');
    const Keycloak = require('keycloak-connect');

    const memoryStore = new session.MemoryStore();
    const keycloak = new Keycloak({ store: memoryStore });

```

--------------------------------

### Basic Navigation Structure

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/example/view/index.html

This snippet defines the basic HTML structure for navigation within the NodeJS Keycloak example. It includes a list of links for login, protected resources, and logout.

```HTML
<ul>
  <li><a href="/login">Login</a></li>
  <li><a href="/protected/resource">Protected Resource</a></li>
  <li><a href="/logout">Logout</a></li>
</ul>
```

--------------------------------

### Git Rebase Command

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/CONTRIBUTING.md

Instructions on how to rebase a branch onto the main branch for integrating changes.

```git
git rebase main
```

--------------------------------

### Initialize Keycloak with Identity Provider Hint

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Demonstrates initializing the Keycloak middleware with an `idpHint` to redirect users to a specific identity provider.

```javascript
const keycloak = new Keycloak({ store: memoryStore, idpHint: myIdP }, kcConfig);
```

--------------------------------

### Securing Resources Based on URL Sections

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Provides an example of securing resources based on URL parameters by defining a custom protection function that checks for roles associated with URL segments.

```javascript
function protectBySection(token, request) {
  return token.hasRole( request.params.section );
}

app.get( '/:section/:page', keycloak.protect( protectBySection ), sectionHandler );
```

--------------------------------

### Pull Request Checklist

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/CONTRIBUTING.md

A checklist to ensure a pull request is well-formed and meets project standards for contribution.

```markdown
1. [Keycloak Dev Mailing List](https://groups.google.com/g/keycloak-dev)
2. An issue associated with the PR
3. One feature/change per PR
4. One commit per PR
5. PR rebased on `main` branch (`git rebase`, not `git pull`)
6. No changes to code not directly related to your PR
7. Includes test
8. Includes documentation
```

--------------------------------

### Integrate Keycloak Middleware with Express

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Demonstrates how to mount the Keycloak middleware into an Express application.

```javascript
app.use( keycloak.middleware() );
```

--------------------------------

### Configure Keycloak with a JavaScript Object

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Shows how to initialize the Keycloak adapter by providing a configuration object directly, bypassing the `keycloak.json` file.

```javascript
    const kcConfig = {
        clientId: 'myclient',
        bearerOnly: true,
        serverUrl: 'http://localhost:8080{kc_base_path}',
        realm: 'myrealm',
        realmPublicKey: 'MIIBIjANB...'
    };

    const keycloak = new Keycloak({ store: memoryStore }, kcConfig);

```

--------------------------------

### Layout Styling

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/example/view/index.html

This CSS snippet defines the layout for the navigation sidebar and the main content area, ensuring proper spacing and alignment.

```CSS
.nav {
  float: left;
  width: 250px;
}

.content {
  margin-left: 270px;
}
```

--------------------------------

### Protect Resource with Role from Different Application

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Demonstrates how to protect a resource with an application role defined in a different Keycloak client.

```javascript
app.get( '/extra-special', keycloak.protect('other-app:special'), extraSpecialHandler );
```

--------------------------------

### Resource-Based Authorization with Keycloak Enforcer

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Utilizes `keycloak.enforcer` for fine-grained, resource-based authorization based on policies defined in Keycloak.

```javascript
app.get('/apis/me', keycloak.enforcer('user:profile'), userProfileHandler);
```

--------------------------------

### Squashing Commits with Git Rebase

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/CONTRIBUTING.md

Command to squash multiple commits into a single commit for a cleaner PR history.

```git
git rebase -i HEAD~X
```

--------------------------------

### Protect Resource with Realm Role

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Secures a resource requiring a specific realm role assigned to the user.

```javascript
app.get( '/admin', keycloak.protect( 'realm:admin' ), adminHandler );
```

--------------------------------

### Protect Resource with Application Role

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Secures a resource requiring a specific application role for the current Keycloak client.

```javascript
app.get( '/special', keycloak.protect('special'), specialHandler );
```

--------------------------------

### Pushing Custom Claims for Policy Decisions

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Illustrates how to push custom claims to the Keycloak server to be used in policy decisions by defining a `claims` function within the `keycloak.enforcer` configuration.

```javascript
app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], {
    claims: function(request) {
      return {
        "http.uri": ["/protected/resource"],
        "user.agent": // get user agent  from request
      }
    }
  }), function (req, res) {
    // access granted
});
```

--------------------------------

### Code Block Styling

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/example/view/index.html

This CSS snippet styles preformatted text blocks, commonly used for displaying code. It ensures readability with word wrapping and a distinct background and border.

```CSS
pre {
  word-wrap: break-word;
  white-space: pre-wrap;
  background-color: #ddd;
  border: 1px solid #ccc;
  padding: 20px;
}
```

--------------------------------

### Node.js Adapter Upgrade Procedure

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

This procedure outlines the steps required to upgrade the Keycloak Node.js adapter. It involves downloading the new adapter archive, removing the old files, and updating the project's package.json.

```text
1. Download the new adapter archive.
2. Remove the existing Node.js adapter directory
3. Unzip the updated file into its place
4. Change the dependency for keycloak-connect in the package.json of your application
```

--------------------------------

### Configure Web Session Store for Keycloak

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Shows how to configure `express-session` and pass the session store to the Keycloak middleware for managing server-side authentication state.

```javascript
const session = require('express-session');
const memoryStore = new session.MemoryStore();

// Configure session
app.use(
  session({
    secret: 'mySecret',
    resave: false,
    saveUninitialized: true,
    store: memoryStore,
  })
);

const keycloak = new Keycloak({ store: memoryStore });
```

--------------------------------

### Protect Resource with Simple Authentication

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Enforces authentication for a route using the `keycloak.protect()` method without any specific roles or permissions.

```javascript
app.get( '/complain', keycloak.protect(), complaintHandler );
```

--------------------------------

### Accessing Permissions with Token Response Mode

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Shows how to access user permissions from the access token when `keycloak.enforcer` is used with `response_mode: 'token'`.

```javascript
app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), function (req, res) {
    const token = req.kauth.grant.access_token.content;
    const permissions = token.authorization ? token.authorization.permissions : undefined;

    // show user profile
});
```

--------------------------------

### Resource-Based Authorization with Token Response Mode

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Configures the `keycloak.enforcer` to use `token` as the `response_mode`, obtaining permissions from a new access token.

```javascript
app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), userProfileHandler);
```

--------------------------------

### CSS Styling for Navigation

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/example/view/index.html

This CSS snippet styles the navigation list, removing default list styles and setting up a clean, block-based layout for links. It also includes hover effects for better user interaction.

```CSS
ul {
  list-style-type: none;
  margin: 0;
  padding: 0;
  background-color: #f1f1f1;
}

li a {
  display: block;
  color: #000;
  padding: 8px 0 8px 16px;
  text-decoration: none;
}

/* Change the link color on hover */
li a:hover {
  background-color: #555;
  color: white;
}
```

--------------------------------

### Customizing Logout URL

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Shows how to configure a custom URL for user-triggered logout by specifying the `logout` option in the `keycloak.middleware()` call.

```javascript
app.use( keycloak.middleware( { logout: '/logoff' } ));
```

--------------------------------

### Configure Express to Trust Proxy

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Shows how to configure Express to trust the proxy when running behind one, which is important for correct redirect URI generation.

```javascript
const app = express();

app.set( 'trust proxy', true );

app.use( keycloak.middleware() );
```

--------------------------------

### Add Custom Scope to Keycloak Login URL

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Illustrates how to add a custom scope value, such as `offline_access`, to the Keycloak login request.

```javascript
const keycloak = new Keycloak({ scope: 'offline_access' });
```

--------------------------------

### Specifying Resource Server Client

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Shows how to configure the `keycloak.enforcer` to use a specific client ID for resource server authentication when the application acts as both a public client and a resource server.

```javascript
keycloak.enforcer('user:profile', {resource_server_id: 'my-apiserver'})
```

--------------------------------

### Configuring Admin Callback URL

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Explains how to set a custom base URL for Keycloak admin callbacks (e.g., for single session logout) using the `admin` parameter in the `keycloak.middleware()` configuration.

```javascript
app.use( keycloak.middleware( { admin: '/callbacks' } );
```

--------------------------------

### Overriding redirectToLogin for API Requests

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Demonstrates how to override the default `redirectToLogin` behavior to return an HTTP 401 for unauthenticated API requests instead of redirecting to the login page.

```javascript
Keycloak.prototype.redirectToLogin = function(req) {
    const apiReqMatcher = /\/api\//i;
    return !apiReqMatcher.test(req.originalUrl || req.url);
};
```

--------------------------------

### Enforcing Permissions with Response Mode

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/securing-apps/nodejs-adapter.adoc

Demonstrates how to use the `keycloak.enforcer` method to check permissions and retrieve granted permissions without issuing a new access token when `response_mode` is set to `permissions`.

```javascript
app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'permissions'}), function (req, res) {
    const permissions = req.permissions;

    // show user profile
});
```

--------------------------------

### Cloning the Repository

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/docs/building.md

Clones the Keycloak Node.js Connect adapter repository from GitHub and navigates into the project directory.

```bash
git clone https://github.com/keycloak/keycloak-nodejs-connect.git
cd keycloak-nodejs-connect
```

--------------------------------

### Keycloak Node.js Connect Options Reference

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/templates/options.adoc

Provides a comprehensive reference for configuring the Keycloak Node.js Connect adapter. It details each option, its purpose, how it can be set via CLI or environment variables, its expected values, default settings, and any deprecation warnings.

```APIDOC
Options Reference:

This table outlines the configuration options for the Keycloak Node.js Connect adapter.

|===
| Option Key | Value

| ``url``
[.options-description]#The Keycloak server URL.
--
*CLI:* `--keycloak-url <url>`
*Env:* `KEYCLOAK_URL`
--
| `+http://localhost:8080/auth+` (default)

| ``realm``
[.options-description]#The realm name.
--
*CLI:* `--keycloak-realm <realm>`
*Env:* `KEYCLOAK_REALM`
--
| `+master+` (default)

| ``client_id``
[.options-description]#The client ID.
--
*CLI:* `--keycloak-client-id <client-id>`
*Env:* `KEYCLOAK_CLIENT_ID`
--
| (required)

| ``client_secret``
[.options-description]#The client secret.
--
*CLI:* `--keycloak-client-secret <client-secret>`
*Env:* `KEYCLOAK_CLIENT_SECRET`
--
| (required if client_secret_post is not used)

| ``bearer-only``
[.options-description]#If set to true, the adapter will only act as a bearer-only client.
--
*CLI:* `--keycloak-bearer-only <true|false>`
*Env:* `KEYCLOAK_BEARER_ONLY`
--
| `+false+` (default)

| ``ssl-required``
[.options-description]#Specifies if SSL is required. Possible values: `external`, `all`, `none`.
--
*CLI:* `--keycloak-ssl-required <external|all|none>`
*Env:* `KEYCLOAK_SSL_REQUIRED`
--
| `+external+` (default)

| ``resource-server-id``
[.options-description]#The resource server ID.
--
*CLI:* `--keycloak-resource-server-id <resource-server-id>`
*Env:* `KEYCLOAK_RESOURCE_SERVER_ID`
--
| (required if using resource server)

| ``public-client``
[.options-description]#If set to true, the client is public (no secret required).
--
*CLI:* `--keycloak-public-client <true|false>`
*Env:* `KEYCLOAK_PUBLIC_CLIENT`
--
| `+false+` (default)

| ``confidential-port``
[.options-description]#The port for confidential clients.
--
*CLI:* `--keycloak-confidential-port <port>`
*Env:* `KEYCLOAK_CONFIDENTIAL_PORT`
--
| `+8443+` (default)

| ``enable-cors``
[.options-description]#If set to true, CORS headers will be added to responses.
--
*CLI:* `--keycloak-enable-cors <true|false>`
*Env:* `KEYCLOAK_ENABLE_CORS`
--
| `+false+` (default)

| ``cors-max-age``
[.options-description]#The maximum age for CORS preflight requests.
--
*CLI:* `--keycloak-cors-max-age <seconds>`
*Env:* `KEYCLOAK_CORS_MAX_AGE`
--
| `+3600+` (default)

| ``cors-allowed-methods``
[.options-description]#A comma-separated list of allowed HTTP methods for CORS.
--
*CLI:* `--keycloak-cors-allowed-methods <methods>`
*Env:* `KEYCLOAK_CORS_ALLOWED_METHODS`
--
| `+GET,POST,PUT,DELETE,OPTIONS+` (default)

| ``cors-allowed-headers``
[.options-description]#A comma-separated list of allowed HTTP headers for CORS.
--
*CLI:* `--keycloak-cors-allowed-headers <headers>`
*Env:* `KEYCLOAK_CORS_ALLOWED_HEADERS`
--
| `+content-type,accept,authorization+` (default)

| ``cors-exposed-headers``
[.options-description]#A comma-separated list of exposed HTTP headers for CORS.
--
*CLI:* `--keycloak-cors-exposed-headers <headers>`
*Env:* `KEYCLOAK_CORS_EXPOSED_HEADERS`
--
| `+content-type,accept,authorization+` (default)

| ``token-store``
[.options-description]#The token store to use. Possible values: `session`, `cookie`, `default`.
--
*CLI:* `--keycloak-token-store <session|cookie|default>`
*Env:* `KEYCLOAK_TOKEN_STORE`
--
| `+session+` (default)

| ``token-max-lifespan``
[.options-description]#The maximum lifespan of the token in seconds.
--
*CLI:* `--keycloak-token-max-lifespan <seconds>`
*Env:* `KEYCLOAK_TOKEN_MAX_LIFESPAN`
--
| `+3600+` (default)

| ``token-refresh-interval``
[.options-description]#The interval in seconds to refresh the token.
--
*CLI:* `--keycloak-token-refresh-interval <seconds>`
*Env:* `KEYCLOAK_TOKEN_REFRESH_INTERVAL`
--
| `+300+` (default)

| ``bearer-only``
[.options-description]#If set to true, the adapter will only act as a bearer-only client.
--
*CLI:* `--keycloak-bearer-only <true|false>`
*Env:* `KEYCLOAK_BEARER_ONLY`
--
| `+false+` (default)

| ``realm-public-key``
[.options-description]#The realm's public key for verifying JWTs.
--
*CLI:* `--keycloak-realm-public-key <key>`
*Env:* `KEYCLOAK_REALM_PUBLIC_KEY`
--
| (required if not using introspection)

| ``use-resource-role-mappings``
[.options-description]#If set to true, resource role mappings will be used.
--
*CLI:* `--keycloak-use-resource-role-mappings <true|false>`
*Env:* `KEYCLOAK_USE_RESOURCE_ROLE_MAPPINGS`
--
| `+false+` (default)

| ``verify-token-audience``
[.options-description]#If set to true, the token audience will be verified.
--
*CLI:* `--keycloak-verify-token-audience <true|false>`
*Env:* `KEYCLOAK_VERIFY_TOKEN_AUDIENCE`
--
| `+false+` (default)

| ``audience``
[.options-description]#The audience to verify in the token.
--
*CLI:* `--keycloak-audience <audience>`
*Env:* `KEYCLOAK_AUDIENCE`
--
| (required if verify-token-audience is true)

| ``credentials-key``
[.options-description]#The credentials key for client authentication.
--
*CLI:* `--keycloak-credentials-key <key>`
*Env:* `KEYCLOAK_CREDENTIALS_KEY`
--
| (required for client credentials grant)

| ``credentials-secret``
[.options-description]#The credentials secret for client authentication.
--
*CLI:* `--keycloak-credentials-secret <secret>`
*Env:* `KEYCLOAK_CREDENTIALS_SECRET`
--
| (required for client credentials grant)

| ``credentials-grant-type``
[.options-description]#The grant type for client authentication. Possible values: `client_credentials`, `password`.
--
*CLI:* `--keycloak-credentials-grant-type <grant-type>`
*Env:* `KEYCLOAK_CREDENTIALS_GRANT_TYPE`
--
| `+client_credentials+` (default)

| ``credentials-username``
[.options-description]#The username for password grant type.
--
*CLI:* `--keycloak-credentials-username <username>`
*Env:* `KEYCLOAK_CREDENTIALS_USERNAME`
--
| (required for password grant type)

| ``credentials-password``
[.options-description]#The password for password grant type.
--
*CLI:* `--keycloak-credentials-password <password>`
*Env:* `KEYCLOAK_CREDENTIALS_PASSWORD`
--
| (required for password grant type)

| ``token-exchange``
[.options-description]#If set to true, token exchange will be enabled.
--
*CLI:* `--keycloak-token-exchange <true|false>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE`
--
| `+false+` (default)

| ``token-exchange-audience``
[.options-description]#The audience for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience <audience>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE`
--
| (required if token-exchange is true)

| ``token-exchange-client-id``
[.options-description]#The client ID for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-id <client-id>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_ID`
--
| (required if token-exchange is true)

| ``token-exchange-client-secret``
[.options-description]#The client secret for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-secret <client-secret>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_SECRET`
--
| (required if token-exchange is true)

| ``token-exchange-grant-type``
[.options-description]#The grant type for token exchange. Possible values: `urn:ietf:params:oauth:grant-type:token-exchange`.
--
*CLI:* `--keycloak-token-exchange-grant-type <grant-type>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_GRANT_TYPE`
--
| `+urn:ietf:params:oauth:grant-type:token-exchange+` (default)

| ``token-exchange-requested-token-type``
[.options-description]#The requested token type for token exchange.
--
*CLI:* `--keycloak-token-exchange-requested-token-type <token-type>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_REQUESTED_TOKEN_TYPE`
--
| `+access_token+` (default)

| ``token-exchange-subject-token``
[.options-description]#The subject token for token exchange.
--
*CLI:* `--keycloak-token-exchange-subject-token <token>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_SUBJECT_TOKEN`
--
| (required for token exchange)

| ``token-exchange-actor-token``
[.options-description]#The actor token for token exchange.
--
*CLI:* `--keycloak-token-exchange-actor-token <token>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_ACTOR_TOKEN`
--
| (optional for token exchange)

| ``token-exchange-requested-issuer``
[.options-description]#The requested issuer for token exchange.
--
*CLI:* `--keycloak-token-exchange-requested-issuer <issuer>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_REQUESTED_ISSUER`
--
| (optional for token exchange)

| ``token-exchange-audience-rewrite``
[.options-description]#If set to true, the audience will be rewritten for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite <true|false>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE`
--
| `+false+` (default)

| ``token-exchange-audience-rewrite-target``
[.options-description]#The target audience for token exchange audience rewrite.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target <audience>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET`
--
| (required if token-exchange-audience-rewrite is true)

| ``token-exchange-client-claim-name``
[.options-description]#The client claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_CLAIM_NAME`
--
| `+azp+` (default)

| ``token-exchange-client-claim-value``
[.options-description]#The client claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-resource-claim-name``
[.options-description]#The resource claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_CLAIM_NAME`
--
| `+resource_access+` (default)

| ``token-exchange-resource-claim-value``
[.options-description]#The resource claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-scope-claim-name``
[.options-description]#The scope claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-scope-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_SCOPE_CLAIM_NAME`
--
| `+scope+` (default)

| ``token-exchange-scope-claim-value``
[.options-description]#The scope claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-scope-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_SCOPE_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-realm-claim-name``
[.options-description]#The realm claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-realm-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_REALM_CLAIM_NAME`
--
| `+realm_access+` (default)

| ``token-exchange-realm-claim-value``
[.options-description]#The realm claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-realm-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_REALM_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-roles-claim-name``
[.options-description]#The roles claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-roles-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_ROLES_CLAIM_NAME`
--
| `+roles+` (default)

| ``token-exchange-roles-claim-value``
[.options-description]#The roles claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-roles-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_ROLES_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-client-roles-claim-name``
[.options-description]#The client roles claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-roles-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_ROLES_CLAIM_NAME`
--
| `+client_roles+` (default)

| ``token-exchange-client-roles-claim-value``
[.options-description]#The client roles claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-roles-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_ROLES_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-realm-roles-claim-name``
[.options-description]#The realm roles claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-realm-roles-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_REALM_ROLES_CLAIM_NAME`
--
| `+realm_roles+` (default)

| ``token-exchange-realm-roles-claim-value``
[.options-description]#The realm roles claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-realm-roles-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_REALM_ROLES_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-resource-roles-claim-name``
[.options-description]#The resource roles claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-roles-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_ROLES_CLAIM_NAME`
--
| `+resource_roles+` (default)

| ``token-exchange-resource-roles-claim-value``
[.options-description]#The resource roles claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-roles-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_ROLES_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-resource-id``
[.options-description]#The resource ID for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-id <resource-id>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_ID`
--
| (optional for token exchange)

| ``token-exchange-resource-scopes``
[.options-description]#The resource scopes for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-scopes <scopes>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_SCOPES`
--
| (optional for token exchange)

| ``token-exchange-resource-owner``
[.options-description]#The resource owner for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-owner <owner>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_OWNER`
--
| (optional for token exchange)

| ``token-exchange-client-id-claim-name``
[.options-description]#The client ID claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-id-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_ID_CLAIM_NAME`
--
| `+azp+` (default)

| ``token-exchange-client-id-claim-value``
[.options-description]#The client ID claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-id-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_ID_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-client-name-claim-name``
[.options-description]#The client name claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-name-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_NAME_CLAIM_NAME`
--
| `+azp_name+` (default)

| ``token-exchange-client-name-claim-value``
[.options-description]#The client name claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-name-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_NAME_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-client-realm-claim-name``
[.options-description]#The client realm claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-realm-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_REALM_CLAIM_NAME`
--
| `+azp_realm+` (default)

| ``token-exchange-client-realm-claim-value``
[.options-description]#The client realm claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-realm-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_REALM_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-client-roles-claim-name``
[.options-description]#The client roles claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-roles-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_ROLES_CLAIM_NAME`
--
| `+client_roles+` (default)

| ``token-exchange-client-roles-claim-value``
[.options-description]#The client roles claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-client-roles-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_CLIENT_ROLES_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-resource-roles-claim-name``
[.options-description]#The resource roles claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-roles-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_ROLES_CLAIM_NAME`
--
| `+resource_roles+` (default)

| ``token-exchange-resource-roles-claim-value``
[.options-description]#The resource roles claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-roles-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_ROLES_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-resource-id-claim-name``
[.options-description]#The resource ID claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-id-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_ID_CLAIM_NAME`
--
| `+resource_id+` (default)

| ``token-exchange-resource-id-claim-value``
[.options-description]#The resource ID claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-id-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_ID_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-resource-scopes-claim-name``
[.options-description]#The resource scopes claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-scopes-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_SCOPES_CLAIM_NAME`
--
| `+resource_scopes+` (default)

| ``token-exchange-resource-scopes-claim-value``
[.options-description]#The resource scopes claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-scopes-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_SCOPES_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-resource-owner-claim-name``
[.options-description]#The resource owner claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-owner-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_OWNER_CLAIM_NAME`
--
| `+resource_owner+` (default)

| ``token-exchange-resource-owner-claim-value``
[.options-description]#The resource owner claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-resource-owner-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_RESOURCE_OWNER_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-audience-rewrite-target-claim-name``
[.options-description]#The audience rewrite target claim name for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-name <claim-name>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_NAME`
--
| `+audience+` (default)

| ``token-exchange-audience-rewrite-target-claim-value``
[.options-description]#The audience rewrite target claim value for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value <claim-value>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE`
--
| (optional for token exchange)

| ``token-exchange-audience-rewrite-target-claim-type``
[.options-description]#The audience rewrite target claim type for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-type <claim-type>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_TYPE`
--
| `+string+` (default)

| ``token-exchange-audience-rewrite-target-claim-value-type``
[.options-description]#The audience rewrite target claim value type for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-type <value-type>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_TYPE`
--
| `+string+` (default)

| ``token-exchange-audience-rewrite-target-claim-value-format``
[.options-description]#The audience rewrite target claim value format for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-format <value-format>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_FORMAT`
--
| `+json+` (default)

| ``token-exchange-audience-rewrite-target-claim-value-delimiter``
[.options-description]#The audience rewrite target claim value delimiter for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-delimiter <delimiter>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_DELIMITER`
--
| `,` (default)

| ``token-exchange-audience-rewrite-target-claim-value-index``
[.options-description]#The audience rewrite target claim value index for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-index <index>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_INDEX`
--
| `+0+` (default)

| ``token-exchange-audience-rewrite-target-claim-value-separator``
[.options-description]#The audience rewrite target claim value separator for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-separator <separator>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_SEPARATOR`
--
| `+|+` (default)

| ``token-exchange-audience-rewrite-target-claim-value-prefix``
[.options-description]#The audience rewrite target claim value prefix for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-prefix <prefix>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_PREFIX`
--
| `` (default)

| ``token-exchange-audience-rewrite-target-claim-value-suffix``
[.options-description]#The audience rewrite target claim value suffix for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-suffix <suffix>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_SUFFIX`
--
| `` (default)

| ``token-exchange-audience-rewrite-target-claim-value-transform``
[.options-description]#The audience rewrite target claim value transform for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-transform <transform>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_TRANSFORM`
--
| `+lowercase+` (default)

| ``token-exchange-audience-rewrite-target-claim-value-transform-args``
[.options-description]#The audience rewrite target claim value transform arguments for token exchange.
--
*CLI:* `--keycloak-token-exchange-audience-rewrite-target-claim-value-transform-args <args>`
*Env:* `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE_REWRITE_TARGET_CLAIM_VALUE_TRANSFORM_
```

--------------------------------

### Run All Tests

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/docs/tests-development.md

Executes all integration and unit tests within the project. This is the primary command for verifying the overall health of the codebase.

```bash
npm test
```

--------------------------------

### Code Linting

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/docs/building.md

Runs the code style checks for the Node.js adapter. This command should be executed before submitting any pull requests to ensure code quality.

```bash
npm run lint
```

--------------------------------

### Conditional Macros for Product/Community

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/guides/templates/profile.adoc

These macros allow for conditional content inclusion based on whether the project is a product version or a community version. They are useful for tailoring documentation or build configurations.

```asciidoc
<#macro ifProduct>
ifeval::[{project_product} == true]
<#nested>
endif::[]
</#macro>

<#macro ifCommunity>
ifeval::[{project_product} != true]
<#nested>
endif::[]
</#macro>
```

--------------------------------

### Run Specific Tests

Source: https://github.com/keycloak/keycloak-nodejs-connect/blob/main/docs/tests-development.md

Executes a specific test file using the Tape test runner. This is useful for focused testing during development or debugging.

```bash
tape test/grant-manager-spec.js
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.