Single sign-on via OpenID Connect

Single Sign-On (SSO) enables users to authenticate with the OrderCloud API using trusted identity providers. This allows shoppers to use existing accounts (like Google or Facebook) or corporate credentials for authentication.

OpenID Connect

OpenID Connect protocol enables single sign-on through RESTful API exchanges between an Identity Provider (IDP) and a Relying Party (RP). This guide focuses on configuring OrderCloud to trust an IDP for user authentication.

Configuring your identity provider (IDP)

OrderCloud requires four pieces of information from your IDP, whether using a service like Google or a custom implementation:

API Reference: Create an OpenID Connect Configuration

Keep Client ID and Client Secret private. URLs can be public (example: Google's URLS). Your IDP needs OrderCloud's Authorized Redirect URI:

https://sandboxapi.ordercloud.io/ocrpcode

This endpoint converts IDP access tokens to OrderCloud tokens and redirects users to your specified AppStartUrl.

Configuring OrderCloud (RP)

Step 1: Create an OpenID Connect integration event

Set up an OpenID Connect Integration Event with two hosted endpoints in your middleware application. See "Configuring Your Integration Event Code" section for details.

API Reference: Create an Integration Event

Step 2: Create connection configuration

Each configuration connects users to one OrderCloud ApiClient through one IDP:

API Reference: Create an OpenID Connect Configuration

POST sandboxapi.ordercloud.io/v1/openidconnects HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

{
  "ID": "anormalordercloudid",
  "OrdercloudApiClient": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "ConnectClientID": "...",
  "ConnectClientSecret": "...",
  "AppStartUrl": "https://my-buyer-application.com/login?token={0}",
  "AuthorizationEndpoint": "...",
  "TokenEndpoint": "...",
  "IntegrationEventID": "integrationeventID",
  "CustomErrorUrl": "https://my-buyer-application.com/error?ErrorMessage={0}"
}

Test the configuration as IDP fields are validated during login. The AppStartUrl redirects to your front-end app after login, with {0} replaced by a valid OrderCloud token.

Implementing login

Direct users to:

https://sandboxapi.ordercloud.io/ocrplogin?id=<ID>&roles=<Roles>&cid=<ApiClientID>

Parameters:

• <ID>: Configuration ID
• <ApiClientID>: OrdercloudAPIClient field
• <Roles>: Space-separated list of requested roles (standard and custom roles supported)

Users enter IDP credentials and receive an OrderCloud token via the AppStartUrl. Your application must handle token storage.

Configuring your integration event code

Host two endpoints for the OpenID Connect Integration Event:

/createuser

Called on first-time user authentication:

Request body:

{
  "ExistingUser": null,
  "OpenIdConnect": {},
  "TokenResponse": {
    "id_token": "eyJhbGciOiJSU...",
    "access_token": "ya29.a0ARrdaM92vGZsFj"
  },
  "Environment": "Sandbox",
  "OrderCloudAccessToken": "eyJhbGciOiJSU...",
  "ConfigData": null
}

Required response after user creation:

{
  "Username": "neworderclouduser",
  "ErrorMessage": null
}

/syncuser

Optional endpoint for subsequent authentications (requires CallSyncUserIntegrationEvent: true):

Request body:

{
  "ExistingUser": {},
  "OpenIdConnect": {},
  "TokenResponse": {
    "id_token": "eyJhbGciOiJSU...",
    "access_token": "ya29.a0ARrdaM92vGZsFj"
  },
  "Environment": "Sandbox",
  "OrderCloudAccessToken": "eyJhbGciOiJSU...",
  "ConfigData": null
}

Required response after user update:

{
  "ErrorMessage": null
}

Setting ErrorMessage in any response terminates the process.

Deep linking

Enable specific page redirects after login using the appstartpath parameter:

https://sandboxapi.ordercloud.io/ocrplogin?id=<ID>&roles=<Roles>&cid=<ApiClientID>&appstartpath=/products/my-promotional-product

Configure AppStartUrl with {2} placeholder:

https://my-buyer-application.com{2}?token={0}

Example URL-encoded path:

https://sandboxapi.ordercloud.io/ocrplogin?id=<ID>&roles=<Roles>&cid=<ApiClientID>&appstartpath=%2Fproducts%2Fmyawesomeproduct

Final redirect:

https://my-buyer-application.com/products/myawesomeproduct?token={yourordercloudtoken}

IDP token

Access IDP tokens using {1} in AppStartUrl:

https://my-buyer-application.com?token={0}&idptoken={1}

For Azure, include Application ID in OpenIdConnect.AdditionalIdpScopes.

OrderCloud refresh token

Include refresh tokens using {3} in AppStartUrl:

https://my-buyer-application.com?token={0}&refresh={3}

Requires API client configuration with refresh token duration.

Custom error redirect

Configure error handling with CustomErrorUrl:

https://my-buyer-application.com/error?ErrorMessage={0}

Custom query parameters to AuthorizationEndpoint

Add custom parameters using customParams:

https://sandboxapi.ordercloud.io/ocrplogin?id=<ID>&roles=<Roles>&cid=<ApiClientID>&appstartpath=%2Fproducts%2Fmyawesomeproduct&customParams=locale%3Dus

If you're using Azure B2C as your IDP, you'll need to include customParams=response_mode%3Dform_post in your GET /ocrplogin request. This will ensure Azure sends OrderCloud a POST request containing the authorization code in the request body rather than a GET request with the authorization code in the query parameters. Using any other response_mode is not recommended for those using Azure B2C as their IDP due to the excessive length of authorization codes generated by Azure.

Related reading

• Implementing Single Sign On with Google IDP
• Implementing Single Sign On with Azure AD B2C IDP
• Order Fees