OAuth 2.0 Configuration

OAuth 2

An Integration Definition consists of three main components, which match the OAuth2.0 code-exchange flow. In order, they are:

  1. Authorization
  2. Request Token
  3. Refresh Token
Pro Tip

If you are not familiar with OAuth2 code-exchange flow there are many

sites online that provide information:

Example Specification

Copy
Copied
import {
  AuthenticationType,
  AuthSpecification,
  OrderSourceAppMetadata,
} from "@shipengine/connect-order-source-api";

export const AuthProcess: AuthSpecification = {
  Identifier: {
    AuthenticationType: AuthenticationType.OAuth,
    IsSandbox: false,
  },
  authorization: {
    url_template: "https://accounts.example.com/o/oauth2/v2/auth",
    query_parameters: [
      {
        name: "client_id",
        value: "{installation:client_id}",
      },
      {
        name: "redirect_uri",
        value: "{system:authorize_callback_url}",
      },
      {
        name: "response_type",
        value: "code",
      },
      {
        name: "scope",
        value: "https://www.exampleapis.com/auth/content",
      },
      {
        name: "access_type",
        value: "offline",
      },
      {
        name: "prompt",
        value: "consent",
      },
    ],
    nonce: null,
  },
  request_token: {
    url_template: "https://oauth2.exampleapis.com/token",
    method: "POST",
    body: [
      {
        name: "redirect_uri",
        value: "{system:authorize_callback_url}",
      },
      {
        name: "code",
        value: "{callback:code}",
      },
      {
        name: "grant_type",
        value: "authorization_code",
      },
      {
        name: "client_id",
        value: "{installation:client_id}",
      },
      {
        name: "client_secret",
        value: "{installation:client_secret}",
      },
    ],
    headers: [
      {
        name: "Content-Type",
        value: "application/x-www-form-urlencoded",
      },
    ],
    query_parameters: [],
  },
  refresh_token: {
    url_template: "https://oauth2.exampleapis.com/token",
    method: "POST",
    body: [
      {
        name: "client_secret",
        value: "{installation:client_secret}",
      },
      {
        name: "grant_type",
        value: "refresh_token",
      },
      {
        name: "client_id",
        value: "{installation:client_id}",
      },
      {
        name: "refresh_token",
        value: "{result_token_response:refresh_token}",
      },
    ],
    headers: [
      {
        name: "Content-Type",
        value: "application/x-www-form-urlencoded",
      },
    ],
    query_parameters: [],
  },
  advanced_configuration: [],
};

export const Metadata: OrderSourceAppMetadata = {
  // DO NOT CHANGE THIS ID AFTER PUBLISHING
  Id: "bcce593b-dce3-4491-8722-a56e653c173f",
  Name: "Example",
  AuthProcess,
  OrderSources: [Example],
};

Advanced Topics

  • Response Transformation (specify how responses from the two exchanges can be mapped into the the platform canonical model)
  • Connection Context (allows a response transformer to specify a collection of properties in connection context)
  • Templating (substituting values in your configuration {installation:client id}, etc...)