1 Configuration
External resources are configured in the configuration files:
// configure custom resource with key "myresourcekey" $CUSTOM_PROXY["myresourcekey"] = array( "baseUrl" => "http://myresource/basepath/{{param}}", "methods" => array( "GET", "POST" ), "permission" => array( "type" => 90001, "id" => 1 ), "headers" => array( "Authorization" => "Bearer <token>" ), "parameters" => array( "param" => array( "default" => "path", "values" => array("path", "otherpath") ) ), "proxy" => array( "host" => "internal.proxy", "port" => 4711 ), "jwt" => array( "enabled" => false, "prefix" => "" ) );
Property | Description | Mandatory |
---|---|---|
baseUrl | Base URL of the accessed resource. | yes |
methods | Optional list of allowed HTTP methods. Possible values are DELETE, GET, HEAD, OPTIONS, POST, PUT | no |
permission | GCMS Permission required for accessing the resource. | no |
headers | Optional list of request headers that will be added by the Proxy | no |
parameters | Optional parameters configuration. Parameters can be passed to the proxy as query parameters and will replace {{placeholder}} in the baseUrl. | no |
proxy | Optional HTTP proxy configuration | no |
jwt | Settings for adding JWT to the forwarded request | no |
jwt.enabled | Flag for enabling JWT | no |
jwt.prefix | Optional prefix for username and group names in the claims | no |
2 REST Endpoint
The base URL for the proxy is http(s)://[gcms.hostname]/CNPortletapp/rest/proxy/[key]
where [key]
is the configuration key of the resource.
Any path after the [key]
section will be appended to the configured baseUrl
.
All headers and query parameters sent to the proxy endpoints will be forwarded to the external resource.
3 JWT
By enabling the flag jwt.enabled on a custom proxy, the CMS will add a Authorization: Bearer token header containing a signed JSON Web Token (JWT) to each forwarded request.
The JWT will be signed with the private key of the CMS (using algorithm RS256), which is created (when is does not exist) upon CMS start and stored as file /Node/tomcat/conf/gentics/private-key.jwk
.
The public key, which can be used to verify the signature can be obtained via the REST API by calling
GET http(s)://[gcms.hostname]/CNPortletapp/rest/admin/publicKey
The JWT will contain the following claims:
Property | Description |
---|---|
sub | Login name of the user (optionally prefixed) |
preferred_username | Login name of the user (optionally prefixed) |
given_name | First name of the user |
family_name | Last name of the user |
Email address of the user | |
gcms_groups | List of group names, the user is member of (optionally prefixed) |
iss | “Gentics CMS” – to identify the JWT issuer |
iat | Current timestamp as “issued at” value |
Example JWT:
{ "sub": "node", "preferred_username": "node", "given_name": "Node", "family_name": "Admin", "email": "nowhere@gentics.com", "gcms_groups": [ "Demo", "Node Super Admin" ], "iss": "Gentics CMS", "iat": 1584453152 }