--- title: SSO Assertion Configuration Guide description: "Title: SSO Configuration Guide: IdP Attribute and Claim Requirements\nSlug/URL handle: sso-idp-attribute-claim-configuration\nCategory: AuthBridge / SSO & Identity\nSubcategory: Configuration\nTags: SSO, SAML, OIDC, AuthBridge, IdP, k1x_tenant_id, deep linking, onboarding\nAudience: Client IT/SSO administrators, implementation engineers\nProduct(s): AuthBridge, K1 Aggregator\nSummary/Description: Step-by-step reference for configuring an identity provider to send the baseline user attributes and k1x_tenant_id claim required by K1x for SAML and OIDC SSO integrations. Includes deep linking instructions via AuthBridge, a worked example, and a troubleshooting section.\nRelated Articles: SAML certificate rotation, AuthBridge onboarding setup, K1x Tenant API reference\nStatus: Draft / Ready for Review" --- [Skip to content](https://support.k1x.io/sso-assertion-configuration-guide#main-content) [Submit A Support Ticket](https://support.k1x.io/kb-tickets/new?hsLang=en-us) [Client portal](https://support.k1x.io/tickets?hsLang=en-us) [![Group 16](https://support.k1x.io/hs-fs/hubfs/Group%2016.png?width=75&height=75&name=Group%2016.png)](https://support.k1x.io/?hsLang=en-us) - [Knowledge Base](https://support.k1x.io/) Open main navigation Close main navigation - [Knowledge Base](https://support.k1x.io/) - [Submit A Support Ticket](https://support.k1x.io/kb-tickets/new) - [Client portal](https://support.k1x.io/tickets) How can we help? - There are no suggestions because the search field is empty. 1. [K1x Knowledge Base](https://support.k1x.io/?hsLang=en-us) 2. [General](https://support.k1x.io/general?hsLang=en-us) 3. [Account Management - SSO & Okta](https://support.k1x.io/general?hsLang=en-us#account-management-sso-okta) July 2, 2026 # SSO Assertion Configuration Guide ## SAML and OIDC integration with K1x Overview This guide describes how to configure your identity provider (IdP) to issue the assertions and claims that K1x requires to authenticate users through SSO. It applies to both SAML and OIDC integrations. There are two parts to the configuration. First, your IdP must send baseline user attributes (first name, last name, email) so K1x can identify the user. Second, every response must include a K1x-specific tenant identifier so K1x can route the user to the correct tenant. Without either, authentication will fail.   Baseline User Attributes In addition to the K1x tenant identifier described in the next section, every authentication response must carry the user's first name, last name, and email address. K1x uses these to identify and provision the user. The attribute or claim names do not need to match a specific naming convention. You can use whatever your IdP emits by default. However, you must communicate the exact names you are sending to K1x so they can be mapped on the K1x side. | **Attribute** | **Required** | **Description** | | --- | --- | --- | | First Name | Yes | The user's given name. Commonly emitted by IdPs as givenName, firstName, or first\_name. | | Last Name | Yes | The user's family name. Commonly emitted by IdPs as surname, familyName, lastName, or last\_name. | | Email | Yes | The user's email address. Commonly emitted by IdPs as email, emailAddress, or mail. |   **Action required:** share the attribute or claim names you are using for first name, last name, and email with your K1x contact before testing SSO.   **K1x Tenant Identifier** Beyond the baseline user attributes, your IdP must also send a K1x-specific tenant identifier on every authentication response. The attribute must be named exactly as shown below and must contain the accountNumber value retrieved from the K1x tenant API. ### Attribute summary **Property name:** k1x\_tenant\_id **Value:** the accountNumber field returned from the K1x tenant API **Format:** GUID (string) **Important:** the K1x tenant API also returns an id field. Do not use that value. Use only accountNumber.   Retrieving the accountNumber The accountNumber is returned by the K1x Tenant API. Use whichever of the two endpoints below applies to your situation. | **Endpoint** | **Use** | | --- | --- | | POST /api/tenant/create | Returns the accountNumber for a newly provisioned tenant. | | GET /api/tenant/list | Returns the accountNumber for an existing tenant. |   Both endpoints are hosted at: https://api-aggregator.k1x.io 1Locate the accountNumber field in the JSON response and copy its value. This is the GUID you will map to k1x\_tenant\_id in your IdP configuration. Note: the response also contains an id field. That value is a separate internal identifier and must not be used. Always use accountNumber. SAML Configuration For SAML integrations, configure your IdP to release the tenant identifier as an attribute on the SAML assertion. ### Required attribute | **Attribute Name** | **Required** | **Value** | | --- | --- | --- | | k1x\_tenant\_id | Yes | The accountNumber GUID returned from the K1x tenant API. Do not use the id field, which is a separate internal identifier. |   ### Configuration steps 1. Locate the attribute mapping or attribute statement section of your SAML application configuration in your IdP. 2. Add a new attribute with the name k1x\_tenant\_id. 3. Set the value to the accountNumber returned from the K1x tenant API. This value is the same for every user in the tenant, so it can be set as a static or constant value rather than a per-user attribute. 4. Save the configuration and issue a test assertion to confirm the attribute appears in the SAML response. ### Example assertion fragment The relevant portion of the SAML assertion should look similar to the following: \ \ a3f1c8d2-9b4e-4f7a-8c6d-2e5b1f9a7c34 \ \   OIDC Configuration For OIDC integrations, configure your IdP to include the tenant identifier as a custom claim in the ID token (and, where applicable, the userinfo response). ### Required claim | **Claim Name** | **Required** | **Value** | | --- | --- | --- | | k1x\_tenant\_id | Yes | The accountNumber GUID returned from the K1x tenant API. Do not use the id field, which is a separate internal identifier. |   ### Configuration steps 1. Open the claim mapping or token configuration section of your OIDC application in your IdP. 2. Add a custom claim named k1x\_tenant\_id to the ID token. 3. Set the claim value to the accountNumber string returned from the K1x tenant API. 4. Confirm the claim is included in tokens issued for this application by inspecting a test ID token.   ### Example ID token payload fragment Once configured, the decoded ID token payload should contain the claim: { "sub": "user@example.com", "iss": "https://your-idp.example.com", "aud": "k1x-client-id", "k1x\_tenant\_id": "a3f1c8d2-9b4e-4f7a-8c6d-2e5b1f9a7c34" }   **Deep Linking from Your Application** To send a user from your application directly to a specific page in K1x, route them through the K1x AuthBridge. AuthBridge initiates the SSO handshake with the configured identity provider and redirects the user to the target K1x URL once authentication completes. Linking a user directly to a K1x page without going through AuthBridge will not establish a session and the user will not be authenticated. ### AuthBridge URL https://authbridge.k1x.io/provider-login?idp={ProvidedByK1x}&target={UrlEncodedRedirect} - idp - the identity provider key. K1x will provide this value during onboarding. - target - the URL-encoded destination URL inside K1x. Always URL-encode this value.   **Linking to an Instance** Use this pattern to take the user to the management view of a specific Instance. ### Target URL template (unencoded) https://k1aggregator.k1x.io/instance/{instanceId}/Manage **instanceId** is the numeric id of the Instance. ### Where to find the instanceId | **Endpoint** | **Use** | | --- | --- | | GET /api/instance/list | Returns the instanceId for existing Instances. | | POST /api/instance | Bulk-create endpoint. Returns the instanceId for newly created Instances. |   Linking to an Investment Use this pattern to take the user directly to the edit view for a specific Investment within an Instance. ### Target URL template (unencoded) https://k1aggregator.k1x.io/instance/{instanceId}/Manage/Edit/{investmentId}/Taxable   **instanceId** is the numeric id of the Instance containing the Investment. **investmentId** is the numeric id of the Investment. ### Where to find the investmentId | **Endpoint** | **Use** | | --- | --- | | GET /api/investment | Lists existing Investments and returns the investmentId for each. | | POST /api/investment | Creates an Investment and returns the new investmentId. |   **Worked Example** The following example shows how to construct a full AuthBridge URL that lands the user on a specific Investment after SSO completes. **Inputs** - idp value provided by K1x: acme-okta - instanceId: 79616 - investmentId: 617953   **Step 1: build the unencoded target URL** https://k1aggregator.k1x.io/instance/79616/Manage/Edit/617953/Taxable   **Step 2: URL-encode the target** https%3A%2F%2Fk1aggregator.k1x.io%2Finstance%2F79616%2FManage%2FEdit%2F617953%2FTaxable   **Step 3: assemble the AuthBridge URL** https://authbridge.k1x.io/provider-login?idp=acme-okta&target=https%3A%2F%2Fk1aggregator.k1x.io%2Finstance%2F79616%2FManage%2FEdit%2F617953%2FTaxable   ### Common pitfalls - Forgetting to URL-encode the target parameter. Slashes, colons, and query characters in an unencoded value will break parsing of the AuthBridge URL. - Omitting the idp parameter. AuthBridge cannot initiate SSO without it. - Using a value other than the one K1x provided for idp, such as a tenant name or display label. - Linking users directly to a k1aggregator.k1x.io URL without routing through AuthBridge. The user will land unauthenticated and be asked to sign in via email this will fail since there won’t be a direct link to the source provider. - Double-encoding the target (encoding an already-encoded value). This produces broken redirects after sign-in. - Using a stale instanceId or investmentId. If an Instance or Investment has been deleted or recreated, refresh the value from the API.   Verification Before going live, validate the configuration: - Trigger a test SSO login and capture the SAML response or ID token. - Confirm the k1x\_tenant\_id attribute or claim is present and the value matches the accountNumber returned from the K1x tenant API. - Confirm the value is sent as a string GUID, not a number, the id field, or another object. - Attempt a sign-in to K1x and confirm the user is routed into the correct tenant.   Troubleshooting ### User lands on an “Unable to Access” page - Confirm the attribute is named exactly k1x\_tenant\_id. Names are case-sensitive. - Verify with K1x that the value is mapping and correctly being applied to the user - Confirm the value is the accountNumber GUID, not the id field, tenant name, tenant URL, or another identifier returned from the API. ### Attribute is missing from the assertion - Confirm the attribute is mapped on the correct application in your IdP. - Confirm the attribute is released to the SAML response or included in the ID token, not only in the userinfo endpoint. ### Value appears wrapped or malformed - Confirm the value is a plain string. Some IdPs wrap constants in arrays or objects by default. The K1x platform expects a single string value.     - [General](https://support.k1x.io/general?hsLang=en-us#main-content) - [Account Management - SSO & Okta](https://support.k1x.io/general?hsLang=en-us#account-management-sso-okta) - [FAQ](https://support.k1x.io/general?hsLang=en-us#faq) - [Release Notes](https://support.k1x.io/general?hsLang=en-us#release-notes) - [K1 Aggregator](https://support.k1x.io/k1-aggregator?hsLang=en-us#main-content) - [Getting Started & Administration](https://support.k1x.io/k1-aggregator?hsLang=en-us#getting-started-administration) - [Core Workflows](https://support.k1x.io/k1-aggregator?hsLang=en-us#core-workflows) - [Reader Extraction & Document Upload](https://support.k1x.io/k1-aggregator?hsLang=en-us#reader-extraction-document-upload) - [Aggregator Modules - Investments](https://support.k1x.io/k1-aggregator?hsLang=en-us#aggregator-modules-investments) - [Aggregator Modules - Foreign Forms](https://support.k1x.io/k1-aggregator?hsLang=en-us#aggregator-modules-foreign-forms) - [Aggregator Modules - Reports and Exports](https://support.k1x.io/k1-aggregator?hsLang=en-us#aggregator-modules-reports-and-exports) - [K-1 Aggregator FAQ](https://support.k1x.io/k1-aggregator?hsLang=en-us#k-1-aggregator-faq) - [Integrations - CCH Axcess](https://support.k1x.io/k1-aggregator?hsLang=en-us#integrations-cch-axcess) - [Integrations - GoSystem](https://support.k1x.io/k1-aggregator?hsLang=en-us#integrations-gosystem) - [Integrations - UltraTax, Profx, OIT](https://support.k1x.io/k1-aggregator?hsLang=en-us#integrations-ultratax-profx-oit) - [Integrations - All Other](https://support.k1x.io/k1-aggregator?hsLang=en-us#integrations-all-other) - [990 Tracker](https://support.k1x.io/990-tracker?hsLang=en-us#main-content) - [990 Tracker FAQ](https://support.k1x.io/990-tracker?hsLang=en-us#990-tracker-faq) - [Federal Forms](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms) - [Federal Forms - 990-T](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-990-t) - [Federal Forms - Form 990](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990) - [Federal Forms - Form 990 - Form 990 Schedules - Schedule A](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990-form-990-schedules-schedule-a) - [Federal Forms - Form 990 - Form 990 Schedules - Schedule B](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990-form-990-schedules-schedule-b) - [Federal Forms - Form 990 - Form 990 Schedules - Schedule C](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990-form-990-schedules-schedule-c) - [Federal Forms - Form 990 - Form 990 Schedules - Schedule D](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990-form-990-schedules-schedule-d) - [Federal Forms - Form 990 - Form 990 Schedules - Schedule K](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990-form-990-schedules-schedule-k) - [Federal Forms - Form 990 - Form 990 Schedules - Schedule R](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990-form-990-schedules-schedule-r) - [Federal Forms - Form 990 EZ](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990-ez) - [Federal Forms - Form 990 PF](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-form-990-pf) - [Federal Forms - Other Federal Forms](https://support.k1x.io/990-tracker?hsLang=en-us#federal-forms-other-federal-forms) - [Electronic Filing](https://support.k1x.io/990-tracker?hsLang=en-us#electronic-filing) - [Modules](https://support.k1x.io/990-tracker?hsLang=en-us#modules) - [Modules - Conflict of Interest](https://support.k1x.io/990-tracker?hsLang=en-us#modules-conflict-of-interest) - [Modules - Master Compensation Module](https://support.k1x.io/990-tracker?hsLang=en-us#modules-master-compensation-module) - [State Forms](https://support.k1x.io/990-tracker?hsLang=en-us#state-forms) - [State Forms - Arizona](https://support.k1x.io/990-tracker?hsLang=en-us#state-forms-arizona) - [State Forms - Massachussets](https://support.k1x.io/990-tracker?hsLang=en-us#state-forms-massachussets) - [State Forms - Mississippi](https://support.k1x.io/990-tracker?hsLang=en-us#state-forms-mississippi) - [State Forms - New Mexico](https://support.k1x.io/990-tracker?hsLang=en-us#state-forms-new-mexico) - [State Forms - West Virginia](https://support.k1x.io/990-tracker?hsLang=en-us#state-forms-west-virginia) - [Troubleshooting](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting) - [Troubleshooting - Federal](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal) - [Troubleshooting - Federal - Validation Errors](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-validation-errors) - [Troubleshooting - Federal - Validation Errors - Form 990](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-validation-errors-form-990) - [Troubleshooting - Federal - Validation Errors - Form 990-T](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-validation-errors-form-990-t) - [Troubleshooting - Federal - Validation Errors - Form 990-PF](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-validation-errors-form-990-pf) - [Troubleshooting - Federal - Validation Errors - Other Federal Forms](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-validation-errors-other-federal-forms) - [Troubleshooting - Federal - Rejection Errors - Form 990](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-rejection-errors-form-990) - [Troubleshooting - Federal - Rejection Errors - Form 990-T](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-rejection-errors-form-990-t) - [Troubleshooting - Federal - Rejection Errors - Form 990-PF](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-rejection-errors-form-990-pf) - [Troubleshooting - Federal - Rejection Errors - Other Federal Forms](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-federal-rejection-errors-other-federal-forms) - [Troubleshooting - State - Validation Errors](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-state-validation-errors) - [Troubleshooting - State - Rejection Errors](https://support.k1x.io/990-tracker?hsLang=en-us#troubleshooting-state-rejection-errors) - [North Caolina](https://support.k1x.io/990-tracker?hsLang=en-us#north-caolina) - [Forms & Schedules](https://support.k1x.io/990-tracker?hsLang=en-us#forms-schedules) - [K1 Creator](https://support.k1x.io/k1-creator?hsLang=en-us#main-content) - [Core Workflows](https://support.k1x.io/k1-creator?hsLang=en-us#core-workflows) [![k1x logo](https://support.k1x.io/hs-fs/hubfs/k1x%20logo.webp?width=65&height=65&name=k1x%20logo.webp "k1x logo")](https://k1x.io) Privacy Policy | Legal | © 2024 K1x. All Rights Reserved. Patented/Patent-pending AI automation technology | The Digital K-1 Exchange and Digital K-1 Filetype. US2022/0405453 | AI-powered engine to extract data for K-1 PDF. US 2021/0082062 | C-TRAC. US 2010/0010849 1 High Street Court, Morristown, NJ 07960