Edit this doc

SSO via OpenID Connect

Introduction

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.

PropertiesDescription
TokenEndpointA URL where agents can get a user-specific JSON web token
AuthorizationEndpointA URL where users enter their IDP credentials
ConnectClientIDRequired to access the urls above
ConnectClientSecretRequired to access the urls above

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

https://auth.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 - Upload Users

OrderCloud requires an existing user record for any user authenticating through a third party. Make sure the User ID matches that user's email as configured in the IDP. Resource permissions will be determined based on the intersection of the user's assigned roles and the requested roles just like normal OrderCloud authentication. Making these user records optional is a feature on the roadmap.

API Reference: Create a User

Step 2 - Create Connection Configuration

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

API Reference: Create an OpenID Connect Configuration

POST https://api.ordercloud.io/v1/openidconnects HTTP/1.1
Authentication: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

{
    "ID": "anormalordercloudid",
    "OrdercloudApiClient": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ConnectClientID": "…",
    "ConnectClientSecret": "…",
    "AppStartUrl": "https://mysinglpagebuyerapp.com/login?token={token}",
    "AuthorizationEndpoint": "…",
    "TokenEndpoint": "…",
}

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 {token} will be replaced with a valid Ordercloud token.

Implementing Login

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

https://auth.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. 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. They are logged in!

Deep Linking

You'll notice that a successful login via the OpenID connect flow will always send the user to your AppStartUrl.

This is not always desirable. For example, your marketing department might start sending out links to promotional products. Your user will click on one of these links and might need to log back in. Upon logging in your user will go to the home page instead of the originally intended link.

To handle this you can add an optional appStartPath query parameter to the ocrplogin url.

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

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

{AppStartUrl}/products/my-promotional-product