lib-oauth-tooling - npm Package Versions

authmosphere 2.0.0 - BREAKING

General changes

The following functions got support for an optional logger:

• TokenCache (via TokenCacheOptions parameter)
• getTokenInfo (via logger parameter)
• getAccessToken (via logger parameter)
• authenticationMiddleware (via AuthenticationMiddlewareOptions parameter)
• requireScopesMiddleware (via ScopeMiddlewareOptions parameter)

Providing a logger is optional. Any logger needs to satisfy the Logger interface. To keep arguments lists short, option objects were introduced to group a number of (mostly) optional parameters.

Express middlewares

• handleOAuthRequestMiddleware was renamed to authenticationMiddleware

  • Config parameter MiddlewareOptions was renamed to AuthenticationMiddlewareOptions
  • An optional logger can be provided (Logger)
  • An optional onNotAuthenticatedHandler can be provided, which let you explicitly handle the case when authentication fails. Important note: if onNotAuthenticatedHandler is defined you are responsible to handle the request yourself (e.g. calling response.sendStatus(code) or next()).

• requireScopesMiddleware

  • Added optional options object of type ScopeMiddlewareOptions
    • An optional logger can be provided (Logger)
    • An optional onAuthorizationFailedHandler can be provided, which let you explicitly handle the case when authentication fails. Important note: if onAuthorizationFailedHandler is defined you are responsible to handle the request yourself (e.g. calling response.sendStatus(code) or next()).
  • Moved precedenceOptions parameter into options parameter
    • precedenceErrorHandler got removed from PrecedenceOptions. onAuthorizationFailedHandler should be used instead.

Changed TokenCache parameter type

The TokenCacheConfig parameter type is now called TokenCacheOptions and looks like:

type CacheConfig = {
  percentageLeft: number
};

type TokenCacheOptions = {
  cacheConfig?: CacheConfig,
  logger?: Logger
};

Improved OAuthConfig type

Restructuring

Instead of providing one bulky type for all OAuth2 grants the type OAuthConfig is split up into a union type of all supported grants. A type for the TokenCache config (TokenCacheOAuthConfig) is also derived:

type OAuthConfig =
  ClientCredentialsGrantConfig   |
  AuthorizationCodeGrantConfig   |
  PasswordCredentialsGrantConfig |
  RefreshGrantConfig;

type TokenCacheOAuthConfig = OAuthConfig & {
  tokenInfoEndpoint: string;
};

Passing optional body parameters

It is now possible to provide an optional object bodyParams which will be appended to the request body when requesting a token (via getAccessToken or TokenCache):

const config: OAuthConfig = {
  ...,
  bodyParams: {
    business_partner_id: 'xxx-xxx-xxx'
  }
};

Passing credentials

It is now possible to provide client (and user) credentials as a string instead of just via a credentialsDir:

const config: OAuthConfig = {
  ...,
  clientId,
  clientSecret,
  applicationUsername,
  applicationPassword
};

For detailed information have a look at the implementation of OAuthConfig.

Improved OAuthGrantType

Instead of four single string values, an enum OAuthGrantType is exported which should be used as grantType in OAuthConfig:

enum OAuthGrantType {
  AUTHORIZATION_CODE_GRANT = 'authorization_code',
  PASSWORD_CREDENTIALS_GRANT = 'password',
  REFRESH_TOKEN_GRANT = 'refresh_token',
  CLIENT_CREDENTIALS_GRANT = 'client_credentials'
}

More specific typing in createAuthCodeRequestUri

The type for the optional parameter queryParams is changed from {} to the more specific { [index: string]: string }.

Mock tooling

mockAccessTokenEndpoint respects scopes property

Before this release, mockAccessTokenEndpoint always includes uid as value of the scopes property in the returned token. Now, mockAccessTokenEndpoint includes the scopes which were requested by the HTTP request. A request like:

getAccessToken({
  ...,
  scopes: ['uid', 'test']
})

...will lead to a response with a token which includes the scopes uid and test. If no scopes are requested, the scopes property of the token will be undefined.

mockTokeninfoEndpoint parameters

Token was moved out of MockOptions into a separate parameter: mockTokeninfoEndpoint(options: MockOptions, tokens?: Token[]): nock.Scope.

New functionality to test OAuth behavior in case of error

mockWithErrorResponse

The library now exports mockTokeninfoEndpointWithErrorResponse and mockAccessTokenEndpointWithErrorResponse which allow to mock an OAuth endpoint with an error response to be able to test behaviour in error case more accurate:

mockTokeninfoEndpointWithErrorResponse(options: MockOptions, httpStatus: number, responseBody?: object): void
mockAccessTokenEndpointWithErrorResponse(options: MockOptions, httpStatus: number, responseBody?: object): void

Both functions set up a HTTP mock via nock. A request to the mocked url (defined via MockOptions) will lead to a response with the given httpStatus and, if defined, responseBody (otherwise {}).

Improved error handling

Promises returned by getAccessToken and getTokenInfo are now rejected in a consistent way with an error object like:

{
  error?: string | Error | object,
  message?: string
}

---