SAML 2.0

Introduction

Kigo's SAML 2.0 integration lets members sign in to a Kigo-powered experience through your organization's Identity Provider (IdP). Your IdP authenticates the member and sends Kigo a signed SAML assertion. Kigo validates the assertion, creates or updates the member's account, creates a single-use SSO session, and redirects the member into the Kigo experience, signed in.

Kigo acts as the SAML Service Provider (SP). Your IdP (for example Okta, Microsoft Entra ID, Ping, ADFS, or Auth0) acts as the Identity Provider. No code is required on your side, only IdP configuration.

Authentication Flow

Kigo supports both SP-initiated and IdP-initiated sign-in.

SP-initiated (the member starts from a link on your site that goes through Kigo):

sequenceDiagram
    actor Member
    participant App as Your Site
    participant Kigo as Kigo API (SP)
    participant IdP as Your IdP
    participant Exp as Kigo-hosted Experience

    Member->>App: Clicks link to Kigo experience
    App->>Kigo: GET /api/v1/sso/saml/login?entity_id={your IdP entity ID}
    Kigo-->>App: { "login_url": "<IdP SSO URL with AuthnRequest>" }
    App->>IdP: Redirect member to login_url
    IdP->>Member: Login prompt (skipped if already signed in)
    Member->>IdP: Authenticates
    IdP->>Kigo: POST signed SAMLResponse to the ACS URL
    Kigo->>Kigo: Validate signature, read NameID and attributes, create/update account
    Kigo->>Exp: Redirect to {redirect_url}?sessionId={session_id}
    Exp-->>Member: Member is signed in

IdP-initiated (the member starts from your IdP, portal, or app launcher): the IdP posts a signed assertion directly to Kigo's ACS URL, and the flow continues from the "Validate signature" step above.

What Kigo Provides

The values above are for production. Kigo provides the matching test-environment values during onboarding. Configure and test in the test environment first.

The SP metadata includes an md:SingleLogoutService element. Single Logout (SLO) is not currently supported by Kigo; this value may change or be removed in the future.

What You Provide

Prerequisites

• Your IdP supports SAML 2.0 Web Browser SSO with the HTTP-POST binding to the ACS.
• Your IdP can sign assertions (Kigo's metadata sets WantAssertionsSigned="true"). Unsigned assertions are rejected.
• Your network allows HTTPS traffic to api.kigodigital.net.
• You have administrative access to your IdP.
• You have a Kigo technical contact for setup and testing.

Steps to Implement

Step 1: Create a SAML Application for Kigo in Your IdP

1. Create a new SAML 2.0 application (sometimes called a "relying party trust" or "service provider") for Kigo.
2. Import the Kigo SP metadata from the metadata URL, or enter the values manually:
   • Entity ID / Audience URI: http://kigodigital.net
   • ACS URL / Reply URL / Single sign-on URL: https://api.kigodigital.net/api/v1/sso/saml/acs
3. Set the assertion to be signed by your IdP. Signing the whole response as well is fine.
4. Kigo does not sign its AuthnRequests (AuthnRequestsSigned="false"). Do not require signed AuthnRequests for this application.

🚧

One IdP application per program

Kigo identifies your integration by the Issuer (Entity ID) in the assertion, and each integration has one redirect into the Kigo experience. If you have more than one Kigo program, create a separate SAML application with its own Entity ID for each program.

Step 2: Configure the NameID and Attributes

NameID (Subject): Required. Kigo uses the NameID as the member's unique identifier (external_user_id) in Kigo. Use a value that never changes for the member, such as an internal member or account ID. If it changes, Kigo treats the member as new.

Attributes: Kigo reads the following attribute names. Attribute names are case-sensitive.

Any additional attributes in the assertion are stored on the member's Kigo account as user attributes. Agree on them with Kigo before sending them.

Example assertion (excerpt):

<saml:Assertion ...>
  <saml:Issuer>https://idp.example.com/kigo-program</saml:Issuer>
  <ds:Signature>...</ds:Signature>
  <saml:Subject>
    <saml:NameID>member-12345</saml:NameID>
    ...
  </saml:Subject>
  <saml:Conditions ...>
    <saml:AudienceRestriction>
      <saml:Audience>http://kigodigital.net</saml:Audience>
    </saml:AudienceRestriction>
  </saml:Conditions>
  <saml:AttributeStatement>
    <saml:Attribute Name="emailaddress"><saml:AttributeValue>[email protected]</saml:AttributeValue></saml:Attribute>
    <saml:Attribute Name="firstname"><saml:AttributeValue>Jane</saml:AttributeValue></saml:Attribute>
    <saml:Attribute Name="lastname"><saml:AttributeValue>Doe</saml:AttributeValue></saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>

Step 3: Export and Securely Send Your IdP Metadata

1. Export the IdP metadata XML for the Kigo application.
2. Confirm it contains your Entity ID, SSO URL, and signing certificate.
3. Send it to your Kigo technical contact through a secure channel, such as an encrypted email, a secure file transfer (SFTP), or a secure collaboration platform.

IdP metadata contains only public information (no private keys), but sending it securely protects its integrity.

Step 4: Kigo Configuration

Kigo will:

1. Import your IdP metadata and link your IdP Entity ID to your program.
2. Configure the redirect URL, which is where Kigo sends the member after sign-in. It points to your program's Kigo-hosted experience, for example {base_url}/sso/{external_program_id}.
3. Confirm SSO is enabled for the program.
4. Send you the values to test with, including the SP-initiated login link.

Step 5: Start Sign-In

Choose one or both:

• SP-initiated: From your site, call the login endpoint with your IdP Entity ID (URL-encoded), then redirect the member's browser to the returned login_url.

  Bash

  curl "https://api.kigodigital.net/api/v1/sso/saml/login?entity_id=https%3A%2F%2Fidp.example.com%2Fkigo-program"

  JSON

  {
    "login_url": "https://idp.example.com/sso/saml?SAMLRequest=..."
  }

• IdP-initiated: Add a tile, link, or button in your IdP or portal that launches the Kigo application. The IdP posts the assertion to Kigo's ACS URL.

After a successful sign-in, Kigo redirects the member to:

{redirect_url}?sessionId={session_id}

The Kigo-hosted experience exchanges the sessionId and signs the member in. No action is needed from your application. The session ID is single-use and expires after 30 minutes.

Step 6: Test the Connection

Complete all testing in Kigo's test environment before production.

Errors

Key Considerations

• Entity ID: The Issuer in every assertion must exactly match the Entity ID in the IdP metadata you sent Kigo.
• Stable NameID: The account is keyed on the NameID. Avoid values that can change, such as email addresses, when a permanent ID is available.
• Multiple programs: Use one SAML application (and Entity ID) per Kigo program.
• Session management: Kigo does not support Single Logout. The Kigo experience keeps its own session after sign-in.

Best Practices

• Certificate renewal: Notify Kigo well before your IdP signing certificate expires (for example, 90 days) and send updated metadata. An expired or replaced certificate stops sign-in until Kigo has the new metadata.
• Testing: Test with several member types, with and without optional attributes, and with error conditions.
• Documentation: Keep a record of your IdP and Kigo configuration settings.
• Monitoring: Alert on authentication failures in your IdP.
• Coordination: Coordinate IdP changes (certificates, Entity ID, attributes) and maintenance windows with your Kigo technical contact.