SSO Integration

This is an old revision of the document!

T4 supports single sign-on (SSO) so your users can log in with your own identity provider (IdP) using OpenID Connect (OIDC) instead of a T4 password. Your application obtains an OIDC token from your IdP and sends it in the T4 login request; T4 validates the token and maps it to the matching T4 user.

Integrating SSO involves three parts:

Tell us about your identity provider so we can register it and assign it to your firm.
Link each T4 user to their identity in that provider, using the standard user endpoints.
Send the OIDC token at login from your application instead of a password.

Note: Registering a provider and assigning it to a firm are performed by T4 CTS Admin. As an integrator you supply the provider details once, then set the per-user link for each user through the onboarding and user endpoints described below.

Protocol: OpenID Connect (OIDC) over OAuth2.
Providers: Okta, Microsoft Entra ID (Azure AD), AD FS, Ping Identity, Google, Keycloak, or any standards-compliant Generic OIDC provider.
Validation: T4 validates each token's signature (against your published JWKS), issuer, and expiry. Tokens must be signed with a key advertised at your JWKS endpoint.

Send the following to T4 once per identity provider. The same provider can be reused across multiple firms on the same IdP.

Item	Description
Name	A short label for the provider, e.g. `Acme Corp Okta`.
Vendor	Okta, Entra ID, AD FS, Ping Identity, Google, Keycloak, or Generic OIDC.
Issuer URL	The `iss` value your IdP places in its tokens, e.g. `https://acme.okta.com/oauth2/default`.
JWKS URI	The URL of your JSON Web Key Set. Always listed under `jwks_uri` in `{issuer}/.well-known/openid-configuration`.
Subject claim	The claim that uniquely identifies a user. Use `sub` for most providers; use `oid` for Entra ID.

Important: The Issuer URL must match the iss claim in your tokens exactly, including any trailing slash. A mismatch causes every login to be rejected.

Once you send these, T4 registers the provider and assigns it to your firm. For reference, the registration T4 performs on your behalf is:

POST https://api.t4login.com/admin/v1/identity-providers

{
  "name": "Acme Corp Okta",
  "vendorType": 1,
  "protocol": 1,
  "issuer": "https://acme.okta.com/oauth2/default",
  "subjectClaimName": "sub",
  "providerDetailsJSON": "{\"JwksUri\": \"https://acme.okta.com/oauth2/default/v1/keys\"}",
  "enabled": true
}

Provider	Issuer	Subject claim	JWKS URI
Entra ID	`https://login.microsoftonline.com/{tenantId}/v2.0`	`oid`	`https://login.microsoftonline.com/{tenantId}/discovery/v2.0/keys`
Okta	`https:{domain}/oauth2/default \| sub \| https:{domain}/oauth2/default/v1/keys`
Google	`https://accounts.google.com`	`sub`	`https://www.googleapis.com/oauth2/v3/certs`
AD FS	`https:{adfs-host}/adfs \| sub \| https:{adfs-host}/adfs/discovery/keys`
Ping Identity	`https:{env}.pingone.com/{envId}/as \| sub \| https:{env}.pingone.com/{envId}/as/jwks`

A T4 user is linked to their IdP identity by an identityProvider object carrying two values:

Field	Description	Required
issuer	The provider's issuer URL (the same value sent above).	Yes
subject	The subject-claim value (`sub`/`oid`) for that user, as issued by your IdP.	Yes

At login, T4 matches the (issuer, subject) pair from the validated token to this link to find the T4 account.

Important: subject is the stable, opaque identifier from your IdP (a GUID for Entra ID, a numeric string for Google) — not the user's email address, unless your IdP is explicitly configured to use email as the subject. Supplying the wrong value causes login to fail.

You can set the link when onboarding a user, when creating a user, or on an existing user.

Add an identityProvider object to the User object in the onboard request:

POST https://api.t4login.com/admin/v1/users/onboard

{
  "User": {
    "templateUser": "DefaultTemplate",
    "username": "[email protected]",
    "password": "SecurePassword123!",
    "firstname": "Alice",
    "lastname": "Smith",
    "email": "[email protected]",
    "apptype": "NonProfessional",
    "identityProvider": {
      "issuer": "https://acme.okta.com/oauth2/default",
      "subject": "00u1ab2cd3EF4GH5IJ6K"
    }
  },
  "Account": { "...": "..." },
  "MarketData": { "...": "..." },
  "Eula": { "...": "..." }
}

POST https://api.t4login.com/admin/v1/users

{
  "username": "[email protected]",
  "firstname": "Alice",
  "lastname": "Smith",
  "email": "[email protected]",
  "apptype": "NonProfessional",
  "identityProvider": {
    "issuer": "https://acme.okta.com/oauth2/default",
    "subject": "00u1ab2cd3EF4GH5IJ6K"
  }
}

Use PATCH to add or change the link for a user that already exists:

PATCH https://api.t4login.com/admin/v1/users/{userID}

{
  "identityProvider": {
    "issuer": "https://acme.okta.com/oauth2/default",
    "subject": "00u1ab2cd3EF4GH5IJ6K"
  }
}

Note: To remove an SSO link, PATCH with an empty issuer: “identityProvider”: { “issuer”: “”, “subject”: “” }. Omit the identityProvider field entirely to leave an existing link unchanged.

Most IdPs let an administrator list subject values in bulk (the Object ID in Entra ID, the user ID in Okta, the numeric account ID in Google). For a single user, have them sign in to any application on that IdP and decode the resulting token at https://jwt.ms (Entra ID) or https://jwt.io (other providers); the sub or oid claim in the payload is the subject value.

Note: For Entra ID use the oid claim, not sub. oid is stable for the user across applications, whereas sub is scoped to a single client and differs between apps.

Once the provider is assigned to your firm and a user is linked, your application logs the user in by sending the OIDC ID token from your IdP in the T4 login request, in place of a password. T4 then:

Reads the iss claim and finds the enabled provider assigned to the firm.
Fetches the provider's JWKS keys (cached for one hour) and validates the token signature, issuer, and expiry.
Reads the subject claim (sub or oid) and matches the (issuer, subject) link to a T4 user.
Loads that user through the normal login path (roles, exchanges, accounts).

If no provider, no link, or an invalid token is found, the login is rejected.