Single Sign On via OpenID Connect

SSO (Single Sign On) allows your users to authenticate themselves to the OrderCloud API by logging into any identity provider you trust. For example, let shoppers save addresses and orders on your site by logging in with Google or Facebook. Or, save your customer service reps the hassle of one more login screen by providing a single sign on point through your ERP system.

OpenID Connect

Single sign on is made possible by OpenID Connect. The OpenID Connect protocol specifies a series of RESTful API exchanges between two parties, an Identity Provider (IDP) like Google and a Relying Party (RP) like OrderCloud. This guide will not describe that full protocol, instead it will teach you how to configure OrderCloud to to trust an IDP to provide user authentication.

Configuring Your Identity Provider (IDP)

Whether you are using a service like Google's API or you have written your own IDP implementation, OrderCloud will need the same four pieces of information from your IDP.

API Reference: Create an OpenID Connect Configuration

The Client ID and especially the Client Secret should be private. The URLs can be public, for example, Google's URLS. In turn, your IDP will need a piece of information from OrderCloud called an Authorized Redirect URI. Use the value

1https://sandboxapi.ordercloud.io/ocrpcode

This OrderCloud resource accepts the IDP's access token, converts it to an OrderCloud token, and then redirects users to the AppStartUrl you will specify in the next section.

Configuring OrderCloud (RP)

Step 1: Create an OpenID Connect Integration Event

OrderCloud requires an OpenID Connect Integration Event to be setup in order to use SSO via OpenID Connect. This will require hosting two endpoints, such as in your own middleware application. These endpoints are discussed in further detail below in the Configuring Your Integration Event Code section.

API Reference: Create an Integration Event

Step 2: Create Connection Configuration

Each connection configuration enables users to authenticate to one Ordercloud ApiClient through one IDP. The Ordercloud API supports normal CRUD operations on these configurations.

API Reference: Create an OpenID Connect Configuration

1POST https://sandboxapi.ordercloud.io/v1/openidconnects HTTP/1.1
2Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
3Content-Type: application/json
4
5{
6    "ID": "anormalordercloudid",
7    "OrdercloudApiClient": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
8    "ConnectClientID": "…",
9    "ConnectClientSecret": "…",
10    "AppStartUrl": "https://my-buyer-application.com/login?token={0}",
11    "AuthorizationEndpoint": "…",
12    "TokenEndpoint": "…",
13    "IntegrationEventID": "integrationeventID", // required for configs created after 03/31/2020
14    "CustomErrorUrl": "https://my-buyer-application.com/error?ErrorMessage={0}" // optionally redirect to a custom URL upon error
15}

The fields from the IDP will not be validated until a user attempts to log in, so testing is critical. The field AppStartUrl is used to redirect to your front-end app after login; the characters {0} will be replaced with a valid Ordercloud token.

Implementing Login

Users are now ready to authenticate. Link them to this URL

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

where <ID> matches the ID field of the configuration object above, <ApiClientID> matches the OrdercloudAPIClient field, and <Roles> is a space separated list of roles requested. Standard OrderCloud roles and custom roles are valid. Users will be redirected to an IDP route to provide credentials. If the credentials are valid, users will be redirected again to AppStartUrl with a valid Ordercloud token in the URL. Your front-end application will need to handle grabbing this token from the URL and storing it. But otherwise, they have been granted a valid OrderCloud access token!

Configuring Your Integration Event Code

The OpenID Connect Integration Event requires hosting two endpoints in your own application that will be triggered throughout the authentication flow.

/createuser Called after a user enters their credentials in the IDP for the first time while accessing your application. This endpoint will receive the following request body from OrderCloud:

1"ExistingUser": null,
2  "OpenIdConnect": {}, // your OpenID Connect configruation you created
3  "TokenResponse": {
4    "id_token": "eyJhbGciOiJSU...", // token from your IDP
5    "access_token": "ya29.a0ARrdaM92vGZsFj"
6  },
7  "Environment": "Sandbox",
8  "OrderCloudAccessToken": "eyJhbGciOiJSU...", // token of the default context user of your API Client for your middleware
9  "ConfigData": null

Using the token response from your IDP, you can decode the token and use the data provided to create a user in OrderCloud. After the user is created, this endpoint will need to send back the following response:

1{
2  "Username": "neworderclouduser", // username of the user created in OrderCloud
3  "ErrorMessage": null
4}

/syncuser (Optional) Called after a user enters their credentials in the IDP on subsequent attempts to access your application after having done so successfully at least once. This endpoint will only be called if CallSyncUserIntegrationEvent is true in your OpenID Connect config. It will receive the following request body from OrderCloud:

1"ExistingUser": {}, // existing OrderCloud user
2  "OpenIdConnect": {}, // your OpenID Connect configuration you created
3  "TokenResponse": {
4    "id_token": "eyJhbGciOiJSU...", // token from your IDP
5    "access_token": "ya29.a0ARrdaM92vGZsFj"
6  },
7  "Environment": "Sandbox",
8  "OrderCloudAccessToken": "eyJhbGciOiJSU...", // token of the default context user of your API Client for your middleware
9  "ConfigData": null

Using the token response from your IDP, you can decode the token and use the data provided to update the existing user in OrderCloud. After the user is update, this endpoint will need to send back the following response:

1{
2  "ErrorMessage": null
3}

Note that in any of the responses your application sends back to OrderCloud, populating ErrorMessage in your response will terminate the process.

Deep Linking

In some cases it may be desirable to redirect your user to a different part of your application upon logging in. For example, your marketing department might start sending out links to promotional products. Your user will click on one of these links and need to log in. Upon logging in your user will need go to the product detail page for that specific product instead of the home page.

To handle this you can add an optional appstartpath query parameter to the relying party login URL.

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

Then, modify your AppStartUrl to include {2} which will be replaced with whichever value you defined in appstartpath. Make sure the value you pass is url-encoded.

For example if I want to redirect users to /products/myawesomeproduct upon logging in then my relying party login URL would look like this:

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

And my AppStartUrl would look like this:

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

Now once login via OpenID is successful OrderCloud will redirect your user to the URL that resolves to:

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

IDP Token

In addition to retrieving OrderCloud's token it is also possible to get the IDP token for the user logging in. You may use this token to perform additional API calls to that IDP directly. To do this simply add {1} in your AppStartUrl, this will be replaced with the IDP token.

For example:

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

Now once login via OpenID is successful OrderCloud will redirect your user to the URL that resolves to:

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

OrderCloud Refresh Token

If you wish to retrieve the OrderCloud refresh token along with the OrderCloud token you can add refresh={3}. This will then be replaced with a valid OrderCloud refresh token.

For example:

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

Now once login via OpenID is successful OrderCloud will redirect your user to the URL that resolves to:

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

Note: You can only receive a refresh token if you have enabled your api client to allow refresh tokens by setting a refresh token duration.

Custom Error Redirect

If you wish to redirect a user to a custom page if an error occurs during authentication, you can add a value to CustomErrorUrl within your OpenID Connect Configuration.

If an error occurs, OrderCloud will redirect the user to that custom error url.

For example:

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

The error message {0} will be replaced with the error text from OrderCloud.

Custom Query Parameters to AuthorizationEndpoint

You are able to pass custom query parameters to the AuthorizationEndpoint. This can be useful if your identity provider has additional (optional) query parameters that can be set when calling the AuthorizationEndpoint. To do this, you can use the special query parameter customParams in the format customParams=value when building the GET /ocrplogin URL. Please note, the value must be URL encoded. For example one use case would be to pass in locale:

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

Still have questions?
Ask in our Community Channel

Content Powered By