SSO Assertion Configuration Guide

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:

<saml:Attribute Name="k1x_tenant_id">

<saml:AttributeValue xsi:type="xs:string">

a3f1c8d2-9b4e-4f7a-8c6d-2e5b1f9a7c34

</saml:AttributeValue>

</saml:Attribute>

 

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.