Authentication

🚧

Important

Before you set up authentication for the Cleverbridge GraphQL API, you MUST register with Client Experience.

For more information about the registration process, see below.

The Cleverbridge GraphQL API uses the open-source OpenID Connect framework for authentication. It allows Cleverbridge to not only verify your identity using our identity server, but also obtain basic profile information which we then use to grant you an access token for the API.

OpenID Connect allows clients of all types, including web-based, mobile, and JavaScript clients, to request and receive access tokens.

The following describes how to set up authentication for the Cleverbridge GraphQL API and two types of clients that you can use to authenticate.

📘

Note

Our Security Policies ✱ apply to the technical users Cleverbridge sets up in the platform. As per these policies, users are locked out after three failed login attempts.

Set up Authentication (Application-to-API Integration)

Integrate our implicit authentication flow into your application to communicate with the Cleverbridge GraphQL API. To do so, complete the following:

1. Decide what type of client you would like to use to request and receive access tokens from our identity server.
2. Register to use the CleverbridgeGraphQL API. To do so, contact Client Experience and provide them with the following information:

• ID of your client application (client_id) that you will be using to communicate with our identity server

❗️

Warning

This is NOT your Cleverbridge client account ID (client_id).

• Your redirect URL
• Your postlogout URL

3. Set up your client application to authenticate using the OpenId Connect implicit flow. To do so, you need the information that you provided in step 2, and the information that you received from Cleverbridge after your registration. This includes:

For a full description of the OpenId Connect implicit flow, see Implicit Flow.

4. Test the authentication process using your client application. If you have any questions during this process, contact Client Experience.

Set up Authentication (Back-End-to-API Integration)

Integrate our client-credential authentication flow into your backend to enable your backend to communicate directly with the Cleverbridge GraphQL API. To do so, complete the following:

1. In the Commerce Assistant, go to Setup > Add User and set up a Cleverbridge user specifically for authentication purposes:

• Enter a Username in the format .GQL..
• Select the API User privilege for the user.
• Set up one user for each context in which you will use the GraphQL API.

Example

Shieldware Inc. uses the GraphQL API for monitoring purposes. They set up a new user in the Commerce Assistant, naming it Shieldware.GQL.Monitoring.

For more information on how to set up users, see Users ✱.

2. Contact Client Experience and provide them with the name of the Cleverbridge user that you will use to authenticate.
3. Assign any additional privileges to your Cleverbridge user that you may need for your API calls. For example, if your back-end needs to access purchase information, you or your administrator should assign a privilege that provides full access to purchase-related features. For more information, see Privileges ✱.
4. Set up your backend to authenticate using the client-credential flow. To do so, you need to send an HTTP POST request to the Cleverbridge IDentity server using the following information:

📘

Note

With Basic Auth, theclient_id is used as the username and the client_secret is used as the password.

If authenticated, the Cleverbridge IDentity server responds with an access token in JSON Web Token (JWT) format:

{
 "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjNmMWI0MTc1OGU0NzM3ZmI[...]",
 "expires_in": 3600,
 "token_type": "Bearer"
}

5. Test the authentication process using your backend. If you have any questions during this process, contact Client Experience.

Application-to-API Authentication Using a JavaScript Client

Build a browser-based JavaScript client application to integrate with the Cleverbridge GraphQL API. For an example of how to build such an application, see Adding a JavaScript client.

A user integrated with the Cleverbridge GraphQL API by building a browser-based JavaScript client application. During the authentication process, the following tasks were performed:

1. The user's JavaScript client sends a login request to the Cleverbridge IDentity server. The login request is made possible through specifically-configured HTML and JavaScript files, which include the user's client app ID (client_id). For an example, see Add your HTML and JavaScript files.
2. The Cleverbridge IDentity server authenticates the user and obtains authorization.
3. The Cleverbridge IDentity server issues an access token, which allows the user to access the Cleverbridge GraphQL API. The token is valid for one hour.
4. The user's JavaScript client retrieves the access token, which it resubmits to the identity server, along with the Authorization header and Bearer scheme that are contained within the JavaScript file (see step 1 above). The user can now send a request to the Cleverbridge GraphQL API.
5. Cleverbridge validates the access token. Once validated, Cleverbridge sends an API response to the user.
6. The user's JavaScript client sends a logout request to the Cleverbridge IDentity server. The logout request is contained within the JavaScript file (see step 1 above).

Application-to-API Authentication Using a ReactJS App

Another method of integrating with the Cleverbridge GraphQL API is using a ReactJS app. There are a number of open-source tools that you can use to build this connection, including react-openidconnect and redux-oidc.

Backend-to-API Integration Using a PHP HTTP Client

One method of integrating the Cleverbridge GraphQL API into your back-end is using an HTTP client for PHP. The example below uses the PHP library Guzzle.

Example

Shieldware, Inc., adds x-parameters to their order URLs to track their sources of revenue. They want to use the GraphQL API to pull the data stored in the x-parameters into their internal reporting system. For this purpose, they build an HTTP client for PHP.

<?php
$username = Shieldware.GQL.SubscriptionManagement;
$password = test123!;
$query = 'query subParam($id: Int!){
  subscription(id: $id) {
    id
    extraParameters {
      key
      value
    }
  }
}';
$subscriptionid = 23431030;
$arguments = ['id' => $subscriptionid];

public function graphql($username, $password, $query, $arguments = null)
{
  //Send a login request to the Cleverbridge IDentity server. Use the username and password of the Cleverbridge user that you set up for GraphQL authentication.
  $client = new GuzzleHttp\Client(['base_uri' => 'https://identity.cleverbridge.com']);
  $request = ['headers' => ['Accept' => 'application/x-www-form-urlencoded'], 'form_params' => ['grant_type' => 'client_credentials', 'client_id' => $username, 'client_secret' => $password]];
  //Retrieve the access token returned by the identity server upon successful authentication and authorization.
  try
  {
    $response = $client->request('POST', '/connect/token', $request);
  }
  catch(GuzzleHttp\Exception\RequestException $e)
  {
    if ($e->hasResponse())
    {
      $body = $e->getResponse()
        ->getreasonPhrase();
      $message .= PHP_EOL . 'Response: ' . $body;
    }
    return false;
  }
  $token = json_decode($response->getBody()
    ->getContents())->access_token;
  if (!isset($token))
  {
    $message .= PHP_EOL . 'Token not generated';
    return false;
  }

  //Send a request to the GraphQL server, passing the access token in the Authorization header. Define separate variables for the query string and the arguments associated with the query.
  $client2 = new GuzzleHttp\Client(['base_uri' => 'https://graph.cleverbridge.com']);
  $request = ['headers' => ['Authorization' => 'Bearer ' . $token, 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], 'body' => json_encode(['query' => $query, 'variables' => $arguments]) ];
  $message .= PHP_EOL . $request['body'];

  //Retrieve the response returned by the GraphQL server upon successful validation of the access token.
  try
  {
    $response = $client2->request('POST', '/graphql', $request);
  }
  catch(GuzzleHttp\Exception\RequestException $e)
  {
    if ($e->hasResponse())
    {
      $body = $e->getResponse()
        ->getreasonPhrase();
      $message .= PHP_EOL . 'Response: ' . $body;
    }
    return false;
  }
  $response = json_decode($response->getBody()
    ->getContents());
  if (isset($response->errors))
  {
    $message .= PHP_EOL . 'Response: ' . $response->errors[0]->message . ' ' . $response->errors[0]->code;
    return false;
  }
  return $response;
}
?>

Authenticate Your Requests

To authenticate your requests to the GraphQL API, you must pass the generated access token with each request. The GrapQL API uses OAuth 2.0 for authentication and authorization, and the Bearer authentication scheme. Here is an example of what a request looks like:

curl --location --request POST 'https://graph.cleverbridge.com/graphql' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjNmMWI0MTc1OGU0NzM3ZmI[...]' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query {        subscription(id: 23431030) {            id            extraParameters {                key                value            }        }}","variables":{}}'

Our GraphQL server validates the access token. If the server finds the access token to be valid, the request is allowed to proceed. Requests made with an invalid token receive a 401 Unauthorized error code.