KeyRunner Enterprise SSO Integration Guide

Overview

This guide outlines the steps for configuring SSO between your Identity Provider (IdP) and KeyRunner, where KeyRunner acts as the Service Provider (SP) and your organization acts as the IdP.

---

Section 1: SSO Integration

1.1 Overview

KeyRunner supports SSO via the SAML 2.0 protocol. Customers can configure their Identity Providers (IdPs) to authenticate users and grant them access to KeyRunner Desktop Clients and VSCode Extension.

---

1.2 Steps for SSO Setup

Step 1: Gather Service Provider (SP) Details

Provide the following details to your IdP administrator for creating a SAML integration:

• ACS URL:
  https://identity.keyrunner.app/saml/acs
  This is the endpoint where the IdP will send SAML assertions after authentication.

• Entity ID:
  https://identity.keyrunner.app
  The unique identifier for KeyRunner as the SP.

• Redirect URL:
  https://identity.keyrunner.app

• Certificates:

  • KeyRunner provides an SP Certificate used for validating SAML assertions.
  • SP Certificate: Request the public certificate in .crt format from KeyRunner.

Step 2: Create an Application in Your IdP

1. Log in to your IdP (e.g., Okta, Azure AD, Ping Identity).

2. Create a new SAML 2.0 application.

3. Configure the following settings:

   • ACS URL: https://identity.keyrunner.app/saml/acs
   • Entity ID: https://identity.keyrunner.app
   • NameID Format: emailAddress
   • Attributes:
     • email → User email address (required)
     • firstName → User's first name (optional)
     • lastName → User's last name (optional)

4. Export IdP Metadata: Once the application is configured, export the IdP Metadata XML.

Step 3: Share IdP Metadata with KeyRunner

Send the exported IdP Metadata to KeyRunner for integration. This will contain:

• SSO URL: The IdP's authentication endpoint.
• IdP Entity ID: The IdP’s unique identifier.
• Certificates: Public certificates for validating SAML requests.

Step 4: KeyRunner Configures the Integration

Once KeyRunner receives the IdP metadata, we will:

1. Import IdP Metadata and configure KeyRunner as the Service Provider (SP).
2. Generate SP Metadata: KeyRunner will share the generated SP metadata, which includes the ACS URL, Entity ID, and SP Certificate.

Step 5: Finalize Attribute Mapping and Test

1. Attribute Mapping: Ensure attributes like email, firstName, and lastName are properly mapped in your IdP.
2. Test SSO: Perform a test login from the IdP to ensure the integration works smoothly.

---

Section 2: SCIM Integration

2.1 Overview

SCIM (System for Cross-domain Identity Management) automates user provisioning, updates, and deprovisioning between your IdP and KeyRunner, ensuring that user accounts are created, modified, or removed in sync across systems.

---

2.2 Steps for SCIM Setup

Step 1: Generate an API Key

KeyRunner provides an API key for SCIM operations. This key will authenticate your requests.

Step 2: Configure SCIM in Your IdP

To configure SCIM, provide the following details to your IdP administrator:

• SCIM Base URL:
  https://api.keyrunner.app/scim/v2

• Authentication Method:
  Bearer Token (API Key).

Step 3: Test SCIM Operations

Once your IdP is configured with the SCIM API details, you can begin testing user provisioning and deprovisioning.

Example: Create a User via SCIM API

curl --request POST \
  --url https://api.keyrunner.app/scim/v2/Users \
  --header "Authorization: Bearer <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "userName": "user@example.com",
    "name": {
      "givenName": "John",
      "familyName": "Doe"
    },
    "emails": [
      {
        "value": "user@example.com",
        "type": "work",
        "primary": true
      }
    ]
  }'