Creating an SSO Session

The Kigo API enables partners to create SSO sessions for their users. These sessions facilitate seamless redirection to TOP site or embedding TOP within an application via iframes.

Prerequisites

Before making an API call to create an SSO session token on behalf of a user, obtain a partner-level session token by following the API Authentication Guide.

Steps to Implement

1. Creating an SSO Session

   • Endpoint: Create an SSO session for a user.
   • Purpose: This endpoint generates a session for the program associated with the external_program_id and the account linked to the external_user_id.
   • Session Expiration: The session_id is valid for 30 minutes. After expiration, a new session must be created to load a valid iframe from a Kigo-hosted site or to redirect to a Kigo-hosted site.
   • Usage: Include the returned session_id in the URL parameters when embedding or redirecting to TOP site.

2. Using the SSO Session ID

   • URL Example:

     https://kigo-top-test.kigodigital.net/sso/[external_program_id]?uuid=${session_id}
     

Key Considerations

1. Program-Specific Configuration
   1. A partner informs their primary contacts at Kigo of a new program they want to launch with a custom configuration. After providing the external_program_id and the desired customization, a Kigo administrator configures the program within Kigo's systems.
2. Handling Unknown external_program_id and external_user_id: If Kigo encounters unknown identifiers, it creates new entities within its system. If no program exists for the partner whose session token was used, Kigo will create a new program associated with the provided external_program_id. Similarly, a new account is created for an unknown external_user_id.
3. Session Storage: Kigo recommends enabling is_single_use for all sessions to reduce the risk of session reuse, especially in cases where the session ID or token is stored in local storage or is accessible on the client side. Set is_single_use to false only if persistent client-side storage (e.g. local storage or cookies) is impossible and the session must be reused in a trusted environment.

Example Workflow

1. End-user clicks a button inside a partner's web application.
2. The application sends an API call to the partner's server.
3. Obtain a partner-level session token using the provided endpoint in the server.
4. Create an SSO session by making an API call to receive a session_id, which authenticates the user into a Kigo-powered experience.
5. Pass the session_id back to the web application.
6. Redirect the user to TOP at:

   https://kigo-top-test.kigodigital.net/sso/[external_program_id]?uuid=${session_id}
   

Best Practices

• Secure Handling: The session_id can safely be passed to the client due to its limited, time-bound access. However, partner-level credentials should remain on the back-end server, never exposed to the front-end client.