UNPKG

21.4 kBTypeScriptView Raw
1import * as http from "http";
2
3
4/**
5 * Describes the available logging levels.
6 * ERROR: 0,
7 * WARN: 1,
8 * INFO: 2,
9 * VERBOSE: 3
10 * @type {number}
11 */
12export type LoggingLevel = 0 | 1 | 2 | 3;
13
14/**
15 * @callback LoggingCallback
16 * @memberOf Logging
17 * @param {LoggingLevel} level The level of this log entry.
18 * @param {string} message The text content of the log entry.
19 * @param {Error} [error] An Error object if this is an {@link Logging.LOGGING_LEVEL.ERROR|ERROR} level log entry.
20 */
21type LoggingCallback = (level: LoggingLevel, message: string, error?: Error) => void;
22
23/**
24 * @typedef LoggingOptions
25 * @memberOf Logging
26 * @property {LoggingCallback} [log] The function to call when ADAL generates a log entry.
27 * @property {LoggingLevel} [level] The maximum level of log entries to generate.
28 * @property {boolean} [loggingWithPII] This value indicts if personal identity related information such as token and claims should be logged. The default value is false.
29 */
30interface LoggingOptions {
31 log?: LoggingCallback;
32 level?: LoggingLevel;
33 loggingWithPII?: boolean;
34}
35
36export class Logging {
37 /**
38 * @property {LoggingLevel} LOGGING_LEVEL Provides information about the logging levels.
39 * ERROR: 0,
40 * WARN: 1,
41 * INFO: 2,
42 * VERBOSE: 3
43 */
44 static LOGGING_LEVEL: LoggingLevel;
45 /**
46 * Sets global logging options for ADAL.
47 * @param {LoggingOptions} options
48 */
49 static setLoggingOptions(options: LoggingOptions): void;
50 /**
51 * Get's the current global logging options.
52 * @return {LoggingOptions}
53 */
54 static getLoggingOptions(): LoggingOptions;
55}
56
57export function setGlobalADALOptions(): any; // TODO
58
59export function getGlobalADALOptions(): any; // TODO
60
61/**
62 * Contains tokens and metadata upon successful completion of an acquireToken call.
63 * @typedef TokenResponse
64 */
65export interface TokenResponse {
66 /**
67 * @property {string} tokenType The type of token returned. Example 'Bearer'.
68 */
69 tokenType: string;
70 /**
71 * @property {int} expiresIn The amount of time, in seconds, for which the token is valid.
72 */
73 expiresIn: number;
74 /**
75 * @property {Date} expiresOn The Date on which the access token expires.
76 */
77 expiresOn: Date | string;
78 /**
79 * @property {string} resource The resource for which the token was requested for. Example: 'https://management.core.windows.net/'.
80 */
81 resource: string;
82 /**
83 * @property {string} accessToken The returned access token.
84 */
85 accessToken: string;
86 /**
87 * @property {string} [refreshToken] A refresh token.
88 */
89 refreshToken?: string;
90
91 /**
92 * @property {Date} [createdOn] The date on which the access token was created.
93 */
94 createdOn?: Date | string;
95 /**
96 * @property {string} [userId] An id for the user. May be a displayable value if is_user_id_displayable is true.
97 */
98 userId?: string;
99 /**
100 * @property {boolean} [isUserIdDisplayable] Indicates whether the user_id property will be meaningful if displayed to a user.
101 */
102 isUserIdDisplayable?: boolean;
103 /**
104 * @property {string} [tenantId] The identifier of the tenant under which the access token was issued.
105 */
106 tenantId?: string;
107 /**
108 * @property {string} [oid] The object id of the user in the tenant
109 */
110 oid?: string;
111 /**
112 * @property {string} [givenName] The given name of the principal represented by the access token.
113 */
114 givenName?: string;
115 /**
116 * @property {string} [familyName] The family name of the principal represented by the access token.
117 */
118 familyName?: string;
119 /**
120 * @property {string} [identityProvider] Identifies the identity provider that issued the access token.
121 */
122 identityProvider?: string;
123
124 /**
125 * @property {any} [error] Provides information about error if any.
126 */
127 error?: any;
128
129 /**
130 * @property {any} [errorDescription] Short description about error if any.
131 */
132 errorDescription?: any;
133
134 [x: string]: any;
135}
136
137/**
138 * This will be returned in case the OAuth 2 service returns an error.
139 * @typedef ErrorResponse
140 * @property {string} [error] A server error.
141 * @property {string} [errorDescription] A description of the error returned.
142 */
143export interface ErrorResponse {
144 error: string;
145 errorDescription: string;
146}
147
148/**
149 * This is the callback that is passed to all acquireToken variants below.
150 * @callback AcquireTokenCallback
151 * @param {Error} [error] If the request fails this parameter will contain an Error object.
152 * @param {TokenResponse|ErrorResponse} [response] On a succesful request returns a {@link TokenResposne}.
153 */
154export type AcquireTokenCallback = (error: Error, response: TokenResponse | ErrorResponse) => void;
155
156/**
157 * This is the callback that is passed to all acquireUserCode method below.
158 * @callback AcquireTokenCallback
159 * @param {Error} [error] If the request fails this parameter will contain an Error object.
160 * @param {UserCodeInfo} [response] On a succesful request returns a {@link UserCodeInfo}.
161 */
162export type AcquireUserCodeCallback = (error: Error, response: UserCodeInfo) => void;
163
164/**
165 * This is an interface that can be implemented to provide custom token cache persistence.
166 * @public
167 * @interface TokenCache
168 */
169export interface TokenCache {
170 /**
171 * Removes a collection of entries from the cache in a single batch operation.
172 * @param {Array} entries An array of cache entries to remove.
173 * @param {Function} callback This function is called when the operation is complete. Any error is provided as the
174 * first parameter.
175 */
176 remove(entires: TokenResponse[], callback: { (err: Error, result: null): void }): void;
177
178 /**
179 * Adds a collection of entries to the cache in a single batch operation.
180 * @param {Array} entries An array of entries to add to the cache.
181 * @param {Function} callback This function is called when the operation is complete. Any error is provided as the
182 * first parameter.
183 */
184 add(entries: TokenResponse[], callback: { (err: Error, result: boolean): void }): void;
185
186 /**
187 * Finds all entries in the cache that match all of the passed in values.
188 * @param {object} query This object will be compared to each entry in the cache. Any entries that
189 * match all of the values in this object will be returned. All the values
190 * in the passed in object must match values in a potentialy returned object
191 * exactly. The returned object may have more values than the passed in query
192 * object. Please take a look at http://underscorejs.org/#where for an example
193 * on how to provide query.
194 * @param {TokenCacheFindCallback} callback
195 */
196 find(query: any, callback: { (err: Error, results: any[]): void }): void
197}
198
199/**
200 * @class MemoryCache - Describes the in memory implementation of the token cache.
201 */
202export class MemoryCache implements TokenCache {
203 /**
204 * @private
205 * @property {Array<TokenResponse>} _entries An array of entries in the TokenCache.
206 */
207 private _entries: TokenResponse[];
208
209 /**
210 * @constructor Creates an instance of MemoryCache
211 */
212 constructor();
213
214 /**
215 * Removes a collection of entries from the cache in a single batch operation.
216 * @param {Array} entries An array of cache entries to remove.
217 * @param {Function} callback This function is called when the operation is complete. Any error is provided as the
218 * first parameter.
219 */
220 remove(entires: TokenResponse[], callback: { (err: Error, result: null): void }): void;
221
222 /**
223 * Adds a collection of entries to the cache in a single batch operation.
224 * @param {Array} entries An array of entries to add to the cache.
225 * @param {Function} callback This function is called when the operation is complete. Any error is provided as the
226 * first parameter.
227 */
228 add(entries: TokenResponse[], callback: { (err: Error, result: boolean): void }): void;
229
230 /**
231 * Finds all entries in the cache that match all of the passed in values.
232 * @param {object} query This object will be compared to each entry in the cache. Any entries that
233 * match all of the values in this object will be returned. All the values
234 * in the passed in object must match values in a potentialy returned object
235 * exactly. The returned object may have more values than the passed in query
236 * object. Please take a look at http://underscorejs.org/#where for an example
237 * on how to provide query.
238 * @param {TokenCacheFindCallback} callback
239 */
240 find(query: any, callback: { (err: Error, results: any[]): void }): void
241}
242
243export class AuthenticationContext {
244 /**
245 * @property {string} authority A URL that identifies a token authority.
246 */
247 public authority: string;
248 /**
249 * @property {string} correlationId The correlation id that will be used for the next acquireToken request.
250 */
251 public correlationId: string;
252 /**
253 * @property {any} options Options that are applied to requests generated by this AuthenticationContext instance.
254 */
255 public options: any;
256 /**
257 * @property {TokenCache} cache The token cache used by this AuthenticationContext instance
258 */
259 public cache: TokenCache;
260
261 /**
262 * Creates a new AuthenticationContext object. By default the authority will be checked against
263 * a list of known Azure Active Directory authorities. If the authority is not recognized as
264 * one of these well known authorities then token acquisition will fail. This behavior can be
265 * turned off via the validateAuthority parameter below.
266 * @constructor
267 * @param {string} authority A URL that identifies a token authority.
268 * @param {bool} [validateAuthority] Turns authority validation on or off. This parameter default to true.
269 * @param {TokenCache} [cache] Sets the token cache used by this AuthenticationContext instance. If this parameter is not set
270 * then a default, in memory cache is used. The default in memory cache is global to the process and is
271 * shared by all AuthenticationContexts that are created with an empty cache parameter. To control the
272 * scope and lifetime of a cache you can either create a {@link MemoryCache} instance and pass it when
273 * constructing an AuthenticationContext or implement a custom {@link TokenCache} and pass that. Cache
274 * instances passed at AuthenticationContext construction time are only used by that instance of
275 * the AuthenticationContext and are not shared unless it has been manually passed during the
276 * construction of other AuthenticationContexts.
277 *
278 */
279 constructor(authority: string, validateAuthority?: boolean, cache?: TokenCache, aadApiVersion?: string);
280
281 /**
282 * Gets a token for a given resource.
283 * @param {string} resource A URI that identifies the resource for which the token is valid.
284 * @param {string} clientId The OAuth client id of the calling application.
285 * @param {string} clientSecret The OAuth client secret of the calling application.
286 * @param {AcquireTokenCallback} callback The callback function.
287 */
288 public acquireTokenWithClientCredentials(resource: string, clientId: string, clientSecret: string, callback: AcquireTokenCallback): void;
289
290 /**
291 * Gets a token for a given resource.
292 * @param {string} resource A URI that identifies the resource for which the token is valid.
293 * @param {string} username The username of the user on behalf this application is authenticating.
294 * @param {string} password The password of the user named in the username parameter.
295 * @param {string} clientId The OAuth client id of the calling application.
296 * @param {AcquireTokenCallback} callback The callback function.
297 */
298 public acquireTokenWithUsernamePassword(resource: string, username: string, password: string, clientId: string, callback: AcquireTokenCallback): void;
299
300 /**
301 * Gets a token for a given resource.
302 * @param {string} authorizationCode An authorization code returned from a client.
303 * @param {string} redirectUri The redirect uri that was used in the authorize call.
304 * @param {string} resource A URI that identifies the resource for which the token is valid.
305 * @param {string} clientId The OAuth client id of the calling application.
306 * @param {string} clientSecret The OAuth client secret of the calling application.
307 * @param {AcquireTokenCallback} callback The callback function.
308 */
309 public acquireTokenWithAuthorizationCode(authorizationCode: string, redirectUri: string, resource: string, clientId: string, clientSecret: string, callback: AcquireTokenCallback): void;
310
311 /**
312 * Gets a new access token via a previously issued refresh token.
313 * @param {string} refreshToken A refresh token returned in a tokne response from a previous invocation of acquireToken.
314 * @param {string} clientId The OAuth client id of the calling application.
315 * @param {string} [clientSecret] The OAuth client secret of the calling application. (Note: this parameter is a late addition.
316 * This parameter may be ommitted entirely so that applications built before this change will continue
317 * to work unchanged.)
318 * @param {string} resource The OAuth resource for which a token is being request. This parameter is optional and can be set to null.
319 * @param {AcquireTokenCallback} callback The callback function.
320 */
321 public acquireTokenWithRefreshToken(refreshToken: string, clientId: string, resource: string, callback: AcquireTokenCallback): void;
322 public acquireTokenWithRefreshToken(refreshToken: string, clientId: string, clientSecret: string, resource: string, callback: AcquireTokenCallback): void;
323
324 /**
325 * Gets a token for a given resource.
326 * @param {string} resource A URI that identifies the resource for which the token is valid.
327 * @param {string} userId The username of the user on behalf this application is authenticating.
328 * @param {string} clientId The OAuth client id of the calling application.
329 * @param {AcquireTokenCallback} callback The callback function.
330 */
331 public acquireToken(resource: string, userId: string, clientId: string, callback: AcquireTokenCallback): void
332
333 /**
334 * Gets the userCodeInfo which contains user_code, device_code for authenticating user on device.
335 * @param {string} resource A URI that identifies the resource for which the device_code and user_code is valid for.
336 * @param {string} clientId The OAuth client id of the calling application.
337 * @param {string} language The language code specifying how the message should be localized to.
338 * @param {AcquireUserCodeCallback} callback The callback function.
339 */
340 public acquireUserCode(resource: string, clientId: string, language: string, callback: AcquireUserCodeCallback): void;
341
342 /**
343 * Gets a new access token using via a certificate credential.
344 * @param {string} resource A URI that identifies the resource for which the token is valid.
345 * @param {string} clientId The OAuth client id of the calling application.
346 * @param {string} certificate A PEM encoded certificate private key.
347 * @param {string} thumbprint A hex encoded thumbprint of the certificate.
348 * @param {AcquireTokenCallback} callback The callback function.
349 */
350 public acquireTokenWithClientCertificate(resource: string, clientId: string, certificate: string, thumbprint: string, callback: AcquireTokenCallback): void;
351
352 /**
353 * Gets a new access token using via a device code.
354 * @note This method doesn't look up the cache, it only stores the returned token into cache. To look up cache before making a new request,
355 * please use acquireToken.
356 * @param {string} clientId The OAuth client id of the calling application.
357 * @param {object} userCodeInfo Contains device_code, retry interval, and expire time for the request for get the token.
358 * @param {AcquireTokenCallback} callback The callback function.
359 */
360 public acquireTokenWithDeviceCode(resource: string, clientId: string, userCodeInfo: UserCodeInfo, callback: AcquireTokenCallback): void;
361
362 /**
363 * Cancels the polling request to get token with device code.
364 * @param {object} userCodeInfo Contains device_code, retry interval, and expire time for the request for get the token.
365 * @param {AcquireTokenCallback} callback The callback function.
366 */
367 public cancelRequestToGetTokenWithDeviceCode(userCodeInfo: UserCodeInfo, callback: AcquireTokenCallback): void;
368}
369
370/**
371 * Describes the user code information that is provided by ADAL while authenticating via DeviceCode.
372 */
373export interface UserCodeInfo {
374 deviceCode: string;
375 expiresIn: number;
376 interval: number;
377 message: string;
378 userCode: string;
379 verificationUrl: string;
380 error?: any;
381 errorDescription?: any;
382 [x: string]: any;
383}
384
385/**
386 * Creates a new AuthenticationContext object. By default the authority will be checked against
387 * a list of known Azure Active Directory authorities. If the authority is not recognized as
388 * one of these well known authorities then token acquisition will fail. This behavior can be
389 * turned off via the validateAuthority parameter below.
390 * @function
391 * @param {string} authority A URL that identifies a token authority.
392 * @param {bool} [validateAuthority] Turns authority validation on or off. This parameter default to true.
393 * @returns {AuthenticationContext} A new authentication context.
394 */
395export function createAuthenticationContext(authority: string, validateAuthority?: boolean): AuthenticationContext;
396
397/**
398 * @class
399 * Describes the parameters that are parsed from an OAuth challenge in the www-authenticate header.
400 */
401export class AuthenticationParameters {
402 authorizationUri: string;
403 resource: string;
404 /**
405 * @constructor Provides an instance of AuthenticationParameters
406 * @param {string} authorizationUri The URI of an authority that can issues tokens for the resource that issued the challenge.
407 * @param {string} resource The resource for a which a token should be requested from the authority.
408 */
409 constructor(authorizationUri: string, resource: string);
410}
411
412/**
413 * Creates an {@link AuthenticationParameters} object from the contents of a
414 * www-authenticate header received from a HTTP 401 response from a resource server.
415 * @param {string} challenge The content fo the www-authenticate header.
416 * @return {AuthenticationParameters} An AuthenticationParameters object containing the parsed values from the header.
417 */
418export function createAuthenticationParametersFromHeader(challenge: string): AuthenticationParameters;
419
420/**
421 * Create an {@link AuthenticationParameters} object from a node http.IncomingMessage
422 * object that was created as a result of a request to a resource server. This function
423 * expects the response to contain a HTTP 401 error code with a www-authenticate
424 * header.
425 * @param {http.IncomingMessage} response A response from a http request to a resource server.
426 * @return {AuthenticationParameters}
427 */
428export function createAuthenticationParametersFromResponse(response: http.IncomingMessage): AuthenticationParameters;
429
430/**
431 * Creates an {@link AuthenticationParameters} object by sending a get request
432 * to the url passed to this function, and parsing the resulting http 401
433 * response.
434 * @param {string|url} url The url of a resource server.
435 * @param {AuthenticationParameters} callback Called on error or request completion.
436 * @param {string} [correlationId] An optional correlationId to pass along with the request and to include in any logs.
437 */
438export function createAuthenticationParametersFromUrl(url: string, callback: { (error: Error, parameters: AuthenticationParameters): void }, correlationId?: string): AuthenticationParameters;
\No newline at end of file