Differences

This shows you the differences between two versions of the page.

--- developers:admin:sso [2026/09/29 12:29] – created chad
+++ developers:admin:sso [2026/09/29 14:12] (current) – [Common Provider Values] chad
@@ Line 1: / Line 1: @@
 ====== SSO Integration ======
-T4 supports single sign-on (SSO) so your users can log in with your own identity provider (IdP) using [[https://openid.net/connect/|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.
+T4 supports single sign-on (SSO), letting your users log in with your own identity provider (IdP) over 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 in place of the password.
-Integrating SSO involves three parts:
+Integrating SSO takes three steps:
-  - **Tell us about your identity provider** so we can register it and assign it to your firm.
+  - Send your identity provider details to T4.
-  - **Link each T4 user** to their identity in that provider, using the standard user endpoints.
+  - Link each T4 user to their identity in that provider.
-  - **Send the OIDC token at login** from your application instead of a password.
+  - Send the OIDC token at login instead of a password.
-<bootnote>
-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.
-</bootnote>
 ===== What We Support =====
-  * **Protocol:** OpenID Connect (OIDC) over OAuth2.
+  * **Protocol:** OpenID Connect (OIDC).
   * **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.
-===== 1. Identity Provider Details =====
+===== 1. Send Us Your Provider Details =====
-Send the following to T4 once per identity provider. The same provider can be reused across multiple firms on the same IdP.
+Email the following to T4.[email protected]. T4 will confirm once the provider is set up.
 | **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''. |
+| Issuer URL | The ''iss'' value in your 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''. |
+| JWKS URI | The URL of your JSON Web Key Set. 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. |
+| Subject claim | The claim that uniquely identifies a user. Use ''sub'' for most providers; ''oid'' for Entra ID. |
-<bootnote important>
+<bootnote>
-The **Issuer URL must match the ''iss'' claim in your tokens exactly**, including any trailing slash. A mismatch causes every login to be rejected.
+The Issuer URL must match the ''iss'' claim in your tokens exactly, including any trailing slash.
 </bootnote>
-Once you send these, T4 registers the provider and assigns it to your firm. For reference, the registration T4 performs on your behalf is:
-<code>
-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
-}
-</code>
-==== Common Provider Values ====
 | **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'' |
+| 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'' |
+| 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'' |
+| 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'' |
+| 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'' |
+| Ping Identity | ''%%https://{env}.pingone.com/{envId}/as%%'' | ''sub'' | ''%%https://{env}.pingone.com/{envId}/as/jwks%%'' |
 ===== 2. Link Each User to Their SSO Identity =====
-A T4 user is linked to their IdP identity by an ''identityProvider'' object carrying two values:
+Link a user by adding an ''identityProvider'' object with two values:
-| **Field** | **Description** | **Required** |
+| **Field** | **Description** |
-| issuer | The provider's issuer URL (the same value sent above). | Yes |
+| issuer | The provider's issuer URL. |
-| subject | The subject-claim value (''sub''/''oid'') for that user, as issued by your IdP. | Yes |
+| subject | The subject-claim value (''sub''/''oid'') for that user, as issued by your IdP. |
-At login, T4 matches the ''(issuer, subject)'' pair from the validated token to this link to find the T4 account.
-<bootnote important>
-''subject'' is the stable, opaque identifier from your IdP (a GUID for Entra ID, a numeric string for Google) &mdash; **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.
-</bootnote>
-You can set the link when onboarding a user, when creating a user, or on an existing user.
+Set the link when onboarding, when creating a user, or on an existing user.
 ==== During Onboarding ====
-Add an ''identityProvider'' object to the ''User'' object in the [[developers:admin:onboarding|onboard]] request:
+Add ''identityProvider'' to the ''User'' object in the [[developers:admin:onboarding|onboard]] request:
 <code>
@@ Line 121: / Line 92: @@
 ==== On an Existing User ====
-Use PATCH to add or change the link for a user that already exists:
 <code>
@@ Line 136: / Line 105: @@
 <bootnote>
-To **remove** an SSO link, PATCH with an empty ''issuer'': ''"identityProvider": { "issuer": "", "subject": "" }''. Omit the ''identityProvider'' field entirely to leave an existing link unchanged.
+To remove a link, PATCH with an empty ''issuer''. Omit ''identityProvider'' to leave it unchanged.
 </bootnote>
-==== Finding a User's Subject Value ====
+===== 3. Logging In with SSO =====
-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.
+Log the user in with the standard [[developers:apiv2:connecting|LoginRequest]], but instead of ''username''/''password'' set your IdP's OIDC ID token in the ''id_token'' field. ''app_name'' and ''app_license'' are still required.
-<bootnote>
+<code>
-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.
+// ClientMessage
-</bootnote>
+login_request {
+  id_token: "eyJhbGciOiJSUzI1NiIsImtpZCI6..."   // OIDC ID token from your IdP
-===== 3. Logging In with SSO =====
+  app_name: "YourApp"
+  app_license: "YOUR-APP-LICENSE-GUID"
-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:
+  price_format: PRICE_FORMAT_DECIMAL
+}
+</code>
-  - Reads the ''iss'' claim and finds the enabled provider assigned to the firm.
+T4 validates the token (signature, issuer, and expiry) and signs in the user whose ''(issuer, subject)'' link matches. The reply is the usual ''LoginResponse''.
-  - 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.
 ===== Checklist =====
-  * Provider details sent to T4: issuer, JWKS URI, subject claim, and vendor.
+  * Provider details sent to T4.[email protected].
-  * Provider registered and assigned to your firm (confirmed by T4).
+  * Every SSO user linked with the correct ''subject'' value.
-  * Every SSO user has an ''identityProvider'' link with the correct ''subject'' value.
+  * At least one successful test login before go-live.
-  * At least one successful test login completed before go-live.