OpenID Connect (OIDC)

Introduction

Kigo supports Single Sign-On (SSO) authentication using OpenID Connect (OIDC), enabling your organization's users to access Kigo-powered experiences through your existing Identity Provider (IdP). With OIDC integration, users authenticate through your IdP (such as Okta, Azure AD, or Google Workspace) and are seamlessly redirected into Kigo with an active session — no separate login required.

This guide walks through the steps required to configure and test an OIDC integration between your Identity Provider and Kigo.

Authentication Flow

sequenceDiagram
    actor User
    participant App as Client App
    participant Kigo
    participant IdP

    User->>App: Clicks link to Kigo experience
    App->>Kigo: GET /api/v1/sso/oidc/login
    Kigo->>IdP: Authorization request (state, nonce, PKCE challenge)
    IdP->>User: Login prompt
    User->>IdP: Authenticates
    IdP->>Kigo: Callback with authorization code
    Kigo->>IdP: Exchange code for tokens (server-to-server)
    Kigo->>Kigo: Validate ID token, extract claims, provision/update user
    Kigo->>User: Redirect to {redirect_url}?sessionId={session_id}

Kigo never sees or handles user credentials. The entire flow takes seconds from the user's perspective.

---

What Kigo Provides

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

What You Provide

---

Prerequisites

Before starting the integration, confirm the following:

• Your Identity Provider supports OpenID Connect / OAuth 2.0 with the Authorization Code flow.
• Your IdP supports PKCE (RFC 7636) with the S256 challenge method — this is required. PKCE is always used; an IdP that cannot perform PKCE-S256 cannot be onboarded.
• Kigo requires a confidential client registration (Client ID + Client Secret), used in addition to PKCE. The client authenticates to your token endpoint with client_secret_basic or client_secret_post. private_key_jwt is not currently supported.
• Your IdP signs ID tokens with RS256 or ES256 — these are the asymmetric signing algorithms Kigo accepts. Tokens signed with any other algorithm (or unsigned) are rejected. RS256 is the default for most IdPs, so no change is typically needed.
• Your IdP makes the user's email available either as a claim in the ID token or from the UserInfo endpoint — see Step 3 for full claim requirements.
• Your IdP's issuer URL is HTTPS on a publicly reachable host, and publishes a standard .well-known/openid-configuration discovery document.
• Your network permits HTTPS connectivity to https://api.kigodigital.net.
• You have an established Kigo technical contact for coordination during setup and testing.
• You have administrative access to your IdP to register a new OIDC application.

---

Steps to Implement

Step 1: Register Kigo in Your Identity Provider

Register Kigo as a new OIDC application (relying party) in your IdP with the following settings:

• Application type: Web application (confidential client).
• Grant type: Authorization Code.
• Redirect URI (sometimes labeled "Sign-in redirect URI" or "Callback URL"): https://api.kigodigital.net/api/v1/sso/oidc/callback.
• Scopes: openid, profile, email.

---

Step 2: Share Configuration Details with Kigo

After registering the application, share the following with your Kigo technical contact:

---

Step 3: Configure Claim Mappings

Kigo extracts user attributes primarily from the OIDC ID token. If the email claim is not present in the ID token, Kigo falls back to your IdP's UserInfo endpoint (using the issued access token) to retrieve it; the email must be resolvable from one of these two sources or the login fails. Work with your Kigo technical contact to confirm your IdP's claim names map to the expected Kigo claim names.

Standard Claim Mappings

Kigo identifies users by the sub (subject) claim, which is mandatory per the OIDC specification. Your IdP must include sub in the ID token — this serves as the primary user identifier in Kigo and cannot be remapped.

If your IdP uses standard OIDC claim names (email, given_name, family_name), no custom mapping is required for those claims. If your IdP uses different claim names, Kigo will configure a mapping from your IdP's claim names to ours.

Custom Claims: If your integration requires additional user attributes beyond the standard set, Kigo can configure custom claim mappings to accommodate them.

---

Step 4: Securely Transmit Credentials to Kigo

The Client Secret is sensitive and must be transmitted securely. Coordinate with your Kigo technical contact to share credentials through one of the following methods:

• An encrypted email or secure file-sharing service.
• A shared secrets manager or vault.
• A pre-arranged secure channel.

Do not send client secrets via unencrypted email or chat.

---

Step 5: Kigo System Configuration

Once Kigo receives your configuration details and credentials:

1. Kigo imports your OIDC configuration into our system, including issuer URL, client credentials, scopes, and claim mappings.
2. Kigo verifies connectivity to your IdP's discovery endpoint and confirms that token signing keys can be retrieved.
3. Kigo provides you with the login URL for initiating the OIDC flow: https://api.kigodigital.net/api/v1/sso/oidc/login?client_id={client_id}&destination_url={destination_url}.

---

Step 6: Test the Connection

Conduct all testing in Kigo's test environment before moving to production.

---

Security

Session management: After successful authentication, Kigo creates a single-use session and redirects the user to your configured Redirect URL with a sessionId query parameter appended (e.g. {base_url}/sso/{external_program_id}?sessionId=…; any destination_url path is inserted before the query string). The sessionId expires after 30 minutes. The Kigo experience hosted at that URL consumes the sessionId automatically to establish the session — no action is required from your application.

PKCE: Kigo always uses PKCE with the S256 method on every authorization request — it is a mandatory part of the flow, not an optional enhancement. No configuration is needed on your side beyond ensuring your IdP supports PKCE-S256 (see Prerequisites).

State and nonce: Kigo uses state and nonce parameters per the OIDC specification to prevent CSRF and token replay attacks. Standard-compliant IdPs handle these automatically — no configuration is required on your side.

---

Operational Responsibilities

Credential Rotation

• Store client secrets securely in your IdP and rotate them according to your organization's security policy.
• Notify your Kigo technical contact before rotating client secrets so we can update our configuration simultaneously and avoid downtime.

Signing Key Rotation

When rotating your IdP's token signing keys, follow standard JWKS rollover practice: publish the new key alongside the old one, allow time for relying parties (including Kigo) to pick up the new key, then retire the old key. Kigo periodically refreshes your IdP's published signing keys automatically.

Coordination

• Designate a technical point of contact on your team for the integration.
• Coordinate any IdP configuration changes (scope changes, claim updates, key rotation) with your Kigo technical contact in advance.
• Plan a maintenance window for production cutover if migrating from another authentication method.

User Deprovisioning

When a user is deactivated in your IdP, your IdP will block subsequent login attempts — no action is needed on the Kigo side. To remove a user's Kigo account entirely, coordinate with your Kigo technical contact.

---

Current Limitations

• One OIDC configuration per partner organization. Each configuration signs members in to one Kigo program. If you need OIDC for more than one program, talk to your Kigo account manager before you start. The Partner API Key and SAML 2.0 methods support multiple programs today.
• private_key_jwt client authentication is not supported.
• Single Logout is not supported. The Kigo experience keeps its own session after sign-in.

---

Support

For questions or issues during integration, contact your Kigo technical contact or reach out to Kigo support.