0
# Keycloak JavaScript Client
1

2
The Keycloak JavaScript client library provides seamless integration between web applications and Keycloak authentication servers. It supports OpenID Connect, Single Sign-On (SSO), OAuth2 authentication flows, and fine-grained authorization through User-Managed Access (UMA) policies.
3

4
## Package Information
5

6
- **Package Name**: keycloak-js
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install keycloak-js`
10

11
## Core Imports
12

13
```javascript
14
import Keycloak from "keycloak-js";
15
import KeycloakAuthorization from "keycloak-js/keycloak-authz";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const Keycloak = require("keycloak-js");
22
const KeycloakAuthorization = require("keycloak-js/keycloak-authz");
23
```
24

25
## Basic Usage
26

27
```javascript
28
import Keycloak from "keycloak-js";
29

30
// Initialize Keycloak instance
31
const keycloak = new Keycloak({
32
  url: "http://keycloak-server",
33
  realm: "my-realm", 
34
  clientId: "my-app"
35
});
36

37
// Initialize authentication
38
async function initAuth() {
39
  try {
40
    const authenticated = await keycloak.init({
41
      onLoad: "check-sso",
42
      pkceMethod: "S256",
43
      responseMode: "query"
44
    });
45
    
46
    if (authenticated) {
47
      console.log("User is authenticated");
48
      console.log("Access token:", keycloak.token);
49
    } else {
50
      console.log("User is not authenticated");
51
    }
52
  } catch (error) {
53
    console.error("Authentication initialization failed:", error);
54
  }
55
}
56

57
// Start authentication process
58
initAuth();
59
```
60

61
## Architecture
62

63
The Keycloak JavaScript client is built around several key components:
64

65
- **Authentication Core**: Main `Keycloak` class handling login, logout, and token management
66
- **Token Management**: Automatic token refresh, validation, and storage
67
- **Event System**: Callback-based architecture for authentication lifecycle events
68
- **Authorization Extension**: Separate `KeycloakAuthorization` class for UMA and policy enforcement
69
- **Multi-Protocol Support**: OpenID Connect, OAuth2, and OAuth flows
70
- **Browser Integration**: Seamless integration with browser authentication flows
71

72
## Capabilities
73

74
### Authentication and Session Management
75

76
Core authentication functionality including login, logout, token management, and session handling. Essential for any application requiring user authentication through Keycloak.
77

78
```javascript { .api }
79
/**
80
 * Main Keycloak authentication client
81
 */
82
class Keycloak {
83
  constructor(config?: KeycloakConfig);
84
  
85
  // Authentication methods
86
  init(options?: KeycloakInitOptions): Promise<boolean>;
87
  login(options?: KeycloakLoginOptions): Promise<void>;
88
  logout(options?: KeycloakLogoutOptions): Promise<void>;
89
  register(options?: KeycloakRegisterOptions): Promise<void>;
90
  accountManagement(options?: KeycloakAccountOptions): Promise<void>;
91
  
92
  // Token management
93
  updateToken(minValidity?: number): Promise<boolean>;
94
  isTokenExpired(minValidity?: number): boolean;
95
  clearToken(): void;
96
  
97
  // User information
98
  loadUserInfo(): Promise<any>;
99
  loadUserProfile(): Promise<KeycloakProfile>;
100
  
101
  // Role checking
102
  hasRealmRole(role: string): boolean;
103
  hasResourceRole(role: string, resource?: string): boolean;
104
  
105
  // URL generation
106
  createLoginUrl(options?: KeycloakLoginOptions): string;
107
  createLogoutUrl(options?: KeycloakLogoutOptions): string;
108
  createRegisterUrl(options?: KeycloakRegisterOptions): string;
109
  createAccountUrl(options?: KeycloakAccountOptions): string;
110
  
111
  // Properties
112
  authenticated?: boolean;
113
  token?: string;
114
  refreshToken?: string;
115
  idToken?: string;
116
  tokenParsed?: KeycloakTokenParsed;
117
  idTokenParsed?: KeycloakTokenParsed;
118
  subject?: string;
119
  realmAccess?: KeycloakRoles;
120
  resourceAccess?: KeycloakResourceAccess;
121
  timeSkew?: number;
122
  
123
  // Event handlers
124
  onReady?: (authenticated: boolean) => void;
125
  onAuthSuccess?: () => void;
126
  onAuthError?: (errorData: KeycloakError) => void;
127
  onAuthRefreshSuccess?: () => void;
128
  onAuthRefreshError?: () => void;
129
  onAuthLogout?: () => void;
130
  onTokenExpired?: () => void;
131
}
132
```
133

134
[Authentication and Session Management](./authentication.md)
135

136
### Authorization and Policy Enforcement
137

138
User-Managed Access (UMA) and policy enforcement capabilities for fine-grained authorization. Enables applications to obtain permissions and enforce access control policies.
139

140
```javascript { .api }
141
/**
142
 * Authorization client for UMA and policy enforcement
143
 */
144
class KeycloakAuthorization {
145
  constructor(keycloak: Keycloak);
146
  
147
  init(): Promise<void>; // deprecated
148
  authorize(request?: AuthorizationRequest): Promise<string>;
149
  entitlement(resourceServerId: string, request?: AuthorizationRequest): Promise<string>;
150
  
151
  // Properties  
152
  rpt?: string;
153
  config?: { rpt_endpoint: string };
154
}
155
```
156

157
[Authorization and Policy Enforcement](./authorization.md)
158

159
## Core Types
160

161
```javascript { .api }
162
interface KeycloakConfig {
163
  url: string;
164
  realm: string;
165
  clientId: string;
166
}
167

168
interface KeycloakInitOptions {
169
  onLoad?: "login-required" | "check-sso";
170
  token?: string;
171
  refreshToken?: string;
172
  idToken?: string;
173
  checkLoginIframe?: boolean;
174
  checkLoginIframeInterval?: number;
175
  responseMode?: "query" | "fragment";
176
  redirectUri?: string;
177
  silentCheckSsoRedirectUri?: string;
178
  flow?: "standard" | "implicit" | "hybrid";
179
  scope?: string;
180
  timeSkew?: number;
181
  useNonce?: boolean;
182
  adapter?: "default" | "cordova" | "cordova-native";
183
  messageReceiveTimeout?: number;
184
  pkceMethod?: "S256";
185
  enableLogging?: boolean;
186
}
187

188
interface KeycloakLoginOptions {
189
  redirectUri?: string;
190
  scope?: string;
191
  locale?: string;
192
  idpHint?: string;
193
  loginHint?: string;
194
  action?: string;
195
}
196

197
interface KeycloakLogoutOptions {
198
  redirectUri?: string;
199
}
200

201
interface KeycloakRegisterOptions {
202
  redirectUri?: string;
203
  locale?: string;
204
}
205

206
interface KeycloakAccountOptions {
207
  redirectUri?: string;
208
}
209

210
interface KeycloakProfile {
211
  id?: string;
212
  username?: string;
213
  email?: string;
214
  firstName?: string;
215
  lastName?: string;
216
  enabled?: boolean;
217
  emailVerified?: boolean;
218
  totp?: boolean;
219
  createdTimestamp?: number;
220
  attributes?: { [key: string]: string[] };
221
}
222

223
interface KeycloakTokenParsed {
224
  exp?: number;
225
  iat?: number;
226
  auth_time?: number;
227
  jti?: string;
228
  iss?: string;
229
  aud?: string | string[];
230
  sub?: string;
231
  typ?: string;
232
  azp?: string;
233
  session_state?: string;
234
  realm_access?: KeycloakRoles;
235
  resource_access?: KeycloakResourceAccess;
236
  [key: string]: any;
237
}
238

239
interface KeycloakRoles {
240
  roles: string[];
241
}
242

243
interface KeycloakResourceAccess {
244
  [key: string]: KeycloakRoles;
245
}
246

247
interface KeycloakError {
248
  error: string;
249
  error_description?: string;
250
}
251

252
interface AuthorizationRequest {
253
  ticket?: string;
254
  tickets?: string[];
255
  permissions?: ResourcePermission[];
256
  metadata?: AuthorizationMetadata;
257
  submit_request?: boolean;
258
  incrementalAuthorization?: boolean;
259
  submitterId?: string;
260
  claimToken?: string;
261
  claimTokenFormat?: string;
262
}
263

264
interface ResourcePermission {
265
  id?: string;
266
  name?: string;
267
  scopes?: string[];
268
}
269

270
interface AuthorizationMetadata {
271
  response_include_resource_name?: boolean;
272
  response_permissions_limit?: number;
273
}
274
```