---
title: Single sign-on
slug: single-sign-on
abstract: Single Sign-On (SSO) enables users to authenticate with the OrderCloud API using trusted identity providers
content_type: concept
audience: \[architect, developer]
---
# Single sign-on

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.

## Implementing SSO with 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:

| Properties | Description |
| ------------ | ------------- |
| `TokenEndpoint` | URL for obtaining user-specific JSON web token |
| `AuthorizationEndpoint` | URL for user IDP credential entry |
| `ConnectClientID` | Required for URL access |
| `ConnectClientSecret` | Required for URL access |

API Reference: [Create an OpenID Connect Configuration](https://api-docs.sitecore.com/ordercloud/open-id-connects/openidconnects.create)

Keep Client ID and Client Secret private. URLs can be public (example: [Google's URLS](https://accounts.google.com/.well-known/openid-configuration)). 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](https://api-docs.sitecore.com/ordercloud/integration-events/integrationevents.create)

#### Step 2: Create connection configuration

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

API Reference: [Create an OpenID Connect Configuration](https://api-docs.sitecore.com/ordercloud/open-id-connects/openidconnects.create)

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

```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:

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

Required response after user creation:

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

#### /syncuser

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

Request body:

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

Required response after user update:

```json
{
  "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.

## Implementing SSO with Azure AD B2C IDP

OpenID Connect is a powerful feature that enables you to provide single sign-on capabilities for any identity provider that supports the specification. In this tutorial we'll walk you step by step through what you'll need to get single sign-on working by using Azure AD B2C as the identity provider. By the end of this tutorial, you'll be able to sign in via Azure and be logged into OrderCloud.

### Implementation outcome

Before we start, let's understand the finished product. By the end of this tutorial you will have a locally running application that will redirect you to Azure's sign-in page and after successfully signing in you should see your login details including:

- Currently authenticated user
- OrderCloud Access Token
- OrderCloud Refresh Token (if configured)
- Azure ID Token (if configured)

### Marketplace configuration

First, you need to access your Marketplace in the Sitecore Cloud Portal.

After accessing, take special note of the OrderCloud Base API URL, which identifies the base URL needed for all API requests.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/d511925e457740d986676d317664afa2.png)

For this demonstration we are on the Sandbox environment in the region Us-West so our base API URL is <https://sandboxapi.ordercloud.io>, yours may look different.

#### Supporting entities

We will be creating a single-sign-on experience for buyer users specifically, so we'll create the most basic OrderCloud entities required to support that scenario.

#### Create a buyer organization

::::codetabs
:::codetab{title="HTTP"}

```http
POST sandboxapi.ordercloud.io/v1/buyers HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "ID": "buyer1",
  "Name": "Buyer 1",
  "Active": true
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, Buyers } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
Buyers.Create({
  ID: "buyer1",
  Name: "Buyer 1",
  Active: true
})
.then(response => {
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, Buyers, Buyer, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const buyer: Buyer = await Buyers.Create({
  ID: "buyer1",
  Name: "Buyer 1",
  Active: true
})
.catch((err:OrderCloudError) => console.log(err));
console.log(buyer);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
Buyer response = await client.Buyers.CreateAsync(new Buyer {
  ID = "buyer1",
  Name = "Buyer 1",
  Active = true
});
```

:::
::::

##### Security profile

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/securityprofiles HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
{
  "ID": "buyerProfile",
  "Name": "Buyer Security Profile",
  "Roles": [
    "Shopper"
  ]
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, SecurityProfiles } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
SecurityProfiles.Create({
  ID: "buyerProfile",
  Name: "Buyer Security Profile",
  Roles: ["Shopper"]
})
.then(response => {
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, SecurityProfiles, SecurityProfile, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const securityProfile: SecurityProfile = await SecurityProfiles.Create({
  ID: "buyerProfile",
  Name: "Buyer Security Profile",
  Roles: ["Shopper"]
})
.catch((err:OrderCloudError) => console.log(err));
console.log(securityProfile);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
SecurityProfile response = await client.SecurityProfiles.CreateAsync(new SecurityProfile {
  ID = "buyerProfile",
  Name = "Buyer Security Profile",
  Roles = new ApiRole[] { ApiRole.Shopper }
});
```

:::
::::

##### Security profile assignment

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/securityprofiles/assignments HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "SecurityProfileID": "buyerProfile",
  "BuyerID": "buyer1"
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, SecurityProfiles } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
SecurityProfiles.SaveAssignment({
  SecurityProfileID: "buyerProfile",
  BuyerID: "buyer1"
})
.then(() => {
  // no response when security profile assigned
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, SecurityProfiles, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
await SecurityProfiles.SaveAssignment({
  SecurityProfileID: "buyerProfile",
  BuyerID: "buyer1"
})
.catch((err:OrderCloudError) => console.log(err));
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
await client.SecurityProfiles.SaveAssignmentAsync(new SecurityProfileAssignment {
  SecurityProfileID = "buyerProfile",
  BuyerID = "buyer1"
});
```

:::
::::

##### API client

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/apiclients HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "AccessTokenDuration": 600,
  "Active": true,
  "AppName": "Buyer Client",
  "RefreshTokenDuration": 43200,
  "AllowAnyBuyer": true,
  "AllowSeller": true
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, ApiClients } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
ApiClients.Create({
  AccessTokenDuration: 600,
  Active: true,
  AppName: "Buyer Client",
  RefreshTokenDuration: 43200,
  AllowAnyBuyer: true,
  AllowSeller: true
})
.then((response) => {
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, ApiClients, ApiClient, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const apiClient: ApiClient = await ApiClients.Create({
  AccessTokenDuration: 600,
  Active: true,
  AppName: "Buyer Client",
  RefreshTokenDuration: 43200,
  AllowAnyBuyer: true,
  AllowSeller: true
})
.catch((err:OrderCloudError) => console.log(err));
console.log(apiClient);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
ApiClient response = await client.ApiClients.Create(new ApiClient {
  AccessTokenDuration = 600,
  Active = true,
  AppName = "Buyer Client",
  RefreshTokenDuration = 43200,
  AllowAnyBuyer = true,
  AllowSeller = true
});
```

:::
::::

Record the ID from the response for OpenID Connect configuration.

### Configuring OIDC (OpenID Connect) via OrderCloud

#### Configure Azure

#### Create an Azure AD B2C tenant

If you haven't yet, you will need to create a new Azure AD B2C tenant. Follow [this tutorial](https://learn.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-tenant) for instructions.

#### Create a user flow

To keep things simple we're setting up azure with user flows but it will work with custom policies as well. Click on "User Flows"

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/28124bf6bdf5489b9ab0fba7f28d6f50.png)

For demo purposes we used the "Sign in" user flow but you can select whichever one makes sense for you. Any claims selected under "Application Claims" will be encoded into the ID token which is accessible during the `/createuser` and `/syncuser` endpoint.

#### Create an App Registration

Under "App Registrations" click on "New Registration"

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/a7aa62851959468cb7e8875a495da7e0.png)

Make sure you set Redirect URI to OrderCloud's `/ocrpcode` endpoint. Please note that the base URL for all OrderCloud endpoints vary by environment/region so make sure to check your marketplace for the correct value.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/6609f08fadae4e12a5cd7d57e9d46eb1.png)

Under "Overview" of your newly created app registration copy the "Application (client) ID", this will be your `ConnectClientID` in future steps.

While still under "Overview", click on "Endpoints"

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/12ae5a66eac54bfabd0d442e551a057d.png)

There are two values specifically we are interested in:

- Azure AD B2C OAuth 2.0 token endpoint (v2) - This will be your `TokenEndpoint`
- Azure AD B2C OAuth 2.0 authorization endpoint (v2) - This will be your `AuthorizationEndpoint`

You should replace `<policy-name>` with the name of the user flow you created previously.

Next, under "Certificates & secrets" create a new client secret. Copy the generated value, this will be your `ConnectClientSecret` in future steps.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/28349ff26a444f5aa772ff4cb729791d.png)

#### Start ngrok

You'll need a publicly available endpoint. You can use a tool called [ngrok](https://ngrok.com/) to let us do this locally without having to deploy anything. After installing ngrok run the command `ngrok http 3000`. This tells ngrok to expose our endpoint (not yet running) on `http://localhost:3000` to two public endpoints. After running the command copy either one of those URLs and record it, you'll need it for the next step.

We recommend to keep ngrok running. Restarting it will generate unique public endpoints and require you to update your configuration in OrderCloud.

1. Create OpenID Connect Integration Event:

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/integrationEvents HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "ID": "openidconnect",
  "Name": "openidconnect",
  "EventType": "OpenIDConnect",
  "CustomImplementationUrl": "{your-ngrok-url}/integration-events",
  "HashKey": "supersecrethash",
  "ElevatedRoles": ["BuyerUserAdmin"]
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, IntegrationEvents } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
IntegrationEvents.Create({
  ID: "openidconnect",
  Name: "openidconnect",
  EventType: "OpenIDConnect",
  CustomImplementationUrl: "{your-ngrok-url}/integration-events",
  HashKey: "supersecrethash",
  ElevatedRoles: ["BuyerUserAdmin"]
})
.then(response => {
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, IntegrationEvents, IntegrationEvent, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const integrationEvent: IntegrationEvent = await IntegrationEvents.Create({
  ID: "openidconnect",
  Name: "openidconnect",
  EventType: "OpenIDConnect",
  CustomImplementationUrl: "{your-ngrok-url}/integration-events",
  HashKey: "supersecrethash",
  ElevatedRoles: ["BuyerUserAdmin"]
})
.catch((err:OrderCloudError) => console.log(err));
console.log(integrationEvent);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
IntegrationEvent response = await client.IntegrationEvents.CreateAsync(new IntegrationEvent {
  ID = "openidconnect",
  Name = "openidconnect",
  EventType = IntegrationEventType.OpenIDConnect,
  CustomImplementationUrl = "{your-ngrok-url}/integration-events",
  HashKey = "supersecrethash",
  ElevatedRoles = new ApiRole[] { ApiRole.BuyerUserAdmin }
});
```

:::
::::

| OrderCloud property | Description |
| ---------- | ------------- |
| `ID` | Unique identifier for the integration event |
| `Name` | A short name describing the integration event, this is not user facing |
| `EventType` | Indicates what type of integration event this is, in our case we should use OpenIDConnect |
| `CustomImplementationUrl` | This indicates the base URL of your middleware where OrderCloud should post to. For OpenIDConnect it will call out to the pat `/createuser` and `/syncuser` |
| `HashKey` | This is an important security feature that is used by your middleware to validate that requests made to your endpoints are legitimate and come from OrderCloud |
| `ElevatedRoles` | An optional array of roles that will be encoded in the user's token and sent along in the payload to `/createuser` and `/syncuser`. In our case we are defining BuyerUserAdmin so that our middleware endpoints have the roles necessary to create users on the fly. | 

1. Create OpenID Connect configuration:

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/openidconnects HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "ID": "azure",
  "OrderCloudApiClientID": "CLIENT_ID_FROM_CREATING_API_CLIENT_STEP",
  "ConnectClientID": "CLIENT_ID_FROM_CONFIGURING_AZURE",
  "ConnectClientSecret": "CLIENT_SECRET_FROM_CONFIGURING_AZURE",
  "AppStartUrl": "http://localhost:3000?token={0}&idpToken={1}&refreshToken={3}",
  "AuthorizationEndpoint": "AUTH_ENDPOINT_FROM_AZURE",
  "TokenEndpoint": "TOKEN_ENDPOINT_FROM_AZURE",
  "UrlEncoded": false,
  "CallSyncUserIntegrationEvent": true,
  "IntegrationEventID": "openidconnect",
  "AdditionalIdpScopes": ["CLIENT_ID_FROM_CONFIGURING_AZURE"]
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, OpenIdConnects } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
OpenIdConnects.Create({
  ID: "azure",
  OrderCloudApiClientID: "CLIENT_ID_FROM_CREATING_API_CLIENT_STEP",
  ConnectClientID: "CLIENT_ID_FROM_CONFIGURING_AZURE",
  ConnectClientSecret: "CLIENT_SECRET_FROM_CONFIGURING_AZURE",
  AppStartUrl: "http://localhost:3000?token={0}&idpToken={1}&refreshToken={3}",
  AuthorizationEndpoint: "AUTH_ENDPOINT_FROM_AZURE",
  TokenEndpoint: "TOKEN_ENDPOINT_FROM_AZURE",
  UrlEncoded: false,
  CallSyncUserIntegrationEvent: true,
  IntegrationEventID: "openidconnect",
  AdditionalIdpScopes: ["CLIENT_ID_FROM_CONFIGURING_AZURE"]
})
.then(response => {
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, OpenIdConnects, OpenIdConnect, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const openIdConnect = await OpenIdConnects.Create({
  ID: "azure",
  OrderCloudApiClientID: "CLIENT_ID_FROM_CREATING_API_CLIENT_STEP",
  ConnectClientID: "CLIENT_ID_FROM_CONFIGURING_AZURE",
  ConnectClientSecret: "CLIENT_SECRET_FROM_CONFIGURING_AZURE",
  AppStartUrl: "http://localhost:3000?token={0}&idpToken={1}&refreshToken={3}",
  AuthorizationEndpoint: "AUTH_ENDPOINT_FROM_AZURE",
  TokenEndpoint: "TOKEN_ENDPOINT_FROM_AZURE",
  UrlEncoded: false,
  CallSyncUserIntegrationEvent: true,
  IntegrationEventID: "openidconnect",
  AdditionalIdpScopes: ["CLIENT_ID_FROM_CONFIGURING_AZURE"]
})
.catch((err:OrderCloudError) => console.log(err));
console.log(openIdConnect);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
OpenIdConnect response = await client.OpenIdConnects.CreateAsync(new OpenIdConnect {
  ID = "azure",
  OrderCloudApiClientID = "CLIENT_ID_FROM_CREATING_API_CLIENT_STEP",
  ConnectClientID = "CLIENT_ID_FROM_CONFIGURING_AZURE",
  ConnectClientSecret = "CLIENT_SECRET_FROM_CONFIGURING_AZURE",
  AppStartUrl = "http://localhost:3000?token={0}&idpToken={1}&refreshToken={3}",
  AuthorizationEndpoint = "AUTH_ENDPOINT_FROM_AZURE",
  TokenEndpoint = "TOKEN_ENDPOINT_FROM_AZURE",
  UrlEncoded = false,
  CallSyncUserIntegrationEvent = true,
  IntegrationEventID = "openidconnect",
  AdditionalIdpScopes = ["CLIENT_ID_FROM_CONFIGURING_AZURE"]
});
```

:::
::::

### Testing

1. Clone [openidconnect-nextjs](https://github.com/ordercloud-api/openidconnect-nextjs)
2. Install dependencies: `npm install`
3. Configure environment: Copy `.env.example` to `.env.local`
4. Start server: `npm run start`
5. Test: Navigate to `http://localhost:3000`

Review [/createuser and /syncuser endpoints](https://github.com/ordercloud-api/openidconnect-nextjs/tree/main/src/pages/api/integration-events) for implementation details.

### Troubleshooting

Common issue: "error validating token with authority"

- Verify configuration values:
  - `ConnectClientID`
  - `ConnectClientSecret`
  - `OrderCloudClientID`

## Implementing SSO with Google IDP

OpenID Connect is a powerful feature that enables you to provide single sign-on capabilities for any identity provider that supports the specification. In this tutorial we'll walk you step by step through what you'll need to get single sign-on working by using Google as the identity provider. By the end of this tutorial, you'll be able to sign in via Google and be logged into OrderCloud.

### Demo

Before we start, let's take a look at the finished product. Navigate to [this website](https://oidc-ordercloud-google.vercel.app/). You will be redirected to Google's sign-in page and after successfully signing in you should see your login details including:

- Currently authenticated user
- OrderCloud Access Token
- OrderCloud Refresh Token (if configured)
- Google ID Token

### Marketplace configuration

First, you need to access your Marketplace in the Sitecore Cloud Portal.

After accessing, take special note of the OrderCloud Base API URL, which identifies the base URL needed for all API requests.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/6faabb1567d8415c83cbb0ef941a24eb.png)

For this demonstration we are on the Sandbox environment in the region Us-West so our base API URL is <https://sandboxapi.ordercloud.io>, yours may look different.

### Create supporting entities

We will be creating a single-sign-on experience for buyer users specifically, so we'll create the most basic OrderCloud entities required to support that scenario.

#### Create a buyer organization

::::codetabs
:::codetab{title="HTTP"}

```http
POST sandboxapi.ordercloud.io/v1/buyers HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

```json
{
  "ID": "buyer1",
  "Name": "Buyer 1",
  "Active": true
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, Buyers } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
Buyers.Create({
  ID: "buyer1",
  Name: "Buyer 1",
  Active: true
})
.then(response => {
  // returns the newly created buyer organization
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, Buyers, Buyer, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const buyer: Buyer = await Buyers.Create({
  ID: "buyer1",
  Name: "Buyer 1",
  Active: true
})
.catch((err:OrderCloudError) => console.log(err));
console.log(buyer);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
Buyer response = await client.Buyers.CreateAsync(new Buyer {
  ID = "buyer1",
  Name = "Buyer 1",
  Active = true
});
```

:::
::::


#### Create security profile

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/securityprofiles HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

```json
{
  "ID": "buyerProfile",
  "Name": "Buyer Security Profile",
  "Roles": [
    "Shopper"
  ]
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, SecurityProfiles } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
SecurityProfiles.Create({
  ID: "buyerProfile",
  Name: "Buyer Security Profile",
  Roles: ["Shopper"]
})
.then(response => {
  // returns the newly created security profile
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, SecurityProfiles, SecurityProfile, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const securityProfile: SecurityProfile = await SecurityProfiles.Create({
  ID: "buyerProfile",
  Name: "Buyer Security Profile",
  Roles: ["Shopper"]
})
.catch((err:OrderCloudError) => console.log(err));
console.log(securityProfile);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
SecurityProfile response = await client.SecurityProfiles.CreateAsync(new SecurityProfile {
  ID = "buyerProfile",
  Name = "Buyer Security Profile",
  Roles = new ApiRole[] { ApiRole.Shopper }
});
```

:::
::::

#### Assign security profile

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/securityprofiles/assignments HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

```json
{
  "SecurityProfileID": "buyerProfile",
  "BuyerID": "buyer1"
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, SecurityProfiles } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
SecurityProfiles.SaveAssignment({
  SecurityProfileID: "buyerProfile",
  BuyerID: "buyer1"
})
.then(() => {
  // no response when security profile assigned
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, SecurityProfiles, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
await SecurityProfiles.SaveAssignment({
  SecurityProfileID: "buyerProfile",
  BuyerID: "buyer1"
})
.catch((err:OrderCloudError) => console.log(err));
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
await client.SecurityProfiles.SaveAssignmentAsync(new SecurityProfileAssignment {
  SecurityProfileID = "buyerProfile",
  BuyerID = "buyer1"
});
```

:::
::::

#### Create API client

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/apiclients HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

```json
{
  "AccessTokenDuration": 600,
  "Active": true,
  "AppName": "Buyer Client",
  "RefreshTokenDuration": 43200,
  "AllowAnyBuyer": true,
  "AllowSeller": true
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, ApiClients } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
ApiClients.Create({
  AccessTokenDuration: 600,
  Active: true,
  AppName: "Buyer Client",
  RefreshTokenDuration: 43200,
  AllowAnyBuyer: true,
  AllowSeller: true
})
.then((response) => {
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, ApiClients, ApiClient, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const apiClient: ApiClient = await ApiClients.Create({
  AccessTokenDuration: 600,
  Active: true,
  AppName: "Buyer Client",
  RefreshTokenDuration: 43200,
  AllowAnyBuyer: true,
  AllowSeller: true
})
.catch((err:OrderCloudError) => console.log(err));
console.log(apiClient);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
ApiClient response = await client.ApiClients.Create(new ApiClient {
  AccessTokenDuration = 600,
  Active = true,
  AppName = "Buyer Client",
  RefreshTokenDuration = 43200,
  AllowAnyBuyer = true,
  AllowSeller = true
});
```

:::
::::


Record the ID from the response for the OpenID Connect configuration.

### OpenID Connect configuration

#### Start ngrok

We'll need a publicly available endpoint. We can use a tool called [ngrok](https://ngrok.com/) to let us do this locally without having to deploy anything. After installing ngrok run the command `ngrok http 3000`. This tells ngrok to expose our endpoint (not yet running) on `http://localhost:3000` to two public endpoints. After running the command copy either one of those URLs and record it, we'll need when creating a new OpenID Connect.

We recommend to keep ngrok running. Restarting it will generate unique public endpoints and require you to update your configuration in OrderCloud.

#### Create integration event

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/integrationEvents HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

```json
{
  "ID": "openidconnect",
  "Name": "openidconnect",
  "EventType": "OpenIDConnect",
  "CustomImplementationUrl": "{your-ngrok-url}/integration-events",
  "HashKey": "supersecrethash",
  "ElevatedRoles": [
    "BuyerUserAdmin"
  ]
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, IntegrationEvents } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
IntegrationEvents.Create({
  ID: "openidconnect",
  Name: "openidconnect",
  EventType: "OpenIDConnect",
  CustomImplementationUrl: "{your-ngrok-url}/integration-events",
  HashKey: "supersecrethash",
  ElevatedRoles: ["BuyerUserAdmin"]
})
.then(response => {
  // returns the newly created integration event
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, IntegrationEvents, IntegrationEvent, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const integrationEvent: IntegrationEvent = await IntegrationEvents.Create({
  ID: "openidconnect",
  Name: "openidconnect",
  EventType: "OpenIDConnect",
  CustomImplementationUrl: "{your-ngrok-url}/integration-events",
  HashKey: "supersecrethash",
  ElevatedRoles: ["BuyerUserAdmin"]
})
.catch((err:OrderCloudError) => console.log(err));
console.log(integrationEvent);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
IntegrationEvent response = await client.IntegrationEvents.CreateAsync(new IntegrationEvent {
  ID = "openidconnect",
  Name = "openidconnect",
  EventType = IntegrationEventType.OpenIDConnect,
  CustomImplementationUrl = "{your-ngrok-url}/integration-events",
  HashKey = "supersecrethash",
  ElevatedRoles = new ApiRole[] { ApiRole.BuyerUserAdmin }
});
```

:::
::::

#### Configure Google

Follow [Google's instructions](https://developers.google.com/identity/protocols/oauth2/openid-connect) for setting up OpenID Connect configuration on their side. You'll need to set the authorized redirect URI to `{ordercloud_base_url}/ocrpcode`. Take note of the `clientID` and `clientSecret` which OrderCloud will refer to as `ConnectClientID` and `ConnectClientSecret` respectively, these values will be needed in the following step.

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/3047e1e44f5641b1a37d3edda6ca2a3e.png)

#### Create a new OpenID Connect

This entity configures the connection between Google and OrderCloud.

::::codetabs
:::codetab{title="HTTP"}

```http
POST https://sandboxapi.ordercloud.io/v1/openidconnects HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
```

```json
{
  "ID": "google",
  "OrderCloudApiClientID": "CLIENT_ID_FROM_CREATING_API_CLIENT_STEP",
  "ConnectClientID": "GOOGLE_CLIENT_ID_HERE",
  "ConnectClientSecret": "GOOGLE_CLIENT_SECRET_HERE",
  "AppStartUrl": "http://localhost:3000?token={0}&idpToken={1}",
  "AuthorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "TokenEndpoint": "https://oauth2.googleapis.com/token",
  "UrlEncoded": false,
  "CallSyncUserIntegrationEvent": true,
  "IntegrationEventID": "openidconnect",
  "AdditionalIdpScopes": []
}
```

:::
:::codetab{title="JavaScript"}

```javascript
import { Tokens, OpenIdConnects } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
OpenIdConnects.Create({
  ID: "google",
  OrderCloudApiClientID: "CLIENT_ID_FROM_CREATING_API_CLIENT_STEP",
  ConnectClientID: "GOOGLE_CLIENT_ID_HERE",
  ConnectClientSecret: "GOOGLE_CLIENT_SECRET_HERE",
  AppStartUrl: "http://localhost:3000?token={0}&idpToken={1}",
  AuthorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
  TokenEndpoint: "https://oauth2.googleapis.com/token",
  UrlEncoded: false,
  CallSyncUserIntegrationEvent: true,
  IntegrationEventID: "openidconnect",
  AdditionalIdpScopes: []
})
.then(response => {
  // returns the newly created openidconnect
  console.log(response);
})
.catch(err => console.log(err));
```

:::
:::codetab{title="TypeScript"}

```typescript
import { Tokens, OpenIdConnects, OpenIdConnect, OrderCloudError } from "ordercloud-javascript-sdk";

Tokens.Set("INSERT_ACCESS_TOKEN_HERE");
const openIdConnect = await OpenIdConnects.Create({
  ID: "google",
  OrderCloudApiClientID: "CLIENT_ID_FROM_CREATING_API_CLIENT_STEP",
  ConnectClientID: "GOOGLE_CLIENT_ID_HERE",
  ConnectClientSecret: "GOOGLE_CLIENT_SECRET_HERE",
  AppStartUrl: "http://localhost:3000?token={0}&idpToken={1}",
  AuthorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
  TokenEndpoint: "https://oauth2.googleapis.com/token",
  UrlEncoded: false,
  CallSyncUserIntegrationEvent: true,
  IntegrationEventID: "openidconnect",
  AdditionalIdpScopes: []
})
.catch((err:OrderCloudError) => console.log(err));
console.log(openIdConnect);
```

:::
:::codetab{title="C#"}

```csharp
using OrderCloud.SDK;

var client = new OrderCloudClient(...);
await client.AuthenticateAsync();
OpenIdConnect response = await client.OpenIdConnects.CreateAsync(new OpenIdConnect {
  ID = "google",
  OrderCloudApiClientID = "CLIENT_ID_FROM_CREATING_API_CLIENT_STEP",
  ConnectClientID = "GOOGLE_CLIENT_ID_HERE",
  ConnectClientSecret = "GOOGLE_CLIENT_SECRET_HERE",
  AppStartUrl = "http://localhost:3000?token={0}&idpToken={1}",
  AuthorizationEndpoint = "https://accounts.google.com/o/oauth2/v2/auth",
  TokenEndpoint = "https://oauth2.googleapis.com/token",
  UrlEncoded = false,
  CallSyncUserIntegrationEvent = true,
  IntegrationEventID = "openidconnect",
  AdditionalIdpScopes = []
});
```

:::
::::

### Testing

OrderCloud and Google should now be completely configured, and you are ready to test to make sure everything is working. To simplify this aspect, we've created a very minimal frontend to test this functionality.

1. Clone [this repository](https://github.com/ordercloud-api/openidconnect-nextjs)
2. Install dependencies by running `npm install` at the root of the project
3. Copy `.env.example` to `.env.local`
4. Run the project by running `npm run start`. This will start the server on port 3000. Remember ngrok is already listening to this port and will expose our endpoints publicly.
5. Navigate to the url `http://localhost:3000`. If everything is correct you should be redirected to Google's login page. Upon signing in you will be redirected back to the application and should see details about your logged in user

Be sure to look at the [/createuser and /syncuser endpoints](https://github.com/ordercloud-api/openidconnect-nextjs/tree/main/src/pages/api/integration-events)

### Common Issues

#### Error message: "error validating token with authority"

This issue occurs when OrderCloud attempts to retrieve the ID token from the IDP. This is generally a configuration issue. Confirm `ConnectClientID`, `ConnectClientSecret`, and `OrderCloudClientID` are correct.

---

## Related reading

- [Order fees](https://doc.sitecore.com/ordercloud/en/developers/platform/orders.html#order-fees)
- [Ad-Hoc Products](https://doc.sitecore.com/ordercloud/en/developers/platform/ad-hoc-products.html)
- [Using extended properties](https://doc.sitecore.com/ordercloud/en/developers/platform/extended-properties.html#using-extended-properties-in-custom-ecommerce-apps)

