Higher Logic has created a JSON Web Token (JWT) Control (Common:Jwt:LinkOrButton) that allows a URL to be called with information securely passed in a token. Higher Logic uses a signed token that can verify the integrity of the claims contained within it. The JWT and the contained data isn’t encrypted, it is base64 encoded and signed using HmacSha256.
This can be used in a variety of ways to pass information about the logged in user from Higher Logic to a third-party application.
The token appended includes claims of:
- ContactKey - ID of the user in Higher Logic
- LegacyContactKey - ID of the user in the integrated CRM/AMS
- TenantCode - Client’s tenant ID
- FirstName - First name of the logged in user
- LastName - Last name of the logged in user
- EmailAddress - Email of the logged in user
- CommunityKey - The ID of the related community; only included if the user is coming from a specific community within a tenant.
Other static claims can be passed with the parameters of the control.
IMPORTANT: Starting in 2020, the Jwt:LinkOrButton control is only available to Higher Logic staff. If you need to use this functionality, please open a ticket with Higher Logic Support with the (1) name of the page (or pagecode) this control should be added to, (2) its location on that page, and (3) what its parameters should be.
Available parameters
- RedirectUrl - (Required) The destination URL of the 3rd party application.
Note: the equals sign can’t be used in the URL. If you need to pass values, please use the ExtendedClaimsJson parameter. - ProductId - A site admin can add the ProductId directly to the control without the query string parameter.
- IncludeProductId - (Default: False). When set to True and the ProductId is in the query string, the value will be used either on claims or as part of the RedirectUrl (UseProductIdInUrlPath=True).
- UseProductIdInUrlPath - (Default: False). When set to True AND "IncludeProductId" is set to True AND the ProductId is in the query string, the value will be added as part of the RedirectUrl.
- AutoRedirect - (Default: False) When set to true, automatically redirects to the page with the token. To use this control within a community to pass user information to a party, first create a new hidden page in the Higher Logic CMS.
- SecretName - (Required) The SecretName is stored in the Higher Logic Thrive Community (Thrive Community) site’s configuration table as a parameter with a prefix of “jwt_”. The parameter is a secret (with the HMAC algorithm) used to sign the JWT.
Use our JWT key generator to generate a secret key. The name should be associated with the vendor company or application. - ExpireMinutes - (Default: 20) The number of minutes the JWT is valid.
- ExtendedClaimsJson - a string of additional static values that can be passed as claims in the JWT. For example "[{'Name':'gid','Value':'200'},{'Name':'rid','Value':'524'}]"
- IsButton - (Default: False) True if the control is to be a button; False if it is a link.
- Text - The text to be displayed in the link or on the button.
- ButtonBootstrapClass - (Default: “btn-default”) Text field to define the CSS class of the button to be displayed.
- Target - (Default: “_self”) The target attribute of the link or button (i.e. “_blank”, “_top”, etc)
Example
For example, let's take a look at the Common:Jwt:LinkOrButton control with these parameters:
- RedirectUrl=https://hlqatestb.connectedcommunity.org/ross-test
- SecretName="jwt_marketingautomation"
- Text="Local Test"
- IncludeProductId="True"
- UseProductIdInUrlPath="True"
- AutoRedirect="False"
- ProductId="consume-jwt"
- ExtendedClaimsJson="[{'Name':'Ross','Value':'Boss'}]"
Using the parameters above would render on the page with the text “Local Test” as a hyperlink, and when clicked would send the user to:
https://hlqatestb.connectedcommunity.org/ross-test/consume-jwt?authtoken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJDb250YWN0S2V5IjoiN2YyZGU1NzEtOTJlOC00OWI
wLWJhMTItMjc0MTNiZjk5Yzk1IiwiTGVnYWN5Q29udGFjdEtleSI6IkhMMCIsIkZpcnN0TmFtZSI6IlN1cGVyTWF
uIiwiTGFzdE5hbWUiOiJXYXNIZXJlIiwiRW1haWxBZGRyZXNzIjoic3lzdGVtQGhpZ2hlcmxvZ2ljLm9yZyIsIlRlbm
FudENvZGUiOiJCIiwiUm9zcyI6IkJvc3MiLCJQcm9kdWN0SWQiOiJjb25zdW1lLWp3dCIsIm5iZiI6MTUyMDk2
MTAzMSwiZXhwIjoxNTIwOTYyMjMxLCJpYXQiOjE1MjA5NjEwMzF9.urt_x2LqwCkIMhSTyvU2gs7i1jcSwW1z8VllLVnDqMI
Note that the ProductID consume-jwt is included in the path of the URL, per the IncludeProductId UseProductIdInUrlPath parameters. The payload data contains:
{
"ContactKey": "7f2de571-92e8-49b0-ba12-27413bf99c95",
"LegacyContactKey": "HL0",
"FirstName": "SuperMan",
"LastName": "WasHere",
"EmailAddress": "system@higherlogic.org",
"TenantCode": "B",
"Ross": "Boss",
"ProductId": "consume-jwt",
"nbf": 1520961031,
"exp": 1520962231,
"iat": 1520961031
}
The extended claims for "Ross": "Boss" is also included in the JWT. This data set can be used to validate the current user and make subsequent API calls to get more information about the user, if needed.