Getting Started

Get started with Data Modeling

Before creating a data model, you need to create a project.

You can do that with the “Create Project” button on the organization page:

In the pop-up dialog you can give your project a name:

Next, you have to select a blueprint to work with:

Data modeling

Now you can start the data modeling by clicking the Data model menu item:

In the Data model tool you can model your business entities. You start by creating your first “Entity” by clicking the “Add Entity” button and give it a name.

Now that you created your first entity, you’ll see that you can still edit the name of the entity or delete it.

An entity can have attributes and relations to other entities. When you create an attribute in an entity a dialog will pop up with a few options:

Attribute options:

• Property Name: A unique name within the entity.
• Type: The data type for this attribute.
  • Text
  • Integer
  • Decimal
  • Boolean
  • Date
  • Content: Binary object or file
• Use as ID: This checkbox can be checked if you want the value of this attribute to be used as the identifier of the entity. This also means that the attribute must be unique, required and searchable.
• Values must be unique: When this checkbox is checked, the value for this attribute must be unique. Creating duplicate values will be prevented.
• Values are required: With this checkbox enabled, adding a value for this attribute is mandatory, otherwise the entity cannot be created.
• Values are searchable: Enabling this options makes sure that the values are indexed and therefore searchable.

You can also model relationships to other entities, or even to the same entity. To add a new relation to the entity, click the “Add Relation” button, and you will see a pop-up dialog:

When adding a relation, you have some options to configure:

• Name: The name of the relationship
• From: Will be prefilled with the current entity
• To: Entity where this relationship is going to
• Checkboxes:
  • Relationship is required
  • checkboxes to indicate the cardinality of the relationship

Permission Policies

Permission Policies

ContentGrid takes a different approach to permissions than legacy content management systems. Instead of making a complex hierarchical tree structure of permissions with inheritance, a set of permission policies describes access for each entity. These policies are rules that contain logical expressions, making use of (a combination of) entity attributes and user attributes.

How to create a Policy

First, go to the Permissions modeler:

To create our first policy, we first have to choose the entity for which we are going to create a policy:

When clicking the “Create Policy” button you will see the configuration options for creating a new policy:

First, you’ll have to choose for which operation this policy will be evaluated. The options are: Read, Create, Update, Delete. You can choose one or more operations.

By choosing the visibility setting, you can define if this policy is applicable for authenticated users only, or for all users.

The “Additional conditions” section is where you define the conditions for this policy, access to the entity is granted when the conditions are fulfilled.

Multiple conditions can be applied, and each rule has a left and a right side, that are compared to each other. Both left and right sides of can be a “user attribute”, “entity attribute” or constant. The possible comparisons between the left and the right side are:

• equals
• not equals
• greater than
• greater or equals
• less than
• less than or equals
• contains
• in

You can add more conditions with the “Add Condition” button. All conditions have to be satisfied before a policy grants access. Save the policy with the “Add Policy” button.

Now, you should see your policy for this entity in the overview.

Webhooks

Tutorial on webhooks

Webhooks are one way that ContentGrid applications can send automated messages or information to external systems. They are almost always faster than polling, and require less work on your end.

Each mutating operation on an resource is handled individually and is asynchronously, but almost immediately delivered to the configured webhook endpoint.

A ContentGrid Webhook

• is always attached to a ContentGrid entity and selected change triggers
• is delivered to a configured HTTP endpoint
• is delivered as a HTTP POST message with a body payload and specific ContentGrid HTTP headers

Create New Webhook?

First, go to the Webhooks modeler:

To create our first Webhook, we first have to click on Create Webhook:

When clicking the “Create Webhook” button you will see the configuration options for creating a new Webhook:

• First, you will have to give a satisfying Webhook name (or description).
• Then you have to choose for which entity this Webhook will be applied
• After the entity selection, select the notifications triggers, where the options are
  • create (whenever the selected entity type is created)
  • update (when each existing entity is being updated)
  • content (when a document content has been changed)
  • delete (when the enetity selected has been deleted)
• As a last step, you have to provide the Webhook URL to be invoked by your ContentGrid application

After clicking save, the Webhook is saved and is listed in the overview but will only be available to your ContentGrid runtime application once you create a new release.

You can add more Webhooks with the “Create Webhook” button.

Webhook endpoint

A Webhook endpoint has some specific constraints and must respect the following implementation details:

• it has to support the HTTP POST method
• should accept a JSON body and application/json Content-Type
• can use our ContentGrid HTTP headers in order to validate that the delivered message is coming from our platform
  • User-Agent value is ContentGrid-Slingshot/APP_VERSION
  • ContentGrid-Application-Id contains the application id
  • ContentGrid-Deployment-Id contains the deployment id
  • ContentGrid-Signature provides a JWT signed by the our platform that should be used in order that the message is actually sent by the ContentGrid platform

Security and validation

ContentGrid signs JWTs using asymmetric encryption (RS256), and publishes the public signing keys in a JWKS (JSON Web Key Set).

The signing keys are rotated on a regular basis.

• We discourage doing manual JWT validation since it might be easy to improperly implement and miss some important details that will lead to serious security vulnerabilities. Most JWT libraries take care of JWT validation for you.
• We also highly recommend to use a JWK library for the programming language of your choice.

One of the benefits of JSON Web Token (JWT) is that you can validate a token using an easy cryptographic operation.

What are JWKs?

A JSON Web Key (JWK) is a JSON data structure that represents a cryptographic key. JWKs are a set of keys shared between different services and are used to verify the JWT token from the authorization server.

You should only be validating the received JWT against ContentGrid Json Web Key (JWK) URL which is ${CONTENTGRID_URL}/.well-known/jwks.json

We use JWKS to expose the public keys used by the ContentGrid platform to all the clients required to validate signatures.

For more information you can check the JWK RFC

The example of a JWKS is something that looks like this:

{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "UVelusmvyM2xScEu0F_xSNlhelC5jZTD77R_3mmOZXs",
      "alg": "RS256",
      "n": "...yjXzcFpbMJB1fIFam9lQBeXWbTqzJwbuFbspHMsRowa8FaPw44l2C9Q42J3AdQD8CcN...",
      "e": "AQAB"
    },
    {
        ...
    }
  ]
}

In the above example some important fields are

• e: is the exponent for a standard pem
• n: is the moduluos for a standard pem
• alg: the signing algorithm.
• kid: a unique id for every key in the set.

ContentGrid’s JWT headers and claims:

{
  "kid": "UVelusmvyM2xScEu0F_xSNlhelC5jZTD77R_3mmOZXs",
  "alg": "RS256"
}.{
  "aud": "https://webhooks-demo.rtp-scw-sandbox.contentgrid.cloud/broker-process",
  "exp": 1679044765,
  "iat": 1679044465,
  "jti": "df475d5a-fc0e-4fca-a03a-c279e86fe9ed"
}.[Signature]

• kid: is Identifier of the static key used to sign the JWT
• alg: Algorithm used to sign the key
• aud: Recipients that the JWT is intended for (the CG Application URL)
• iat: The issuing time of the token in seconds
• exp: The expiration time of the token in seconds
• jti: Unique identifier of the token

Get the signing keys

Here is a Java exmaple of how to validate a JWT using JWKs with Nimbus JOSE + JWT

• To validate the token, first, you need to get the JSON web key set from the JWKs endpoint. The token will be received as JSON in the validation endpoint in the body.

ResourceRetriever jwkSetRetriever = new DefaultResourceRetriever();
JWKSource<SecurityContext> jwkSource = new RemoteJWKSet<>(URI.create("${CONTENTGRID_URL}/.well-known/jwks.json").toURL(), jwkSetRetriever);
JWSKeySelector<SecurityContext> jwsKeySelector = JWSAlgorithmFamilyJWSKeySelector.fromJWKSource(jwkSource);

• Additional validation for token claims

ConfigurableJWTProcessor<SecurityContext> jwtProcessor = new DefaultJWTProcessor<>();
jwtProcessor.setJWSKeySelector(jwsKeySelector);

jwtProcessor.setJWTClaimsSetVerifier((claims, context) -> {
	final Date now = new Date();			
	final Date exp = claims.getExpirationTime();
	if (exp != null) {
		if (now.after(exp)) {
			throw new BadJWTException("expired");
		}
	}
});	

• and the JWT validation

SignedJWT signedJWT = SignedJWT.parse(THE_JWT);	
jwtProcessor.process(signedJWT, null);

This short guide provides the basic steps required to locally verify an access or ID token signed by ContentGrid. It uses packages from Nimbus JOSE + JWT for key parsing and token validation, but the general principles should apply to any JWT validation library.