SSO to External Applications

Single sign-on (SSO) signs a User into an external application when they select a configured MenuItem in intratool. intratool creates a short-lived, signed JSON Web Token (JWT); the receiving application verifies it, identifies the user, and creates its own session.

This page describes login from intratool into another application. Third-Party Login describes the reverse direction: login into intratool. This SSO mechanism uses a JWT link handoff and does not implement an OpenID Connect or SAML login flow.

Login Flow

1. An authenticated user selects a MenuItem configured for intratool SSO.

2. If the user is signed in through a group account and the menu item requires personal confirmation, intratool asks the person to confirm their identity with their personal intratool username and password.

3. intratool creates a signed JWT for the current user, or the personally confirmed user, when the navigation proceeds. The token expires five minutes after issuance.

4. intratool opens the configured target URL with the JWT in the agreed query parameter.

5. The receiving application validates the signature and claims, enforces single use, and maps the identifier to a user within the agreed customer account.

6. The receiving application establishes its own session and redirects to a URL without the token.

The token's lifetime limits when a login can be accepted. The receiving application controls the lifetime of the resulting session. This handoff does not provide automatic logout from the receiving application when the user logs out of intratool.

Setup

Arrange the integration with the intratool team for the relevant customer. Agree on the HTTPS login URL, identifier field, customer mapping, public verification key, display mode, and handling of group accounts before accepting logins. The standard RSA key size is 4096 bits; confirm the supplied customer's public key parameters during setup.

The identifier mapping applies to the customer's intratool SSO integration. It is not selected separately by each menu item or by a query parameter. The default identifier field is username; staff_number or email can be selected during setup. Changing the mapping can affect other menu items using this integration.

Identifier Mapping

The selected property is sent as sub. With staff_number configured, a staff number such as 0004711 is transmitted as "sub": "0004711". There is no separate staff_number claim. Preserve leading zeroes and match the identifier within the agreed customer account.

The staff number can be missing, and intratool's user validation does not require it to be unique. Ensure that identifiers are populated and uniquely assigned for the participating users. The receiving application must reject missing, empty, unexpected, or ambiguous identifiers instead of selecting an arbitrary account.

Name, email, language, and group_account are not additional claims in this handoff. Selecting email as the mapping field places the email address in sub; it does not add an email claim.

Group Accounts

The optional user_confirmation_required setting of the MenuItem enables personal user confirmation when opening a menu item from a group account. It defaults to false. When it is true, intratool asks the person using the group account to confirm their identity with their personal intratool username and password before continuing. Users already signed in with a personal account do not receive this additional prompt.

After successful confirmation, the SSO token uses the confirmed personal user's configured identifier as sub. With staff_number selected, this is the confirmed person's staff number. If confirmation fails or is cancelled, intratool navigation does not continue to the receiving application. The personal password is checked by intratool and is not included in the JWT or sent to the receiving application.

When personal confirmation is disabled, the menu item does not request this additional identification. If the active identity for the SSO request is the group account itself, intratool can issue a token for that account. The JWT contains neither a group_account claim nor a claim indicating that personal confirmation occurred.

For applications that require an individual person, enable personal confirmation for the menu item and use a verified mapping to individual accounts in the receiving application. Reject unknown or non-personal accounts; a missing staff number is not a reliable group-account indicator. If the receiving application needs an explicit group-account or confirmation claim, an extension of the token contract must be agreed before rollout.

Menu Link Configuration

An SSO MenuItem uses its link field as the target URL and integrationIntratoolSso as its type. An ordinary link item does not generate an SSO token. Configure the customer's SSO integration through the intratool team before using the menu item.

For the default parameter name, the link can be configured as:

https://learning.example.com/sso/login?tenant=example-customer

At the time of the click, intratool appends token while preserving the existing query parameters:

https://learning.example.com/sso/login?tenant=example-customer&token=<JWT>

For an explicit parameter name, use the System Variable {{ integration.token }} in the link:

https://learning.example.com/sso/login?tenant=example-customer&accessCredential={{ integration.token }}

The placeholder is replaced with the JWT, and no additional token parameter is appended. integration.token is available only while resolving the SSO menu item's link at click time. It is not a global variable for other fields, ordinary navigation rendering, or automation contexts.

These are example URLs for a receiving application, not intratool endpoints. Replace the host, path, customer reference, and parameter name with the agreed values. Parameters outside the JWT, including tenant, are not signed. A customer reference may select a preconfigured customer and verification key, but it must not independently establish the user's identity.

Token Format

The JWT uses the compact JWS format with the RS256 algorithm: RSA PKCS#1 v1.5 signatures with SHA-256. Its signature protects integrity and authenticity; the payload is readable and is not encrypted.

The protected header contains:

{
  "alg": "RS256"
}

The handoff does not send kid or typ header parameters.

Claims

Claim	Type	Meaning
iss	string	Issuer, always intratool. This value is shared across customers and is not a customer identifier.
aud	string	Hostname of the resolved target URL, such as learning.example.com. It does not include the scheme, port, path, or query string.
sub	mixed	Value of the configured user property. For username, staff_number, and email, expect a string or a missing value represented by null; require a non-empty string before accepting a login.
iat	integer	Issuance time as a Unix timestamp in seconds.
nbf	integer	Earliest acceptance time as a Unix timestamp in seconds; equals iat.
exp	integer	Expiration time as a Unix timestamp in seconds; equals iat + 300.
jti	string	A newly generated UUID for this token. The receiving application uses it to enforce single use.

The audience is a hostname, so paths or customer query parameters on the same host do not create different audiences. Bind the trusted verification keys and subject mapping to the expected customer in the receiving application.

Example Payload

The following decoded payload uses a synthetic staff number and illustrates a five-minute validity window, from January 1, 2026 at 12:00 UTC to 12:05 UTC.

{
  "iat": 1767268800,
  "nbf": 1767268800,
  "exp": 1767269100,
  "iss": "intratool",
  "aud": "learning.example.com",
  "jti": "4aaa8e51-a760-4c9e-b073-9b35422cb0e0",
  "sub": "0004711"
}

For signature verification and a complete login test, arrange a freshly issued test token and its matching public key with the intratool team during setup. The receiving application needs only the public key; intratool retains the signing private key.

Receiving Application Validation

The receiving application is responsible for verifying the JWT signature and claims before establishing a session. We recommend using a maintained JWT library for this purpose.

Validation covers the following checks:

1. Accept only RS256 and verify the signature against a public key already trusted for the expected customer. Do not accept a key or an algorithm merely because the incoming token requests it.

2. Require iss, aud, sub, iat, nbf, exp, and jti. Check iss against intratool and aud against the agreed target hostname.

3. Validate the time claims: reject expired tokens, tokens used before nbf, and an issuance time in the future. Expect nbf = iat and exp = iat + 300. Keep any clock tolerance small and explicitly configured.

4. Require a non-empty string identifier and resolve it unambiguously within the customer's account. Apply the receiving application's account eligibility rules, including any exclusion of non-personal accounts.

5. Atomically record the validated jti as consumed before creating a session. Reject a token whose ID has already been consumed, including simultaneous attempts. Scope this record to the customer and issuer, and retain it through the expiration time plus any accepted clock tolerance.

A jti is an identifier, not an automatic revocation mechanism. intratool issues the signed token; the receiving application owns the replay store and single-use enforcement. See the JWT specification and JWT Best Current Practices for validation guidance.

URL Handling

Use HTTPS for the handoff and avoid recording the token in reverse-proxy logs, application logs, analytics, error reports, or support screenshots. URL parameters can appear in logs, browser history, and referrer data even when the connection uses HTTPS. See OWASP's guidance on query-string exposure.

The receiving login endpoint should process the token before loading third-party resources, send Cache-Control: no-store and Referrer-Policy: no-referrer, and redirect to a URL without the token after validation. These controls reduce exposure; they do not replace signature, claim, and replay checks or retroactively remove a token from logs or browser history.

Public Keys and Rotation

Each tenant has its own RSA key pair. Its public key is exchanged and verified during setup through an agreed, authenticated channel. Keys are not rotated by default.

Any key change must be agreed with the intratool team in advance. No JWKS endpoint or kid header parameter is provided.

Browser and App Display

For an external SSO target in the web application, allow_iframe_access: false opens the destination in a new tab. allow_iframe_access: true requests display inside intratool in an iframe; the receiving application's framing policy and the browser must permit it. In the intratool app, the destination opens in a new WebView.

For iframe display, agree on the exact embedding origin for the customer's intratool instance, for example https://example-customer.intratool.de. The example is not an origin to allow without confirming the actual instance address. Configure the receiving application's CSP frame-ancestors accordingly and avoid conflicting framing restrictions.

When the iframe is cross-site, session cookies need SameSite=None; Secure; use HttpOnly for session cookies that do not need JavaScript access. Browsers can still restrict third-party cookies, so test the required browsers and the app. A new tab avoids this iframe-specific cookie dependency in the web application. See cookie attributes and third-party cookie restrictions.

Transferred Data

The SSO handoff sends the selected user identifier and the technical claims listed above to the receiving application through the user's browser when the menu item is selected. It does not transfer a password. Additional URL parameters configured on the menu item are separate data transfers and must be included in the agreed data inventory.

Data	Purpose
sub	Map the authenticated intratool user to an account in the receiving application; for example, a staff number.
iss and aud	Identify the token issuer and expected receiving hostname.
iat, nbf, and exp	Define issuance and the five-minute acceptance window.
jti	Identify a token for replay prevention.
Signature and alg	Allow verification that the token was signed with the trusted customer's key and has not been modified.