OAuth 2.0 Client

You can use the Kustomer OAuth 2.0 client, or consumer, to configure delegated access for Commands and REST API Workflow Actions based on a third-party OAuth 2.0 provider specification. This allows you to build powerful integrations in Kustomer with APIs and platforms (for example, Salesforce) that require this specification for authorized access.

When you configure an OAuth 2.0 client for use in an app, a Kustomer user must authorize the app with the configured third-party OAuth 2.0 provider before the user can install the app for their Kustomer organization. Once the user authorizes the app, the registered app creates an App Account entity to store the latest access token that will allow the user to access a third-party API in Kustomer.

Currently, users can add a single App Account entity when the auth field is configured for an app. Future work may allow users to add additional app accounts. The registered app reserves the name of this App Account entity as default.

You can reference an App Account entity and the entity credentials when authorizing a Command or rest_api-type Workflow Action in the field appAccountName as in the sample app definition below.

Redirect URI

Third-party OAuth 2.0 providers ofter require you to specify and whitelist a redirect URI to securely receive an authorization code during the OAuth 2.0 dance, or handshake.

👍

Static redirect URI

Kustomer uses non-variable, static redirect URIs to ensure compatibility with third-party OAuth providers that accept an exact, single redirect URI only.

redirect_url

If you need to specify a redirect URI for a third-party OAuth 2.0 provider, use the following format:

https://api.apps.kustomerapp.com/v1/apps/<APP_NAME>/authorize/oauth2/redirect

Example: https://api.apps.kustomerapp.com/v1/apps/ecommstore/authorize/oauth2/redirect for an app with the app name ecommstore.

{
  "app": "ecommstore",
  "version": "0.0.1",
  "title": "E-comm Store",
  "auth": {
  	"oauth2": {
    	"clientId": "ecommstoreclientid_e1093jg1093kf0192kf09j",
      "clientSecret": "ecommstoresecret_e1093jg1093kf0192kf09j",
      "clientCredentialsMethod": "basicAuth",
      "authorizationUrl": "https://api.ecommstore.com/authorize",
      "tokenUrl": "https://api.ecommstore.com/access_token",
      "authorizationScope": "update_order read_order",
      "customHeader": "X-EComm-Store-Access-Token",
      "expiresIn": 3600
    }
  },
  "commands": [{
    "name": "ecommstore.app.store.refundOrder",
    "displayName": "Refund Order",
    "permittedUrlArgs": ["store"],
    "url": "https://{{{store}}}.example-ecommstore.com/orders",
    "httpMethod": "post",
    "auditLogging": true,
    "appAccountName": "default",
    "inputSchema": {
       "type": "object",
       "properties": {
         "foo": {
           "type": "string"
         }
       },
       "additionalProperties": false,
       "required": [
         "foo"
       ]
    }, 
    "outputSchema": {
       "type": "object",
       "properties": {
         "foo": {
           "type": "string"
         }
       },
       "additionalProperties": true,
       "required": []
    }
  }],
  "actions": [{
    "name": "ecommstore.store.refundOrder",
    "description": "Refund Order",
    "type": "rest_api",
    "appAccountName": "default",
    "inputTemplate": {
      "uri": "https://api.ecommstore.com/orders/{{orderId}},
      "method": "POST",
      "qs": "/#querystring",
      "body": "{refund: true}",
      "json": true
    }, 
    "outputTemplate": {
      "body": "/#body"
    },
    "sampleOutputContext": {
    	"body": "{status: "REFUNDED"}
    },
    "inputSchema": {
      "type": "object",
      "properties": {
        "querystring": {
          "type": "string",
        }
      },
      "required": [],
      "additionalProperties": false
    }, 
    "outputSchema": {
      "type": "object",
      "properties": {
        "response": {
          "type": "object"
        },
        "body": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  }]
}

OAuth 2.0 auth.oauth2 definition properties

The basic 'auth.oauth2' definition properties and their descriptions are listed below:

clientId

Required. The client ID that the relevant third-party OAuth 2.0 provider lists for your app.

Example: "clientId": "ecommstoreclientid_e1093jg1093kf0192kf09j"

clientSecret

Recommended. The client secret that third-party OAuth 2.0 providers often require for your app to authorize.

🚧

Secure client secrets 🤫

The OAuth 2.0 authorization flow stores the client secret based on encryption signed with the Kustomer organization that registered and made the app available. Keep your client secret secure, and never publish or reveal your client secret in a starter repo or other public code.

Example: "clientSecret": "ecommstoresecret_e1093jg1093kf0192kf09j"

authorizationUrl

Required. The URL at which the App Settings page needs to redirect the relevant OAuth 2.0 provider for a user to authorize your application.

Example: "authorizationUrl": "https://api.ecommstore.com/authorize"

tokenUrl

Required. The URL at which the relevant OAuth 2.0 provider, if specified, allows an authorization code, the clientId configured above, and the clientSecret configured above, to be exchanged for an access token to be stored in an App Account entity.

Example: "tokenUrl": "https://api.ecommstore.com/access_token"

clientCredentialsMethod

Required. The method for how to provide a clientId and clientSecret (if specified). There are two possible methods:

form: The clientId and clientSecret (if specified) are provided through a form submission to the specified tokenUrl in exchange for an access token.

basicAuth: The clientId and clientSecret (if specified) are base64-encoded and provided in a basic auth header in the access token request. To learn more, consult section 2.1.3. Client Password of the OAuth 2.0 RFC specification to see if this applies for your OAuth 2.0 provider configuration.

Example: "clientCredentialsMethod": "basicAuth"

authorizationScope

Optional. Corresponds to the string that specifies the scope of the access your application needs with the relevant OAuth 2.0 provider.

Example: "authorizationScope": "update_order read_order"

customHeader

Optional. The name of a custom header where an authorized App Account entity will inject the available access token when the entity makes an outbound request to a configured Command or rest_api-type Workflow Action.

Example: "customHeader": "X-EComm-Store-Access-Token"

In the example above, the App Account entity would add the following custom header to the outbound request to a Command or rest_api-type Workflow Action:

• X-EComm-Store-Access-Token:{{ accessToken }} for a custom header

If no custom header is not specified, the App Account entity uses the following header instead in the outbound request to a Command or rest_api-type Workflow Action:

• Authorization:Bearer {{ accessToken }}

expiresIn

Optional. Override for the access token lifetime in seconds. When the relevant third-party OAuth 2.0 provider requires your application to use refresh tokens, you can specify an expiresIn value to override the access token lifetime provided in the access token body.

A default access token expiration interval of 3600 seconds is used if an expiresIn value is not specified in the app definition, or if the access token response body and the request contain a refresh token.

Example: "expiresIn": "3600"