Delivery API JWT Authentication
Introduction
Goal
Use JSON Web Token (JWT) authentication to access a channel's preview data through the Delivery API.
Background
When accessing the Delivery API (formerly Page Model API) through a live endpoint, by default it will return a channel's published pages and content. In order to access unpublished pages and content and render the channel preview in the Experience manager, an external frontend application must authenticate using a JSON Web Token.
JWT-based preview channel authentication is built into the Bloomreach SPA SDK. Channel preview works out of the box with any SPA built on the SDK.
In case the SDK can't be used, for example when using an unsupported frontend technology or framework, the frontend application must implement the JWT authentication.
Preview Channel Authentication Using JWT
The URL for a channel's external frontend application is configured in the org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url property on a channel node. For example:
/hst:myproject/hst:configurations/myproject/hst:workspace/hst:channel/hst:channelinfo: jcr:primaryType: hst:channelinfo org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url: http://localhost:3000
When the Experience manager requests the preview channel for the first time, it appends the external frontend application's URL with a 'query' request parameter containing a JSON Web Token. For example:
http://localhost:3000/?token=xxxxx.yyyyy.zzzzz
In order to access the preview channel data through a Delivery API request, the frontend application must include this token in the Authorization header using the Bearer schema. For example:
Authorization: Bearer xxxxx.yyyyy.zzzzz
Configure a Different Header
The header used to communicate the token is configured in the HST container configuration properties file. The default is as follows:
jwt.token.authorization.header = Authorization
In case an implementation project already uses the Authorization header for a different purpose (for example, for Spring Security), a different header name can be configured. For example:
jwt.token.authorization.header = HST-Authorization
When using the SDK, the header name used to pass the authorization token can be configured by setting the authorizationHeader option in the initialize function (default value "Authorization").