External Approvals Overview

The External Approvals option is a feature that allows external users (without a Heimdall account) to approve or deny sessions requested in the portal. To enable this, several prerequisites must be met.

Prerequisites

The first step is to make sure that portalMode is enabled. If it is, go to Notifications and specify which configured notifications should be used for External Approvals by checking the appropriate checkbox.

Next, assign such a notification config to the role which, when requested, will trigger emails being sent. You can configure this in Roles Management.

In the next step, go to Portal Basic and configure the following fields:

• Portal Host - used when sending emails to session approvers. The URL that approvers should open is included here.

• JWT Signature Key - used to sign and validate the token signature. The signatureKey must be provided in Base64Url format, and once decoded it must have a minimum length of 256 bytes. In its encoded form, only the characters A–Z, a–z, 0–9, -, _. You can also use secrets by setting the username and password fields. For example, set the token as the username and its value as the password. Note: The signature key does not support secret rotation at this time. Alternatively, you can generate the key by clicking the corresponding button.

Smtp Configuration still needs to be configured, since emails to external approvers are sent using this protocol.

JWT Token Handling for External Approvals

Once the above requirements are met, after requesting a session for the corresponding role, emails will be sent to the designated recipients. These emails include a link that contains a token. When accessed, the link allows approvers to approve or deny the session.

1. Using External Clients or API Consumers

• Clients (e.g., Java applications or automated scripts) using the external approval API must:
  • Store and send the JWT token explicitly in the Authorization: Bearer <token> header on requests to the external approval endpoints.
  • Avoid mixing JWT token usage with Basic Auth or session-based authentication requests to GUI endpoints in the same client instance, as this may cause session invalidation or authentication conflicts.
  • Maintain separate HTTP client instances or configurations for:
    • Stateful GUI requests (using Basic Auth and cookies)
    • Stateless external approval requests (using JWT)

You can approve or deny a session using curl:

Approve Session

curl -X POST "{$portalHost}/api/pending-approvals/{$sessionId}/approve" \
     -H "Authorization: Bearer {$token}"

---

Deny Session

You can deny a session using curl with JSON in the body:

curl -X POST "{$portalHost}/api/pending-approvals/deny" \
     -H "Authorization: Bearer {$token}" \
     -H "Content-Type: application/json" \
     -d '{
           "sessionId": {$sessionId},
           "denialReason": "{$denialReason}"
         }'

2. Important Notes

• Avoid storing the external JWT token in global browser storage (localStorage), as it will be attached to all requests on the domain, breaking GUI sessions.
• Use sessionStorage or in-memory variables to keep JWT tokens scoped to individual tabs or approval workflows.
• Backend security configuration separates GUI and external approval endpoints with distinct security filters to prevent session collisions.

---

If these guidelines are followed, both GUI users and external approvers can operate in parallel without session conflicts or authentication issues.