Adobe I/O Lib IMS Library API Documentation

Modules

aio-lib-ims

The @adobe/aio-lib-ims module offers three kinds of elements:

Managing configuration contexts for token creation and use
Creating and invalidating tokens
Providing low level access to IMS API

Classes

Ims: The Ims class wraps the IMS API.
ValidationCache
ValidationCache
ConfigCliContext: The ConfigCliContext class stores IMS contexts for the Adobe I/O CLI in the local file system using the Adobe I/O Core Configuration Library.
Context: The Context abstract class provides an interface to manage the IMS configuration contexts on behalf of the Adobe I/O Lib IMS Library.
StateActionContext: The StateActionContext class stores IMS contexts for Adobe I/O Runtime Actions in the cloud using the Adobe I/O State Library.

Constants

TYPE_ACTION: Name of context type action
TYPE_CLI: Name of context type cli
IMS: Name of the IMS configuration context data structure
CONTEXTS: Property holding an object with all contexts
CONFIG: Property holding an object with context management configuration
CLI: Property holding the cli context name
CURRENT: Property holding the current context name
Updater: Create an Updater for the Error wrapper
E: Provides a wrapper to easily create classes of a certain name, and values
ACCESS_TOKEN: The constant string access_token.
REFRESH_TOKEN: The constant string refresh_token.
AUTHORIZATION_CODE: The constant string authorization_code.
CLIENT_CREDENTIALS: The constant string client_credentials.
CLIENT_ID: The constant string client_id.
CLIENT_SECRET: The constant string client_secret.
SCOPE: The constant string scope.

Functions

_sendPost(postUrl, token, postData) ⇒ Promise: Send a request via POST.
getTokenData(token) ⇒ object: Returns the decoded token value as JavaScript object.

Typedefs

ClientCredentialsResponse : object
ValidationResult : object
ValidationFunction ⇒ Promise.<ValidationResult>

aio-lib-ims

The @adobe/aio-lib-ims module offers three kinds of elements:

Managing configuration contexts for token creation and use
Creating and invalidating tokens
Providing low level access to IMS API

aio-lib-ims
- .getTokenData
- .Ims
- .ValidationCache
- .ACCESS_TOKEN
- .REFRESH_TOKEN
- .AUTHORIZATION_CODE
- .CLIENT_ID
- .CLIENT_SECRET
- .SCOPE
- .context
- .getToken(contextName, options) ⇒ Promise
- .invalidateToken(contextName, [force]) ⇒ Promise

aio-lib-ims.getTokenData

Kind: static property of aio-lib-ims
See: getTokenData

aio-lib-ims.Ims

Kind: static property of aio-lib-ims
See: Ims

aio-lib-ims.ValidationCache

Kind: static property of aio-lib-ims
See: ValidationCache

aio-lib-ims.ACCESS_TOKEN

Kind: static property of aio-lib-ims
See: ACCESS_TOKEN

aio-lib-ims.REFRESH_TOKEN

Kind: static property of aio-lib-ims
See: REFRESH_TOKEN

aio-lib-ims.AUTHORIZATION_CODE

Kind: static property of aio-lib-ims
See: AUTHORIZATION_CODE

aio-lib-ims.CLIENT_ID

Kind: static property of aio-lib-ims
See: CLIENT_ID

aio-lib-ims.CLIENT_SECRET

Kind: static property of aio-lib-ims
See: CLIENT_SECRET

aio-lib-ims.SCOPE

Kind: static property of aio-lib-ims
See: SCOPE

aio-lib-ims.context

Kind: static property of aio-lib-ims
See: Context

aio-lib-ims.getToken(contextName, options) ⇒ `Promise`

Returns an access token for the given context name. When running in Adobe I/O Runtime tokens will be persisted in the State SDK.

Kind: static method of aio-lib-ims
Returns: Promise - Resolving to an access token (string)

Param	Type	Description
contextName	`string`	The name of the IMS context for which to return the access token. If this is empty, the token(s) of the current IMS context are invalidated.
options	`object`	A set of arbitrary options which will be passed to the underlying login plugin.

aio-lib-ims.invalidateToken(contextName, [force]) ⇒ `Promise`

Invalidates the access and optionally refresh of an IMS context. The name of the IMS context is given as its first parameter and defaults to the current context if missing or empty. The force parameter indicates whether only the access token is invalidated (force=false) or the refresh token (if existing) is also invalidated (force=true). If the refresh token exists and is validated, all access tokens which have been created with this refresh token will automatically become invalid as well.

Kind: static method of aio-lib-ims
Returns: Promise - Promise that resolves with the request data

Param	Type	Description
contextName	`string`	The name of the IMS context for which to invalidate the token(s). If this is empty, the token(s) of the current IMS context are invalidated.
[force]	`boolean`	Whether to invalidate just the access token or to also invalidate the refresh token. Defaults to `false`.

Ims

The Ims class wraps the IMS API.

Kind: global class

Ims
- new Ims(env, cache)
- instance
  - .getApiUrl(api) ⇒ string
  - .getSusiUrl(clientId, scopes, callbackUrl, state) ⇒ string
  - .get(api, token, parameters) ⇒ Promise
  - .post(api, token, parameters) ⇒ Promise
  - .getAccessToken(authCode, clientId, clientSecret, scopes) ⇒ Promise
  - .getAccessTokenByClientCredentials(clientId, clientSecret, orgId, scopes) ⇒ Promise
  - .exchangeJwtToken(clientId, clientSecret, signedJwtToken) ⇒ Promise
  - .invalidateToken(token, clientId, clientSecret) ⇒ Promise
  - .validateTokenAllowList(token, allowList) ⇒ Promise
  - .validateToken(token, [clientId]) ⇒ object
  - ._validateToken(token, [clientId]) ⇒ object
  - .getOrganizations(token) ⇒ object
  - .toTokenResult(token) ⇒ Promise
- static
  - .fromToken(token) ⇒ Promise

new Ims(env, cache)

Creates a new IMS connector instance for the stage or prod environment

Param	Type	Description
env	`string`	The name of the environment. `prod` and `stage` are the only values supported. `prod` is default and any value other than `prod` or `stage` it is assumed to be the default value of `prod`. If not set, it will get the global cli env value. See https://github.com/adobe/aio-lib-env (which defaults to `prod` as well if not set)
cache	`ValidationCache`	The cache instance to use.

ims.getApiUrl(api) ⇒ `string`

Returns the absolute URL to call the indicated API. The API is expected to be the API absolute path, such as /ims/profile. To form the absolute URL, the scheme (https) and fully qualified domain of the IMS host for this instance's environment is prepended to the path.

Kind: instance method of Ims
Returns: string - The absolute URI for the IMS API

Param	Type	Description
api	`string`	The API (path) for which to return the URL

ims.getSusiUrl(clientId, scopes, callbackUrl, state) ⇒ `string`

Returns the URL for the environment of this instance which allows for OAuth2 based three-legged authentication with a browser for an end user.

Kind: instance method of Ims
Returns: string - the OAuth2 login URL

Param	Type	Description
clientId	`string`	The Client ID
scopes	`string`	The list of scopes to request as a blank separated list
callbackUrl	`string`	The callback URL after the user signed in
state	`string`	Any state value which is passed back from sign in

ims.get(api, token, parameters) ⇒ `Promise`

Send a GET request to an IMS API with the access token sending the parameters as request URL parameters.

Kind: instance method of Ims
Returns: Promise - a promise resolving to the result of the request

Param	Type	Description
api	`string`	The IMS API to `GET` from, e.g. `/ims/profile/v1`
token	`string`	The IMS access token to call the API
parameters	`Map`	A map of request parameters

ims.post(api, token, parameters) ⇒ `Promise`

Send a POST request to an IMS API with the access token sending the parameters as form data.

Kind: instance method of Ims
Returns: Promise - a promise resolving to the result of the request

Param	Type	Description
api	`string`	The IMS API to `POST` to, e.g. `/ims/profile/v1`
token	`string`	The IMS access token to call the API
parameters	`Map`	A map of request parameters

ims.getAccessToken(authCode, clientId, clientSecret, scopes) ⇒ `Promise`

Request the access token for the given client providing the access grant in the authCode. The promise resolve to the token result JavaScript object as follows:

{
  access_token: {
    token: "eyJ4NXUiOi...6ZodTesbag",
    expiry: 1566242851048
  },
  refresh_token: {
    token: "eyJ4NXUiOi...YbT1_szWZA",
    expiry: 1567366051050
  },
  payload: {
     ...full api response...
  }
}

Kind: instance method of Ims
Returns: Promise - a promise resolving to a tokens object as described in the toTokenResult or rejects to an error message.

Param	Type	Description
authCode	`string`	The authorization code received from the OAuth2 sign in page or by some other means. This may also be a refresh token which may be traded for a new access token.
clientId	`string`	The Client ID
clientSecret	`string`	The Client Secrete proving client ID ownership
scopes	`string`	The list of scopes to request as a blank separated list

ims.getAccessTokenByClientCredentials(clientId, clientSecret, orgId, scopes) ⇒ `Promise`

Request an access token of the Client Credentials Grant Type.

Kind: instance method of Ims
Returns: Promise - a promise resolving to a token object as described in the ClientCredentialsResponse or rejects to an error message.

Param	Type	Description
clientId	`string`	The Client ID
clientSecret	`string`	The Client Secret proving client ID ownership
orgId	`string`	the IMS org Id
scopes	`Array.<string>`	The list of scopes to request as a blank separated list

ims.exchangeJwtToken(clientId, clientSecret, signedJwtToken) ⇒ `Promise`

Asks for the signed JWT token to be exchanged for a valid access token as well as a refresh token. The promise resolve to the token result JavaScript object as follows:

{
  access_token: {
    token: "eyJ4NXUiOi...6ZodTesbag",
    expiry: 1566242851048
  },
  payload: {
     ...full api response...
  }
}

Note that there is no refresh_token in a JWT token exchange.

Kind: instance method of Ims
Returns: Promise - returns a Promise that resolves to the token result object

Param	Type	Description
clientId	`string`	The client ID of the owning application
clientSecret	`string`	The client's secret
signedJwtToken	`string`	The properly signed JWT token for the JWT token exchange

ims.invalidateToken(token, clientId, clientSecret) ⇒ `Promise`

Invalidates the given token. If the token is a refresh token, all the access tokens created with that refresh token will also be invalidated at the same time.

Kind: instance method of Ims
Returns: Promise - Promise that resolves with the request data

Param	Type	Description
token	`string`	the access token
clientId	`string`	the client id
clientSecret	`string`	the client secret

ims.validateTokenAllowList(token, allowList) ⇒ `Promise`

Validates the given token against an allow list.

Optional: If a cache is provided, the token will be validated against the cache first.

Note: The cache uses the returned status key to determine if the result should be cached. This is not returned to the user.

Kind: instance method of Ims
Returns: Promise - Promise that resolves with the ims validation result

Param	Type	Description
token	`string`	the token to validate
allowList	`Array.<string>`	the allow list to validate against

ims.validateToken(token, [clientId]) ⇒ `object`

Validates the given token.

Kind: instance method of Ims
Returns: object - the server response

Param	Type	Description
token	`string`	the access token
[clientId]	`string`	the client id, optional

ims._validateToken(token, [clientId]) ⇒ `object`

Verifies a given token, returns a status which can be used to determine cache status if this function is passed to the validation cache.

Kind: instance method of Ims
Returns: object - Status code and the server response

Param	Type	Description
token	`string`	the access token
[clientId]	`string`	the client id, optional

ims.getOrganizations(token) ⇒ `object`

Gets the IMS organizations attached to the given token.

Kind: instance method of Ims
Returns: object - the server response

Param	Type	Description
token	`string`	the access token

ims.toTokenResult(token) ⇒ `Promise`

Converts the access token to a token result object as follows:

{
  access_token: {
    token: "eyJ4NXUiOi...6ZodTesbag",
    expiry: 1566242851048
  }
}

The expiry property is the expiry time of the token in milliseconds since the epoch.

Kind: instance method of Ims
Returns: Promise - a Promise resolving to an object as described.

Param	Type	Description
token	`string`	The access token to wrap into a token result

Ims.fromToken(token) ⇒ `Promise`

Creates an instance of the Ims class deriving the instance's environment from the as claim in the provided access token.

Kind: static method of Ims
Returns: Promise - A Promise resolving to the Ims instance.

Param	Type	Description
token	`string`	The access token from which to extract the environment to setup the `Ims` instancee.

ValidationCache

Kind: global class

ValidationCache
- new ValidationCache()
- new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)
- .validateWithCache(validationFunction, ...validationParams) ⇒ Promise.<object>

new ValidationCache()

A class to cache valid or invalid results. Internally two separate cache entries are maintained. Each cache entry is about 66Bytes big.

new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)

Creates a new LRU cache instance.

Param	Type	Description
maxAge	`number`	The maximum age in milliseconds of cache validity.
maxValidEntries	`number`	The maximum number of valid entries that can be contained in the cache.
maxInvalidEntries	`number`	The maximum number of invalid entries that can be contained in the cache.

validationCache.validateWithCache(validationFunction, ...validationParams) ⇒ `Promise.<object>`

Applies a validation function and caches the result. If there is a cache entry available returns the cached result without calling the validation function. The cache key is computed from the validation params

Kind: instance method of ValidationCache
Returns: Promise.<object> - validation result

Param	Type	Description
validationFunction	`ValidationFunction`	a function that returns an object of the form `{ status, message }`
...validationParams	`string`	parameters for the validationFunction, must be at least one

ValidationCache

Kind: global class

ValidationCache
- new ValidationCache()
- new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)
- .validateWithCache(validationFunction, ...validationParams) ⇒ Promise.<object>

new ValidationCache()

A class to cache valid or invalid results. Internally two separate cache entries are maintained. Each cache entry is about 66Bytes big.

new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)

Creates a new LRU cache instance.

Param	Type	Description
maxAge	`number`	The maximum age in milliseconds of cache validity.
maxValidEntries	`number`	The maximum number of valid entries that can be contained in the cache.
maxInvalidEntries	`number`	The maximum number of invalid entries that can be contained in the cache.

validationCache.validateWithCache(validationFunction, ...validationParams) ⇒ `Promise.<object>`

Applies a validation function and caches the result. If there is a cache entry available returns the cached result without calling the validation function. The cache key is computed from the validation params

Kind: instance method of ValidationCache
Returns: Promise.<object> - validation result

Param	Type	Description
validationFunction	`ValidationFunction`	a function that returns an object of the form `{ status, message }`
...validationParams	`string`	parameters for the validationFunction, must be at least one

ConfigCliContext

The ConfigCliContext class stores IMS contexts for the Adobe I/O CLI in the local file system using the Adobe I/O Core Configuration Library.

Kind: global class

ConfigCliContext
- .getCli() ⇒ Promise.<any>
- .setCli(contextData, [local], [merge])

configCliContext.getCli() ⇒ `Promise.<any>`

Gets the cli context data

Kind: instance method of ConfigCliContext
Returns: Promise.<any> - the cli context data

configCliContext.setCli(contextData, [local], [merge])

Sets the cli context data

Kind: instance method of ConfigCliContext

Param	Type	Default	Description
contextData	`object`		the data to save
[local]	`boolean`	`false`	set to true to save to local config, false for global config
[merge]	`boolean`	`true`	set to true to merge existing data with the new data

Context

The Context abstract class provides an interface to manage the IMS configuration contexts on behalf of the Adobe I/O Lib IMS Library.

Kind: global class

Context
- .getCurrent() ⇒ Promise.<string>
- .setCurrent(contextName) ⇒ Promise.<any>
- .get(contextName) ⇒ Promise.<object>
- .set(contextName, contextData, local)
- .keys() ⇒ Promise.<Array.<string>>

context.getCurrent() ⇒ `Promise.<string>`

Gets the current context name.

Kind: instance method of Context
Returns: Promise.<string> - the current context name

context.setCurrent(contextName) ⇒ `Promise.<any>`

Sets the current context name in the local configuration

Kind: instance method of Context
Returns: Promise.<any> - returns an instance of the Config object

Param	Type	Description
contextName	`string`	The name of the context to use as the current context

context.get(contextName) ⇒ `Promise.<object>`

Returns an object representing the named context. If the contextName parameter is empty or missing, it defaults to the current context name. The result is an object with two properties:

name: The actual context name used
data: The IMS context data

Kind: instance method of Context
Returns: Promise.<object> - The configuration object

Param	Type	Description
contextName	`string`	Name of the context information to return.

context.set(contextName, contextData, local)

Updates the named configuration with new configuration data. If a configuration object for the named context already exists it is completely replaced with this new configuration.

Kind: instance method of Context

Param	Type	Default	Description
contextName	`string`		Name of the context to update
contextData	`object`		The configuration data to store for the context
local	`boolean`	`false`	Persist in local or global configuration. When running in Adobe I/O Runtime, this has no effect unless `contextData` contains an `access_token` or `refresh_token` field, in which case setting `local=true` will prevent the persistence of those fields in the `State SDK`. Please note that when calling `getToken` in an I/O Runtime Action, generated tokens will always be persisted as `getToken` internally calls `context.set` with `local=false`.

context.keys() ⇒ `Promise.<Array.<string>>`

Returns the names of the configured contexts as an array of strings.

Kind: instance method of Context
Returns: Promise.<Array.<string>> - The names of the currently known configurations.

StateActionContext

The StateActionContext class stores IMS contexts for Adobe I/O Runtime Actions in the cloud using the Adobe I/O State Library.

Kind: global class

TYPE_ACTION

Name of context type action

Kind: global constant

TYPE_CLI

Name of context type cli

Kind: global constant

IMS

Name of the IMS configuration context data structure

Kind: global constant

CONTEXTS

Property holding an object with all contexts

Kind: global constant

CONFIG

Property holding an object with context management configuration

Kind: global constant

CLI

Property holding the cli context name

Kind: global constant

CURRENT

Property holding the current context name

Kind: global constant

Updater

Create an Updater for the Error wrapper

Kind: global constant

E

Provides a wrapper to easily create classes of a certain name, and values

Kind: global constant

ACCESS_TOKEN

The constant string access_token.

Kind: global constant

REFRESH_TOKEN

The constant string refresh_token.

Kind: global constant

AUTHORIZATION_CODE

The constant string authorization_code.

Kind: global constant

CLIENT_CREDENTIALS

The constant string client_credentials.

Kind: global constant

CLIENT_ID

The constant string client_id.

Kind: global constant

CLIENT_SECRET

The constant string client_secret.

Kind: global constant

SCOPE

The constant string scope.

Kind: global constant

_sendPost(postUrl, token, postData) ⇒ `Promise`

Send a request via POST.

Kind: global function
Returns: Promise - Promise that resolves with the request data

Param	Type	Description
postUrl	`string`	the url endpoint
token	`string`	the authorization token
postData	`object`	the data to send

getTokenData(token) ⇒ `object`

Returns the decoded token value as JavaScript object.

Kind: global function
Returns: object - The decoded token payload data without header and signature

Param	Type	Description
token	`string`	The token to decode and extract the token value from

ClientCredentialsResponse : `object`

Kind: global typedef
Properties

Name	Type	Description
access_token	`string`	The access token issued by IMS
token_type	`string`	The type of the token (in this case 'bearer')
expires_in	`number`	The lifetime in seconds of the access token

ValidationResult : `object`

Kind: global typedef
Properties

Name	Type	Description
status	`number`	validation response status code, e.g 200, 401, 403, ...
message	`string`	validation message, e.g. reason of failed validation

ValidationFunction ⇒ `Promise.<ValidationResult>`

Kind: global typedef
Returns: Promise.<ValidationResult> - validation result

Param	Type	Description
...params	`string`	validation params used for building the cache key (at least one)

Files

api.md

Latest commit

History

api.md

File metadata and controls

Adobe I/O Lib IMS Library API Documentation

Modules

Classes

Constants

Functions

Typedefs

aio-lib-ims

aio-lib-ims.getTokenData

aio-lib-ims.Ims

aio-lib-ims.ValidationCache

aio-lib-ims.ACCESS_TOKEN

aio-lib-ims.REFRESH_TOKEN

aio-lib-ims.AUTHORIZATION_CODE

aio-lib-ims.CLIENT_ID

aio-lib-ims.CLIENT_SECRET

aio-lib-ims.SCOPE

aio-lib-ims.context

aio-lib-ims.getToken(contextName, options) ⇒ Promise

aio-lib-ims.invalidateToken(contextName, [force]) ⇒ Promise

Ims

new Ims(env, cache)

ims.getApiUrl(api) ⇒ string

ims.getSusiUrl(clientId, scopes, callbackUrl, state) ⇒ string

ims.get(api, token, parameters) ⇒ Promise

ims.post(api, token, parameters) ⇒ Promise

ims.getAccessToken(authCode, clientId, clientSecret, scopes) ⇒ Promise

ims.getAccessTokenByClientCredentials(clientId, clientSecret, orgId, scopes) ⇒ Promise

ims.exchangeJwtToken(clientId, clientSecret, signedJwtToken) ⇒ Promise

ims.invalidateToken(token, clientId, clientSecret) ⇒ Promise

ims.validateTokenAllowList(token, allowList) ⇒ Promise

ims.validateToken(token, [clientId]) ⇒ object

ims._validateToken(token, [clientId]) ⇒ object

ims.getOrganizations(token) ⇒ object

ims.toTokenResult(token) ⇒ Promise

Ims.fromToken(token) ⇒ Promise

ValidationCache

new ValidationCache()

new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)

validationCache.validateWithCache(validationFunction, ...validationParams) ⇒ Promise.<object>

ValidationCache

new ValidationCache()

new ValidationCache(maxAge, maxValidEntries, maxInvalidEntries)

validationCache.validateWithCache(validationFunction, ...validationParams) ⇒ Promise.<object>

ConfigCliContext

configCliContext.getCli() ⇒ Promise.<any>

configCliContext.setCli(contextData, [local], [merge])

Context

context.getCurrent() ⇒ Promise.<string>

context.setCurrent(contextName) ⇒ Promise.<any>

context.get(contextName) ⇒ Promise.<object>

context.set(contextName, contextData, local)

context.keys() ⇒ Promise.<Array.<string>>

StateActionContext

TYPE_ACTION

TYPE_CLI

IMS

CONTEXTS

CONFIG

CLI

CURRENT

Updater

E

ACCESS_TOKEN

REFRESH_TOKEN

AUTHORIZATION_CODE

CLIENT_CREDENTIALS

CLIENT_ID

CLIENT_SECRET

SCOPE

_sendPost(postUrl, token, postData) ⇒ Promise

getTokenData(token) ⇒ object

ClientCredentialsResponse : object

ValidationResult : object

ValidationFunction ⇒ Promise.<ValidationResult>

aio-lib-ims.getToken(contextName, options) ⇒ `Promise`

aio-lib-ims.invalidateToken(contextName, [force]) ⇒ `Promise`

ims.getApiUrl(api) ⇒ `string`

ims.getSusiUrl(clientId, scopes, callbackUrl, state) ⇒ `string`

ims.get(api, token, parameters) ⇒ `Promise`

ims.post(api, token, parameters) ⇒ `Promise`

ims.getAccessToken(authCode, clientId, clientSecret, scopes) ⇒ `Promise`

ims.getAccessTokenByClientCredentials(clientId, clientSecret, orgId, scopes) ⇒ `Promise`

ims.exchangeJwtToken(clientId, clientSecret, signedJwtToken) ⇒ `Promise`

ims.invalidateToken(token, clientId, clientSecret) ⇒ `Promise`

ims.validateTokenAllowList(token, allowList) ⇒ `Promise`

ims.validateToken(token, [clientId]) ⇒ `object`

ims._validateToken(token, [clientId]) ⇒ `object`

ims.getOrganizations(token) ⇒ `object`

ims.toTokenResult(token) ⇒ `Promise`

Ims.fromToken(token) ⇒ `Promise`

validationCache.validateWithCache(validationFunction, ...validationParams) ⇒ `Promise.<object>`

validationCache.validateWithCache(validationFunction, ...validationParams) ⇒ `Promise.<object>`

configCliContext.getCli() ⇒ `Promise.<any>`

context.getCurrent() ⇒ `Promise.<string>`

context.setCurrent(contextName) ⇒ `Promise.<any>`

context.get(contextName) ⇒ `Promise.<object>`

context.keys() ⇒ `Promise.<Array.<string>>`

_sendPost(postUrl, token, postData) ⇒ `Promise`

getTokenData(token) ⇒ `object`

ClientCredentialsResponse : `object`

ValidationResult : `object`

ValidationFunction ⇒ `Promise.<ValidationResult>`