JWT

This page provides a simple example of how to configure Cloud CMS for JWT.

For a deeper explanation of Cloud CMS Single Sign On (SSO) and the role that JWT plays in it, please read our documentation on Single Sign On.

The example provided here is pretty simple. It is put together this way to keep things simple.

In practice, you'll make modifications to this approach depending upon the needs of your security and identity provider system.

JWT.IO

Let's generate a JSON Web Token.

Open up a browser to https://jwt.io and enter the following:

For the Header, enter the following:

{
  "alg": "HS256",
  "typ": "JWT"
}

This indicates that we should encode the JWT token using HMACSHA256 (HS256).

For the Payload, use the following:

{
  "iss": "test",
  "name": "John Doe",    
  "email": "john@doe.com",
  "firstName": "John",
  "lastName": "Doe"
}

These values are:

  • iss - the issuer of the JWT token. In this case, we set it to test
  • name - the name of the user
  • email - the email address of the user
  • firstName - the first name of the user
  • lastName - the last name of the user

In the Verify Signature section, set the your-256-bit-secret value to testsecret.

All in all, it should look something like this:

On the left-hand side, you should now see a generated JWT token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ0ZXN0IiwibmFtZSI6IkpvaG4gRG9lIiwiZW1haWwiOiJqb2huQGRvZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifQ.XmgvDhZlBsHA4pVdgXMWqoANkWrUkvpX9QIkk-qzGvM

Remember this token. You'll need to copy/paste it later.

Configure Cloud CMS

Now go into Cloud CMS. Log in as your admin or tenant owner and go to Manage Platform > SSO.

Select JWT and then set up your configuration more or less like this:

Where the following applies:

  • Set Token Type to Cookie
  • Set Token Name to MyCookie
  • Set Shared Secret to testsecret
  • Set Algorithm to HS256 (HMAC + SHA256)
  • Set Issuer to test
  • Set User Primary Identifier Field to email

These values should match what we use in the JSON Web Token.

And then, under User Field Mappings, add:

  • User Property firstName is mapped from firstName
  • User Property lastName is mapped from lastName
  • User Property email is mapped from email

Save your changes.

In this section, we'll assume you're using Google Chrome.

Make sure you're logged out of Cloud CMS and then go to:

http://demo.cloudcms.net:2999

Open up the Developers Console (Command + Option + I on the Mac). Then go under Applications and add a Cookie.

The cookie name should be MyCookie and its value should be the value of the JSON Web Token we produced earlier, shown here:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ0ZXN0IiwibmFtZSI6IkpvaG4gRG9lIiwiZW1haWwiOiJqb2huQGRvZS5jb20iLCJmaXJzdE5hbWUiOiJKb2huIiwibGFzdE5hbWUiOiJEb2UifQ.XmgvDhZlBsHA4pVdgXMWqoANkWrUkvpX9QIkk-qzGvM

Now point your browser one again to:

http://demo.cloudcms.net:2999

And you'll be automatically signed in. The JSON Web Token is picked up from the MyCookie cookie. It is decrypted and the properties contained inside of it are used to automatically sync a user into Cloud CMS. The user's name is John Doe as described by the JSON Web Token.

Examples

The following examples are provided to help aid folks setting up SSO using JWT. These involve suggested configurations of third party software and so your mileage may vary. Feel free to look at these for an idea of how to get started.

Using Apache Server / HTTPD

In this example, we'll look at using a custom URL (http://cms.mycompany.com) and a JWT token to automatically sign the user onto Cloud CMS. We'll use an Apache HTTPD Server instance and the mod_rewrite module to rewrite requests so that they arrive to the Cloud CMS with the JWT header applied.

Create the JWT Token

To start, let's create our JWT token. Go to https://jwt.io/ and fill things in like this:

Where the header is:

{ 
    "alg": "HS256", 
    "typ": "JWT" 
}

This specifies that we'll use HSA256 for encoding of our JWT token

The payload is:

{
    "iss": "myapp",
    "email": "joe@smith.com",
    "name": "joe",
    "firstName": "Joe",
    "lastName": "Smith"
}

This specifies that the JWT token was issued by myapp. The rest are properties of the user that are being asserted by the token.

For the signature, use the secret secret. It's simple. It's easy to remember. And gosh darn it, people like it.

Click on Share JWT and you'll generate the JWT token. In this case, it should be: 

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJteWFwcCIsImVtYWlsIjoiam9lQHNtaXRoLmNvbSIsIm5hbWUiOiJqb2UiLCJmaXJzdE5hbWUiOiJKb2UiLCJsYXN0TmFtZSI6IlNtaXRoIn0.o2CUXV_eBRLfkELmsNKjyd6R5wPEbzFiO6TUJSe5Njg

Write it down. No, just kidding. At least, keep it at hand, as we'll need to copy/paste it in a moment.

Configure SSO in Cloud CMS

In Cloud CMS, go to Manage Platform > SSO. Set the SSO type to JWT.

And then configure the following:

  • Token Type = Header
  • Token Name = CMS_SSO_TOKEN
  • Shared Secret = secret
  • Algorithm = HS256 (HMAC + SHA256)
  • Issuer = myapp
  • User Primary Identifier Field = email

Under the User Field Mappings section, add the following:

  • User Property firstName = Field Value firstName
  • User Property lastName = Field Value lastName
  • User Property name = Field Value name

This sets things up so that the JWT Payload Attributes will be picked up and sync'd to the Cloud CMS user's properties.

Configure Apache

Next, in your Apache HTTP configuration, make sure that you enable the following modules:

LoadModule proxy_module libexec/apache2/mod_proxy.so
LoadModule proxy_http_module libexec/apache2/mod_proxy_http.so
LoadModule rewrite_module libexec/apache2/mod_rewrite.so

Next, add a virtual host. It should look something like this:

<VirtualHost *:80>

  ServerName cms.mycompany.com
  ServerAlias cms.mycompany.com

  # Enable the mod-rewrite Module
  RewriteEngine On

  # Set JWT header
  RequestHeader set CMS_SSO_TOKEN "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJteWFwcCIsImVtYWlsIjoiam9lQHNtaXRoLmNvbSIsIm5hbWUiOiJqb2UiLCJmaXJzdE5hbWUiOiJKb2UiLCJsYXN0TmFtZSI6IlNtaXRoIn0.o2CUXV_eBRLfkELmsNKjyd6R5wPEbzFiO6TUJSe5Njg"

  # Rewrite to UI Server
  RewriteRule ^(.+)$ http://uiserver$1 [P,L]

</VirtualHost>

Where:

  • cms.mycompany.com is the host being redirected (i.e. browsers are making requests to http://cms.mycompany.com)
  • CMS_SSO_TOKEN is the name of the JWT header that will be applied
  • The value of the JWT token is the value you got from https://jwt.io.
  • The rewrite is to http://uiserver. Replace this with the location of your UI Server.

Restart your HTTPD server.

With that in place, any requests you make to http://cms.mycompany.com (provided that they connect to your Apache HTTP Server and your configuration was loaded) will have the JWT token set into the header. The request is then redirected to the UI Server and you will be automatically authenticated as the user described by the JWT token (Joe Smith).

Note: If you're running Cloud CMS on-premise in multi-tenancy mode, you will need to additionally set a header to indicate which tenant the request should be routed to. You can do so by setting the Host header, like this:

RequestHeader set Host "acme.mycompany.com"

You might ask - how do I pass different JWT tokens for different users? That is a decision that you must make. Our goal here isn't to suggest how you should implement your JWT-based security policy. The understanding is the user authentication and the decision of the JWT value to use is made upstream, somewhere else that is ahead of the request arriving to Cloud CMS.

The example here is meant to show how you can use Apache HTTPD to then apply that JWT token to the request and have Cloud CMS work seamlessly with it.