Authentication
How an extension authenticates depends on where its code runs:
| Where the code runs | How it authenticates |
|---|---|
| In the portal or Admin Console | The Extension SDK receives a token during the handshake. See Extension SDK JWT claims. |
| On a server, connected to an external service | The extension's OAuth application issues access and refresh tokens. See OAuth refresh tokens. |
Extension OAuth applications
Extensions that connect to external services use an OAuth application registered for that extension.
- An admin installs and configures the extension in the Admin Console.
- The integrator signs in through the OAuth flow once.
- GraFx Experience issues an access token and a refresh token.
- The integration uses the refresh token to get new access tokens.
This only applies to server-side integrations, not to end users signing in.
OAuth refresh tokens
Refresh tokens roll over, so integrations stay connected without signing in again.
| Rule | Detail |
|---|---|
| Validity | A refresh token is valid for 30 days. |
| Renewal | Each time you use it to get a new access token, it's valid for another 30 days. |
| Staying connected | Refresh before the 30 days run out and the integration keeps working. |
| Expiry | A refresh token unused for 30 days stops working. Go through the OAuth flow again to get a new one. |
| Reuse | Using a refresh token doesn't invalidate it. |
| Scope | Only for extension OAuth applications. User sign-in is not affected. |
| Revocation | Disabling or uninstalling the extension revokes its refresh tokens. |
Stay connected
Schedule your integration to refresh well before the 30 days run out, so a delayed run doesn't let the refresh token expire.
Extension SDK JWT claims
When your app connects through the Extension SDK, GraFx Experience issues a JWT with token_type set to extension_sdk. Your app receives it from connect(). Use its claims to validate the token and to see who the user is and which installation and extension it's for.
Standard claims
| Claim | Description |
|---|---|
iss |
Issuer: the identity provider URL. Use it to verify the token and find the keys (JWK set) to check the signature. |
aud |
Audience: the extension, for example ext:grafx-vdp. |
sub |
Subject: the user ID. |
exp |
Expiry time (Unix timestamp). |
iat |
Issue time (Unix timestamp). |
jti |
Unique token ID. |
Platform claims
| Claim | Description |
|---|---|
email |
Email address of the signed-in user. |
tenant_id |
ID of the installation (tenant). |
ext_id |
ID of the extension on this installation. |
ext_key |
Extension key, for example assets or grafx-vdp. |
token_type |
Always extension_sdk. |
scope |
OAuth scopes granted to the token. |
roles |
The user's roles. |
amr |
How the user authenticated. |
Role values
For what each role means, see Roles & permissions.
| Value | Role |
|---|---|
ROLE_USER |
User. Access to spaces and content through group permissions. |
ROLE_TENANT_ADMIN |
Admin. Access to the page editor and the Admin Console. |
ROLE_TENANT_OWNER |
Account Owner. Same access as Admin; one per installation. |
Use roles to show admin-only features only to ROLE_TENANT_ADMIN or ROLE_TENANT_OWNER.
Always validate the token
Check that iss is the issuer you expect, then verify the signature against that issuer's JWK set. Reject tokens from any other issuer, tokens whose aud is not your extension, and tokens past exp.
Example payload
{
"iss": "https://idp.kadanza.io",
"aud": "ext:assets",
"sub": "336ce6b4-ec7b-11ec-8179-7e7497b0126b",
"email": "user@example.com",
"tenant_id": "6c58d5a8-60f0-11f1-b6c7-2eaf6dc1d365",
"ext_id": "f3322f0e-6a21-11f1-8f7f-beee13e1b806",
"ext_key": "assets",
"token_type": "extension_sdk",
"roles": ["ROLE_USER"],
"exp": 1781689458,
"iat": 1781685858,
"jti": "626baa89-204e-4c74-8690-30544d7272cb"
}
The issuer URL differs per environment. Contact CHILI publish for the right iss value for development, UAT, and production.