sdk-middleware-auth

Middleware to authenticate the request using one of the supported auth flows.

⚠️ In Maintenance Mode ⚠️

This package has been replaced by the TypeScript SDK is in maintenance mode as such this tool will no longer receive new features or bug fixes.

We recommend to use the TypeScript SDK for any new implementation and plan migrating to it.

Install

Node.js

npm install --save @commercetools/sdk-middleware-auth

Browser

<script src="https://unpkg.com/@commercetools/sdk-middleware-auth/dist/commercetools-sdk-middleware-auth.umd.min.js"></script>
<script>
  // global: CommercetoolsSdkMiddlewareAuth
</script>

createAuthMiddlewareForClientCredentialsFlow(options)

Creates a middleware to handle authentication for the Client Credentials Flow of the commercetools platform API.

Named arguments (options)

1. host (String): the host of the OAuth API service
2. projectKey (String): the key of the project to assign the default scope to
3. credentials (Object): the client credentials for authentication (clientId, clientSecret)
4. scopes (Array): a list of scopes (default manage_project:{projectKey}) to assign to the OAuth token
5. fetch (Function): A fetch implementation which can be e.g. node-fetch or unfetch but also the native browser fetch function. Only needs be be passed if not globally available (e.g. through isomorphic-fetch)
6. timeout (Number): An optional number value (in milliseconds) which specifies when a request should timeout if authentication request fails to complete.
7. getAbortController (Function): An optional abortController class instance that should signal the http-client to abandon the current request instance.

Usage example

import { createClient } from '@commercetools/sdk-client'
import { createAuthMiddlewareForClientCredentialsFlow } from '@commercetools/sdk-middleware-auth'

const client = createClient({
  middlewares: [
    createAuthMiddlewareForClientCredentialsFlow({
      host: 'https://auth.commercetools.com',
      projectKey: 'test',
      credentials: {
        clientId: '123',
        clientSecret: 'secret',
      },
      scopes: ['view_products:test', 'manage_orders:test'],

      // Optional if not globally available
      fetch,
      timeout: 10000, // timeout the request if it doesn't complete in 10000ms or 10 seconds
      getAbortController: () => new AbortController(),
    }),
  ],
})

createAuthMiddlewareForPasswordFlow(options)

Creates a middleware to handle authentication for the Password Flow of the commercetools platform API.

Named arguments (options)

1. host (String): the host of the OAuth API service
2. projectKey (String): the key of the project to assign the default scope to

3. credentials (Object): the client credentials for authentication (clientId, clientSecret, user)

4. The user field is an object containing username and password. Sample below

5. scopes (Array): a list of scopes to assign to the OAuth token. No default scope is sent

6. fetch (Function): A fetch implementation which can be e.g. node-fetch or unfetch but also the native browser fetch function. Only needs be be passed if not globally available (e.g. through isomorphic-fetch)
7. timeout (Number): An optional number value (in milliseconds) which specifies when a request should timeout if authentication request fails to complete.
8. getAbortController (Function): An optional abortController class instance that should signal the http-client to abandon the current request instance.

Usage example

import { createClient } from '@commercetools/sdk-client'
import { createAuthMiddlewareForPasswordFlow } from '@commercetools/sdk-middleware-auth'

const client = createClient({
  middlewares: [
    createAuthMiddlewareForPasswordFlow({
      host: 'https://auth.commercetools.com',
      projectKey: 'test',
      credentials: {
        clientId: '123',
        clientSecret: 'secret',
        user: {
          username: string,
          password: string,
        },
      },
      scopes: ['view_products:test', 'manage_orders:test'],

      // Optional if not globally available
      fetch,
      timeout: 10000, // timeout the request if it doesn't complete in 10000ms or 10 seconds
      getAbortController: () => new AbortController(),
    }),
  ],
})

createAuthMiddlewareForAnonymousSessionFlow(options)

Creates a middleware to handle authentication for the Anonymous Session Flow of the commercetools platform API.

Named arguments (options)

1. host (String): the host of the OAuth API service
2. projectKey (String): the key of the project to assign the default scope to
3. credentials (Object): the client credentials for authentication (clientId, clientSecret, anonymousId)
4. scopes (Array): a list of scopes (default manage_project:{projectKey}) to assign to the OAuth token
5. fetch (Function): A fetch implementation which can be e.g. node-fetch or unfetch but also the native browser fetch function. Only needs be be passed if not globally available (e.g. through isomorphic-fetch)
6. timeout (Number): An optional number value (in milliseconds) which specifies when a request should timeout if authentication request fails to complete.
7. getAbortController (Function): An optional abortController class instance that should signal the http-client to abandon the current request instance.

Usage example

import { createClient } from '@commercetools/sdk-client'
import { createAuthMiddlewareForAnonymousSessionFlow } from '@commercetools/sdk-middleware-auth'

const client = createClient({
  middlewares: [
    createAuthMiddlewareForAnonymousSessionFlow({
      host: 'https://auth.commercetools.com',
      projectKey: 'test',
      credentials: {
        clientId: '123',
        clientSecret: 'secret',
        anonymousId: 'unique-id-of-customer-not-required',
      },
      scopes: ['view_products:test', 'manage_orders:test'],

      // Optional if not globally available
      fetch,
      timeout: 10000, // timeout the request if it doesn't complete in 10000ms or 10 seconds
      getAbortController: () => new AbortController(),
    }),
  ],
})

createAuthMiddlewareForRefreshTokenFlow(options)

Creates a middleware to handle authentication for the Refresh Token Flow of the commercetools platform API.

Named arguments (options)

1. host (String): the host of the OAuth API service
2. projectKey (String): the key of the project to assign the default scope to
3. credentials (Object): the client credentials for authentication (clientId, clientSecret)
4. refreshToken (String): refreshToken from the API to use to fetch new token.
5. fetch (Function): A fetch implementation which can be e.g. node-fetch or unfetch but also the native browser fetch function. Only needs be be passed if not globally available (e.g. through isomorphic-fetch)
6. timeout (Number): An optional number value (in milliseconds) which specifies when a request should timeout if authentication request fails to complete.
7. getAbortController (Function): An optional abortController class instance that should signal the http-client to abandon the current request instance.

Usage example

import { createClient } from '@commercetools/sdk-client'
import { createAuthMiddlewareForRefreshTokenFlow } from '@commercetools/sdk-middleware-auth'

const client = createClient({
  middlewares: [
    createAuthMiddlewareForRefreshTokenFlow({
      host: 'https://auth.commercetools.com',
      projectKey: 'test',
      credentials: {
        clientId: '123',
        clientSecret: 'secret',
      },
      refreshToken: 'foobar123',

      // Optional if not globally available
      fetch,
      timeout: 10000, // timeout the request if it doesn't complete in 10000ms or 10 seconds
      getAbortController: () => new AbortController(),
    }),
  ],
})

createAuthMiddlewareWithExistingToken(authorization, options)

Creates a middleware that attaches a provided access token Authorization header.

Named arguments (authorization, options)

authorization (String): the value for the Authorization header. For example, you may pass the scheme "Bearer" ("Bearer 1234") or "Basic" ("Basic 134") and so on, depending on your authentication mechanism.

options is an optional (Object), having the following properties:

1. force (Boolean): if set to true, existing Authorization header (if any) in the request will be overridden with the supplied access token (Default: true)
2. timeout (Number): An optional number value (in milliseconds) which specifies when a request should timeout if authentication request fails to complete.
3. getAbortController (Function): An optional abortController class instance that should signal the http-client to abandon the current request instance.

Note: if timeout is specified, then it's mandatory to also specify the getAbortController property.

import { createClient } from '@commercetools/sdk-client'
import { createAuthMiddlewareWithExistingToken } from '@commercetools/sdk-middleware-auth'

const accessToken = 'my-access-token'

const client = createClient({
  middlewares: [
    createAuthMiddlewareWithExistingToken(`Bearer ${accessToken}`, {
      force: true,
      timeout: 10000, // timeout the request if it doesn't complete in 10000ms or 10 seconds
      getAbortController: () => new AbortController(),
    }),
  ],
})