Instructions

An integration client for Keycloak for Caris applications.

Installation

npm i @carisls/keycloak-client

Middleware

Adding of basic piece to handle user injection and redirections to retrieve user.

const keycloakClient = require('@carisls/keycloak-client');
app.use(keycloakClient.router({
  clientId: 'my-client'
  ssoUrl: process.env.SSO_URL,
  encPassword: process.env.ENC_PASSWORD
}));

Option | API Router | Description --- | --- | --- ssoUrl | ANY | Url to use as SSO server base url clientId | ANY | Client Id clientSecret | ANY | Client Secret (if enabled) api | N/A | If API Router we need to set this setting to true to prevent any redirections standard | N/A | Whether to use implicit (default) or a standard flow useCachedSession | N/A | Whether to use token caching (in case of large tokens) publicKey | ANY | Overriding a default public certificate (provided by SSO Server) publicKeyCache | ANY | Time in seconds when a fetched publicKey should expire encPassword | ANY | Setting encryption password for session cookie encPasswordSalt | ANY | Setting encryption password salt for session cookie encIterationCount | ANY | Setting encryption password number of hash iterations for session cookie paths.login | false | Overriding a default /login path to initiate login paths.sso | false | Overriding a default /sso path to receive user token paths.logout | false | Overriding a default /logout path to initiate logout paths.afterLogin | false | Overrides a default / path where to send user after a successful login paths.afterLogout | false | Overrides a default / path where to send user after a successful logout expOffset | false | When x-session cookie will expire (in seconds). Negative is earlier, positive later. Default is 0

NOTE: You can include publicKey option or not. If not, client will get it by following OpenID standard (.well-known).

NOTE: If it is API, we do not have "sending user to login" so we need to pass api: true to options.

Authorization

Adding middleware to authorize requests.

const authorize = keycloakClient.authorize;
app.use(authorize('my-app-role', [
  '/403.html',
  '/assets'
]));

Middleware authorize has three parameters:

No | Parameter Name | Required | Default | Description ---|---|---|---|--- 1 | roles | false | null | Needed roles to pass or null for all authenticated (one role string or array of strings) 2 | exceptions | false | [] | What paths to exclude. Matches exact url and from the start (/peter will match both /peter and /peterson and /peter/some-file.txt) 3 | redirectToLogin | false | true | If not set as false it will redirect user to /login?ReturnUrl={encodedUrl}. If set to false it will throw 401

Client Enpoints

Base Url for a realm:

https://{domain}/auth/realms/{realm}

Paths:

• POST /protocol/openid-connect/token (ValidateCredentials)

Base Url for a realm admin:

https://{domain}/auth/admin/realms/{realm}

Paths:

• GET /[email protected] (FindAUserByEmail)
• DELETE /users/{user.id} (DeleteUser)
• POST /users (CreateUser)
• PUT /users/{user.id}/reset-password (UpdateUser)

Base Url for the master realm:

https://{domain}/auth/realms/master

Paths:

• POST /protocol/openid-connect/token (GetAdminToken)