SAML

Introduction

Kigo's SAML integration enables secure single sign-on (SSO) authentication between an organization's Identity Provider (IdP) and Kigo services. This allows organizations to leverage their existing identity management infrastructure for streamlined access control.

Prerequisites

Identity Provider Requirements:

• IdP Supports SAML 2.0 with Service Provider (SP) configuration.

Technical Infrastructure:

• Network connectivity allowing HTTPS traffic to api.kigodigital.net.

Technical Contact:

• An established connection with a technical resource at Kigo has been made to collaborate on completing the steps below.

Steps to Implement

Step 1: Retrieve Kigo Service Provider Metadata

1. Access the Kigo Service Provider metadata at https://api.kigodigital.net/api/v1/sso/saml/metadata.
2. Download the Service Provider metadata XML file.
3. Verify the metadata contains entity identifiers, assertion consumer service URLs, and certificate information*.

*There exists an md:SingleLogoutService element in the Service Provider metadata. SLO is currently not supported by Kigo, and this value may be updated or removed in the future.

Step 2: Generate Identity Provider Metadata

1. Create a new Service Provider configuration for Kigo in the Identity Provider's administrative interface.

2. Import the Kigo metadata file obtained in Step 1.

3. Configure user attribute mappings according to Kigo specifications:

   Attribute	Expected Attribute Name	Required
   User Email	emailaddress	Yes
   User First Name	firstname	No
   User Last Name	lastname	No

   
   

4. Generate and export the IdP metadata XML file.

5. Validate the metadata file contains all required configuration elements.

Step 3: Securely Transmit Identity Provider Metadata

1. Share the IdP metadata with a Kigo technical contact using secure channels such as:
   • Encrypted email with password protection
   • Secure file transfer protocol (SFTP)
   • Secure collaboration platforms
2. Confirm successful receipt with Kigo team.

Step 4: Kigo System Configuration

1. The Kigo team will import the provided IdP metadata and configure the connection.
2. The Kigo team will confirm a successful SAML connection and provide testing endpoint information.

Step 5: Comprehensive Connection Testing

1. Initiate test authentication attempts from Identity Provider.
2. Verify successful user authentication and attribute transmission. Test:
   • Standard user authentication
   • User attribute mapping verification
   • Session timeout behavior
3. Coordinate any issue resolution with the Kigo team.

Key Considerations

• Attribute Mapping: Required user attributes (email, user ID) must be consistently provided in SAML assertions and adhere to any specified formatting. Attribute mapping errors will impact user access.
• Session Management: Align session timeout behaviors between the IdP and Kigo systems.

Example Workflow

The following scenario demonstrates a complete SAML authentication workflow between an organization's Identity Provider and Kigo services:

Initial User Access Request:
A user attempts to access a protected Kigo application through their web browser. Since the user has not previously authenticated, Kigo's system detects the unauthenticated request and initiates the SAML authentication process by generating a SAML authentication request.

Identity Provider Authentication:

1. Kigo redirects the user to the organization's IdP login page.
2. The user enters their corporate credentials.
3. The IdP validates the credentials against the corporate directory.
4. Upon successful validation, the IdP prepares and signs a SAML assertion containing user identity information (e.g., email, display name, user ID).

Response and Session Establishment:

1. The IdP redirects the user back to Kigo with the signed SAML assertion.
2. Kigo receives and validates the assertion, mapping user attributes to internal profiles.
3. Upon successful validation, Kigo establishes an authenticated session, granting the user access to the requested application.

Best Practices

• Certificate Renewal: Establish automated certificate renewal schedules with advance notification (e.g., 90 days). Certificate expiration will cause service disruption.
• Thorough Testing: Perform comprehensive testing in development environments covering various user types, attribute mappings, and authentication flows, including error conditions.
• Documentation: Maintain current documentation of all IdP and SP configuration settings.
• Monitoring: Implement monitoring systems that provide real-time alerts for authentication failures.
• Coordination: Coordinate maintenance windows between the IdP and Kigo systems to minimize disruption.