Authentication

CKBox, like other CKEditor Cloud Services, uses JWT tokens for authentication and authorization. All these tokens are generated on your application side and signed with a shared secret that you can obtain in the CKEditor Ecosystem dashboard. CKBox is a commercial product and in order to use it, you need to obtain a license. The access credentials required to configure the tokenUrl can be found in the CKEditor Ecosystem dashboard.

# Creating access credentials

To obtain the access credentials required to create the token endpoint, please log in to the CKEditor Ecosystem dashboard, and navigate to “Your products » Cloud Services”.

# Website environment

To obtain access credentials, first, you have to choose the environment. Environments are independent spaces for your data, and you can create any number of them. From the list of environments select the one that you want to manage or create a new one.

# Access credentials

Next, go to the “Access credentials” tab and click the “Create a new access key” button.

The modal will show up and will prompt for a name for the new access key. Provide the name and click the “Save” button.

The newly created access key will be present on the list of access keys.

The value of the new access key will be hidden. To show the value, click the “Show” button in the “Actions” column.

For your safety, the access key value will disappear in a few seconds. You will be able to display it again by clicking the “Show” button. Make sure to keep the access credentials in a safe place.

Here you can see the complete information required to sign tokens created by your token endpoint: the environment ID and the access key:

To read more about the concept of environments, please refer to the Environments management article.

# Token endpoint

With the environment and access credentials ready, you can create a security token endpoint. The role of this endpoint is to securely authorize end users of your application to use CKEditor Cloud Services only if they should have access to the content or action they are requesting.

Below are implementation examples in various languages:

• ASP.NET
• Java
• Node.js
• PHP
• Python

We highly recommend using the libraries listed on jwt.io to create the token.
If you encounter problems creating the token endpoint in another server-side language, or if you have any other suggestions regarding the documentation, please contact us.

# Development token endpoint

If you are just starting, you may use the development token endpoint URL which is available out of the box and requires no coding on your side. The URL of the development token endpoint can be obtained easily in a few simple steps:

From the list of environments select the one that you want to manage or create a new one.

After choosing the environment, press the “Generate” button in the “Development token URL” section of the “CKEditor configuration” tab:

The development token URL will show up in the “Development token URL” section:

# Token payload

Payload properties

The following properties must be included in the JWT token payload:

• aud – The environment ID, which is the identifier of the environment created in the CKEditor Ecosystem Dashboard.
• sub – The user ID, which is the unique identifier of the user for whom the token is issued.
• iat – A timestamp the token was issued at. Make sure that iat is present and contains the correct time stated in seconds. Some JWT implementations do not include it by default. Additionally, the system time may be invalid, causing strange issues with tokens (see, for example, Docker for Mac time drift).
• auth – An object defining the user’s role. Allowed values are user for regular users and admin for administrator users.

The payload example below will enable access to CKBox as administrator:

{
    "aud": "NQoFK1NLVelFWOBQtQ8A",
    "iat": 1511963669,
    "sub": "example-user-id",
    "auth": {
        "ckbox": {
            "role": "admin"
        }
    }
}

# User roles

CKBox users are divided into two groups: regular users and administrators. Regular users can use all the features of the application allowing for file management (uploading, renaming, removing, etc.). Administrators additionally have access to the administration management panel, which allows configuring various aspects of the CKBox environment, like the available categories, their allowed extensions, and the quality of responsive images.

The user role is defined by setting an appropriate value in the auth.ckbox.role field of the token payload:

• if you want the user to be an administrator, set auth.ckbox.role to admin

  "auth": {
      "ckbox": {
          "role": "admin"
      }
  }
  

• for the regular user, auth.ckbox.role should be set to user

  "auth": {
      "ckbox": {
          "role": "user"
      }
  }
  

The premium permissions feature lets the integrator assign permissions to regular users. It allows greater control over access and asset management rights.