Programmatical Share Access token

To ensure a seamless experience for our customers, we introduce the ability to programmatically auto-login to Password Protected External Share links. This will eliminate the need to manually enter the password and restrict access to the Confluence page exclusively through our system via iFrame to for example create an online user guide. To achieve that, we use JWT (JSON Web Token).

How to Use It?

1. Obtaining the Unlock Secret

Every share comes equipped with an Unlock Secret, which is essential for creating a share access token.
The Unlock Secret is a hex-encoded string, crafted from 32 randomly assorted bytes.

Accessing the Unlock Secret

• Via the user interface:

  • Go to the share’s configurations page

  • Ensure that the ‘Protect link with password’ option is enabled under the security tab

  • Here, you can locate and access the unlock secret

    

    Unlock secret is a read only value which can be copied, or regenerated.

• Via the API:

  • The “unlockSecret” field is returned as part of the response payload when invoking the GET method on the endpoint:
    GET https://confluence.external-share.com/webapi/share/{SHARE_UUID}
    This is detailed in our API documentation: https://docs.warsawdynamics.com/content/37018/external_share_for_confluence_documentation/115671152/115671872#API-GETOPERATION

2. Creating JWT

Once you have obtained the Unlock Secret, you can proceed to create a JWT to access shares without manually entering a password.

JWT unlocking share: Required components

• Standard header:

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

• Payload:

  {
    "iss": "a8b63c1d-3a37-428b-c807-2ffeabbaa647", // UUID of the share
    "nbf": 1698133085, // Token valid from (Unix time in seconds)
    "exp": 1698133175  // Token expiration (Unix time in seconds)
  }

• Signature:
  The Unlock Secret value, converted to bytes. In UI and API it is presented in hex format.
  For instance, when using a linked JWT creator website, select ‘Key encoding: HEX’ for this conversion.

Example of creating JWT using linked website:
With Java example of creating nbf and exp.

After filling data you have to click left arrow to generate JWT.

3. Using JWT Share Access token

Now, as you already have the JWT token, for a password-protected link, append ?unlock parameter to the URL as follows:

https://confluence.external-share.com/content/{UUID}?unlock={jwt}

On successful JWT validation, we are adding the same cookie as the page would have been accessed using password, so no need for using unlock token with every page visit.