Authentication

Sitecore Content Hub uses the OAuth 2.0 authorization framework for security. OAuth is an open standard for access delegation, commonly used as a way for Internet users to grant websites or applications access to their information on other sites but without giving these websites or apps the passwords. OAuth 2.0 provides authorization flows for web applications, desktop applications, mobile phones, and smart devices.

Note

External components have access to a pre-authenticated Content Hub JavaScript SDK client for sending HTTP requests to Sitecore Content Hub. The SDK provides dedicated clients for common operations, and a raw client for custom requests. For requests to third-party servers, you can use standard browser APIs such as Fetch.

Set up OAuth in Content Hub

To set up a connection to your project, create an M.OAuthClient entity in Content Hub.

Note

The RedirectUrl property is mandatory, but it's not relevant in this case. Any value can be provided.

To set up OAuth in Content Hub:

On the menu bar, click Manage .
On the Manage page, click OAuth clients.
If the SDK's M.OAuthClient entity is not in the list, click OAuth Client to add a new client.
In the Oauth Client dialog, enter the required M.OAuthClient entity values.
- Name
- Client ID
- Client Secret
- Redirect Url
From the Client Type drop-down list, click Client Credentials.
In the Users field, click Add and, in the User dialog, select a user, and then click Save.
In the OAuth Client dialog, click Save.

Tip

To edit an OAuth client, next to the client you want to edit, click Quick Edit . To delete the client, click Delete .

Password authentication

In addition to a ClientId and a ClientSecret, you specify a username and a password to authenticate with Content Hub from your project. The following is an example of a Content Hub authentication:

RequestResponse

import OAuthPasswordGrant from "@sitecore/sc-contenthub-webclient-sdk/dist/authentication/oauth-password-grant";
import { ContentHubClient } from "@sitecore/sc-contenthub-webclient-sdk/dist/clients/content-hub-client";

// Your Sitecore Content Hub endpoint to connect to
const endpoint = "https://your.m.endpoint.com";

// Enter your credentials here
const oauth = new OAuthPasswordGrant(
    "client_id",
    "client_secret",
    "username",
    "password"
);

// Create the JavaScript SDK client
const client = new ContentHubClient(endpoint, oauth);

// Authentication
// returns true when authentication succeeds.
// returns false or throws an error when authentication failed.

await client.internalClient.authenticateAsync();

The await client.internalClient.authenticateAsync() will return TRUE if the authentication is sucessful, or in the case of a failure, it will either return FALSE or throw an error.

The await expression can also be written as part of a function as follows:

RequestResponse

async function main() {
  await ...
} 
main();

When using await, be sure to either include a declaration for the Promise constructor or include ES2015 in your --lib option:

RequestResponse

// configuration using tsconfig.json
{
 "compilerOptions": {
  "lib": [
   "es2015"
  ]
 }
}

Alternatively, use the following code:

RequestResponse

tsc main.ts --lib ES2015

Client credentials authentication

Important

The client must be created with the Client type set to Client credentials.

When you set up OAuth in Content Hub, you can define multiple users in the Users field, however, for the purpose of authentication only the first one will be used, This means that all operations will be executed in the context of that user.

Tip

You can also create a dedicated service user account to use in the OAuth client, so that operations performed by a service are not linked to an individual user account.

The following code provides an example of the client credentials authentication:

RequestResponse

import OAuthClientCredentialsGrant from "@sitecore/sc-contenthub-webclient-sdk/dist/authentication/oauth-client-credentials-grant";
const oauth = new OAuthClientCredentialsGrant("client_id", "client_secret");

Refresh token authentication

Refresh token authentication can be used instead of a username and password authentication. In the refresh token authentication, it is important to subscribe to the IWebMClient.RefreshTokenReceived event. Instead of creating an OAuthPasswordGrant, change this to OAuthRefreshTokenGrant:

RequestResponse

import OAuthRefreshTokenGrant from "@sitecore/sc-contenthub-webclient-sdk/dist/authentication/oauth-refreshtoken-grant";

// Enter your credentials here
const oauth = new OAuthRefreshTokenGrant(
  "client_id",
  "client_secret",
  "refresh_token",
);

Do you have some feedback for us?

If you have suggestions for improving this article,