> For the complete documentation index, see [llms.txt](https://api-docs.intratool.help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.intratool.help/introduction/authorization/sso-to-external-applications.md).

# SSO to External Applications

Single sign-on (SSO) signs a [User](/api-reference/users.md) into an external application when they select a configured [MenuItem](/api-reference/menu/menu-items.md) 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](/introduction/authorization/third-party-login.md) 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](/introduction/system-variables.md) `{{ 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:

```json
{
  "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.

```json
{
  "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](https://www.rfc-editor.org/rfc/rfc7519.html) and [JWT Best Current Practices](https://datatracker.ietf.org/doc/html/rfc8725) 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](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url).

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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie) and [third-party cookie restrictions](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Third-party_cookies).

## 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.       |