DEVELOPER DOCUMENTATION • 5-MINUTE SELF-SERVE GUIDES OASIS SAML 2.0 to RFC 7519 HS256 JWT

Step-by-Step Enterprise SSO Integration Blueprints.

Select your customer's Identity Provider below or use the left navigation box to jump directly to exact copy-paste instructions for the KyoRox Control Plane.

CORE GUIDE A • WORKSPACE AUTHENTICATION

1. How to Log In & Navigate the KyoRox Control Plane

Every KyoRox subscription automatically provisions an isolated tenant workspace. Here is how to access your dashboard and navigate its core tabs.

Open Control Plane →
STEP 01

Locate Your Welcome Credentials

Immediately after checkout, KyoRox sends an automated welcome email from support@kyorox.com containing your unique Tenant UUID, your one-time Live API Key (kx_live_...), and your 256-bit JWT Client Secret.

STEP 02

Authenticate at kyorox.com/dashboard

Open https://kyorox.com/dashboard, paste your Tenant UUID and Live API Key, and click Access Control Plane. Credentials are kept strictly in tab-scoped sessionStorage.

STEP 03

Navigate the Control Plane Tabs

Inside the dashboard, use SP Endpoints to copy your KyoRox URLs, Add Connection Studio to connect an IdP, Active Connections to inspect health, and API Keys & JWT Vault to view your signing secret.

STEP 04

Lost Your API Key? Use Email OTP Recovery

Because API keys are stored as irreversible SHA-256 hashes, misplaced keys cannot be read back. Use the Rotate API Key & Secret action inside the Control Plane (verified via a 6-digit email OTP) or email support@kyorox.com.

CORE GUIDE B • SERVICE PROVIDER (SP) CONFIGURATION

2. Copying Your KyoRox Service Provider (SP) Endpoints

Every enterprise Identity Provider asks for two core values from your Service Provider: the SP Entity ID (Audience URI) and the Assertion Consumer Service (ACS) URL. Replace {YOUR_TENANT_UUID} with your Tenant UUID.

⚡ LIVE ONBOARDING ENDPOINT URL GENERATOR Paste your Tenant UUID to auto-fill all endpoints & IdP guides below
1. SP ENTITY ID (AUDIENCE URI) & HOSTED OASIS SP METADATA XML URL https://sso.kyorox.com/metadata/{YOUR_TENANT_UUID}
2. ASSERTION CONSUMER SERVICE (ACS / SINGLE SIGN-ON REPLY URL — HTTP-POST) https://sso.kyorox.com/auth/sso/{YOUR_TENANT_UUID}/acs
3. SP-INITIATED LOGIN TRIGGER URL (REDIRECT USERS HERE FROM YOUR APP LOGIN BUTTON) https://sso.kyorox.com/auth/sso/{YOUR_TENANT_UUID}?provider=okta&redirect_uri=https://app.yourdomain.com/sso/callback
PROVIDER GUIDE 01 • PROVIDER KEY: okta

Okta Workforce Identity — Step-by-Step SAML 2.0 Setup

Connect Okta Workforce Identity to KyoRox in 4 steps. No custom XML coding required.

dashboard value: okta
STEP 1 • IN KYOROX DASHBOARD

Copy Your SP Endpoints

Log into kyorox.com/dashboard, open the SP Endpoints tab, and copy your ACS URL and SP Entity ID.

STEP 2 • IN OKTA ADMIN CONSOLE

Create SAML 2.0 App Integration

Go to Applications ➔ Create App Integration ➔ SAML 2.0. Paste your KyoRox ACS URL into Single sign-on URL, paste your SP Entity ID into Audience URI (SP Entity ID), set Name ID format to EmailAddress, and add Attribute Statements: email (user.email), firstName (user.firstName), and lastName (user.lastName).

STEP 3 • EXPORT FROM OKTA

Copy Sign-On URL, Issuer & X.509 Certificate

Open the Sign On tab of your new Okta application. Copy the Issuer (IdP Entity ID), the Sign-On URL (IdP SSO URL), and download the X.509 Certificate (.cert / .pem). Assign users or groups under the Assignments tab.

STEP 4 • IN KYOROX DASHBOARD

Save Connection in Add Connection Studio

In the KyoRox Dashboard, open Add Connection Studio, select okta (Okta Workforce Identity), paste the Okta IdP Entity ID, IdP SSO URL, and PEM Certificate, enter your app's HTTPS callback in Allowed Redirect URIs (e.g. https://app.yourdomain.com/sso/callback), and click Save & Encrypt Connection.

OKTA ATTRIBUTE & ENDPOINT MAPPING SUMMARY 
Single sign-on URL (ACS) : https://sso.kyorox.com/auth/sso/{YOUR_TENANT_UUID}/acs
Audience URI (Entity ID) : https://sso.kyorox.com/metadata/{YOUR_TENANT_UUID}
Name ID Format           : EmailAddress (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
Attribute Statements     : email -> user.email | firstName -> user.firstName | lastName -> user.lastName
KyoRox Provider Key      : okta
PROVIDER GUIDE 02 • PROVIDER KEY: azure_ad

Microsoft Entra ID (Azure AD) — Step-by-Step SAML 2.0 Setup

Configure an Enterprise Non-Gallery SAML Application in Microsoft Entra Admin Center and link it to KyoRox.

dashboard value: azure_ad
STEP 1 • IN KYOROX DASHBOARD

Copy SP Entity ID & ACS Reply URL

Open the SP Endpoints tab in kyorox.com/dashboard and copy your SP Entity ID and ACS URL (or download your Hosted SP Metadata XML file).

STEP 2 • IN MICROSOFT ENTRA PORTAL

Create Enterprise Application & Basic SAML Config

Go to Enterprise Applications ➔ New Application ➔ Create your own application (Non-gallery). Open Single sign-on ➔ SAML, click Edit on Step 1 (Basic SAML Configuration), paste your KyoRox SP Entity ID into Identifier (Entity ID), and paste your KyoRox ACS URL into Reply URL (Assertion Consumer Service URL).

STEP 3 • EXPORT FROM ENTRA ID

Download Base64 Certificate & Copy Login URLs

In Section 3 (SAML Certificates), download Certificate (Base64) and open it in a text editor to copy the PEM block. In Section 4 (Set up Application), copy the Microsoft Entra Identifier (IdP Entity ID) and Login URL (IdP SSO URL). Assign enterprise users under Users and groups.

STEP 4 • IN KYOROX DASHBOARD

Activate azure_ad Connection in Control Plane

In KyoRox Add Connection Studio, select azure_ad (Microsoft Entra ID / Azure AD), paste the Entra Identifier, Login URL, and Base64 PEM Certificate, enter your HTTPS Allowed Redirect URI, and click Save & Encrypt Connection.

MICROSOFT ENTRA ID SAML CONFIGURATION SUMMARY 
Identifier (Entity ID)   : https://sso.kyorox.com/metadata/{YOUR_TENANT_UUID}
Reply URL (ACS URL)      : https://sso.kyorox.com/auth/sso/{YOUR_TENANT_UUID}/acs
Unique User Identifier   : user.mail (EmailAddress)
Certificate Format       : Certificate (Base64) -> -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
KyoRox Provider Key      : azure_ad
PROVIDER GUIDE 03 • PROVIDER KEY: google_workspace

Google Workspace SAML — Step-by-Step SAML 2.0 Setup

Connect Google Admin Console Custom SAML Apps to KyoRox in 4 straightforward steps.

dashboard value: google_workspace
STEP 1 • IN GOOGLE ADMIN CONSOLE

Create a Custom SAML App

Sign into admin.google.com and navigate to Apps ➔ Web and mobile apps ➔ Add App ➔ Add custom SAML app. Enter your application name and click Continue.

STEP 2 • COPY GOOGLE IDP DETAILS

Copy SSO URL, Entity ID & Certificate

On the Google Identity Provider details page (Option 2), copy the SSO URL, copy the Entity ID, and download or copy the Certificate (X.509 PEM). Click Continue.

STEP 3 • PASTE KYOROX SP DETAILS

Configure ACS URL, Entity ID & User Access

On the Service provider details screen, paste your KyoRox ACS URL and SP Entity ID from the KyoRox Dashboard. Check the Signed response box, set Name ID format to EMAIL, map attributes (Primary email ➔ email, First name ➔ firstName, Last name ➔ lastName), click Finish, and set User access to ON for everyone.

STEP 4 • IN KYOROX DASHBOARD

Save Google Workspace Connection

Open Add Connection Studio at kyorox.com/dashboard, select google_workspace (Google Workspace SAML), paste Google's Entity ID, SSO URL, and PEM Certificate, enter your HTTPS Allowed Redirect URI, and click Save & Encrypt Connection.

GOOGLE WORKSPACE SAML CONFIGURATION SUMMARY 
ACS URL                  : https://sso.kyorox.com/auth/sso/{YOUR_TENANT_UUID}/acs
Entity ID                : https://sso.kyorox.com/metadata/{YOUR_TENANT_UUID}
Signed Response          : Checked (Required for RSA-SHA256 verification)
Name ID Format           : EMAIL (Basic Information > Primary email)
Attribute Mapping        : Primary email -> email | First name -> firstName | Last name -> lastName
KyoRox Provider Key      : google_workspace
PROVIDER GUIDE 04 • PROVIDER KEY: custom_saml

JumpCloud Directory Platform — Step-by-Step SAML 2.0 Setup

Configure JumpCloud SSO Applications with KyoRox in 4 guided steps.

dashboard value: custom_saml
STEP 1 • IN JUMPCLOUD ADMIN PORTAL

Add a New Custom SAML Application

Log into the JumpCloud Admin Portal and go to User Authentication ➔ SSO Applications ➔ + Add New Application. Select Custom SAML App at the bottom of the drawer and open the SSO tab.

STEP 2 • CONFIGURE SP ENDPOINTS

Paste KyoRox SP Entity ID & ACS URL

Enter an IdP Entity ID (e.g., urn:jumpcloud:yourcompany). Paste your KyoRox SP Entity ID and ACS URLs from the KyoRox Dashboard. Set SAMLSubject NameID to email and SAMLSubject NameID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. Check Sign Assertion.

STEP 3 • EXPORT FROM JUMPCLOUD

Map Attributes, Copy IDP URL & Download Cert

Under USER ATTRIBUTE MAPPING, add email (email), firstName (firstname), and lastName (lastname). Copy the IDP URL (SSO URL), click Activate, download the IdP Certificate (.pem) from the left certificate menu, and assign User Groups.

STEP 4 • IN KYOROX DASHBOARD

Save Connection in Add Connection Studio

In the KyoRox Control Plane (kyorox.com/dashboard), open Add Connection Studio, select custom_saml (Generic OASIS SAML 2.0), paste your JumpCloud IdP Entity ID, IDP URL, and X.509 PEM Certificate, add your Allowed Redirect URI, and click Save & Encrypt Connection.

JUMPCLOUD SAML 2.0 CONFIGURATION SUMMARY 
SP Entity ID             : https://sso.kyorox.com/metadata/{YOUR_TENANT_UUID}
ACS URL                  : https://sso.kyorox.com/auth/sso/{YOUR_TENANT_UUID}/acs
SAMLSubject NameID       : email (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
Sign Assertion           : Checked (RSA-SHA256)
User Attribute Mapping   : email -> email | firstName -> firstname | lastName -> lastname
KyoRox Provider Key      : custom_saml
PROVIDER GUIDE 05 • PROVIDER KEY: ping_identity

PingIdentity (PingOne & PingFederate) — Step-by-Step SAML 2.0 Setup

Connect PingOne Cloud or PingFederate SP Connections to KyoRox in 4 guided steps.

dashboard value: ping_identity
STEP 1 • IN PING ADMIN CONSOLE

Create a New SAML 2.0 Application

In PingOne go to Applications ➔ + Add Application ➔ SAML Application ➔ Manually Enter (or in PingFederate open SP Connections ➔ Create Connection).

STEP 2 • PASTE KYOROX SP ENDPOINTS

Configure ACS URLs & Entity ID

Paste your KyoRox ACS URL into ACS URLs and paste your KyoRox SP Entity ID into Entity ID. Set Subject NameID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress and enable Sign Assertion (RSA-SHA256).

STEP 3 • EXPORT FROM PINGIDENTITY

Map Attributes & Export Signing Certificate

Under Attribute Mappings, map email (Email Address), firstName (Given Name), and lastName (Family Name). Open the Configuration tab, copy the Issuer ID (IdP Entity ID), copy the Single Signon Service URL, and download the Signing Certificate (X.509 PEM).

STEP 4 • IN KYOROX DASHBOARD

Save ping_identity Connection in Control Plane

In kyorox.com/dashboard, open Add Connection Studio, select ping_identity (PingFederate / PingOne), paste the Ping Issuer ID, Single Signon Service URL, and PEM Certificate, enter your HTTPS Allowed Redirect URI, and click Save & Encrypt Connection.

PINGIDENTITY SAML 2.0 CONFIGURATION SUMMARY 
ACS URLs                 : https://sso.kyorox.com/auth/sso/{YOUR_TENANT_UUID}/acs
Entity ID                : https://sso.kyorox.com/metadata/{YOUR_TENANT_UUID}
Assertion Signing        : Sign Assertion (RSA-SHA256)
Subject NameID Format    : urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Attribute Mapping        : email -> Email Address | firstName -> Given Name | lastName -> Family Name
KyoRox Provider Key      : ping_identity
PROVIDER GUIDE 06 • PROVIDER KEYS: custom_saml / onelogin

Custom OASIS SAML 2.0 (OneLogin, Keycloak, Duo, Auth0, ADFS)

KyoRox supports any standards-compliant OASIS SAML 2.0 Identity Provider using the three universal SAML federation parameters.

dashboard value: custom_saml / onelogin
STEP 1 • UNIVERSAL SP CONFIGURATION

Register KyoRox as Service Provider in Your IdP

Create a SAML 2.0 Service Provider client in OneLogin, Keycloak, Duo, Auth0, or ADFS. Paste your KyoRox SP Entity ID and ACS URL (HTTP-POST binding) from your KyoRox Dashboard.

STEP 2 • SIGNATURE & NAMEID RULES

Enable RSA-SHA256 Signed Assertions

Configure your IdP to sign the SAML Assertion or Response using RSA-SHA256 and send the user's email address in NameID (or inside an email attribute statement).

STEP 3 • PEM CERTIFICATE CHECKLIST

Export Standard X.509 PEM Certificate

Export your IdP's public signing certificate in standard Base64 PEM format enclosed between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

STEP 4 • IN KYOROX DASHBOARD

Bind Provider in Add Connection Studio

In KyoRox Add Connection Studio, select custom_saml (or onelogin for OneLogin Enterprise), paste the IdP Entity ID, IdP SSO URL, and PEM Certificate, add your Allowed Redirect URI, and save.

REQUIRED X.509 PEM CERTIFICATE FORMAT CHECKLIST 
-----BEGIN CERTIFICATE-----
MIIDdTCCAl2gAwIBAgILBAAAAAABFUtaw5QwDQYJKoZIhvcNAQEFBQAwVzELMAkG
... (Base64 Encoded Public X.509 IdP Signing Certificate Body) ...
-----END CERTIFICATE-----
CORE GUIDE C • DOWNSTREAM APPLICATION HANDOFF

3. Backend HS256 JWT Verification & Redirect Handoff

After KyoRox verifies the IdP's RSA-SHA256 XML assertion in volatile RAM (<15ms) and locks the AssertionID nonce for 300 seconds, it redirects the user to your whitelisted HTTPS redirect_uri with a signed 5-minute HS256 JWT.

NODE.JS (EXPRESS / NEXT.JS / Node.js) — HS256 JWT VERIFICATION 
import jwt from 'jsonwebtoken';

// Callback route matching your whitelisted Allowed Redirect URI
app.get('/sso/callback', (req, res) => {
  const token = req.query.access_token || req.query.token;
  if (!token) return res.status(401).send('Missing SSO token');

  // Verify using your 256-bit JWT Client Secret from KyoRox Control Plane
  const claims = jwt.verify(token, process.env.KYOROX_CLIENT_SECRET, {
    algorithms: ['HS256']
  });

  // Standardized zero-PII pass-through claims:
  // claims.sub, claims.email, claims.given_name, claims.family_name, claims.roles, claims.idp
  req.session.user = { email: claims.email, idp: claims.idp, roles: claims.roles || [] };
  return res.redirect('/workspace');
});
PYTHON (FASTAPI / DJANGO / FLASK) — PYJWT VERIFICATION 
import os, jwt
from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/sso/callback")
def sso_callback(access_token: str):
    try:
        claims = jwt.decode(
            access_token,
            os.environ["KYOROX_CLIENT_SECRET"],
            algorithms=["HS256"]
        )
        return {"authenticated_user": claims["email"], "idp": claims.get("idp")}
    except jwt.PyJWTError:
        raise HTTPException(status_code=401, detail="Invalid or expired KyoRox SSO JWT")
CORE GUIDE D • DAY-2 LIFECYCLE & SECURITY OPERATIONS

4. Connection Maintenance, Certificate Renewal & API Key Rotation

How to keep your enterprise SAML connections healthy over time with zero authentication downtime.

Contact Support Desk →
OPS 01 • CERTIFICATE RADAR

Monitor 30 / 14 / 7-Day X.509 Expiry Alerts

KyoRox automatically parses the validTo date of every uploaded IdP X.509 certificate and displays live expiry telemetry inside your Control Plane Overview. Growth and Enterprise plans also receive automated pre-expiry email alerts.

OPS 02 • ZERO-DOWNTIME CERT UPDATE

Updating an Expiring IdP Certificate

To renew an expiring IdP certificate without deleting your connection, open Add Connection Studio, select the same idp_provider key (e.g., okta), and submit the new X.509 PEM certificate. KyoRox atomically updates the encrypted vault record in place.

OPS 03 • ATOMIC SECRET ROTATION

Rotating Your API Key & JWT Client Secret

In the API Keys & JWT Vault tab, request a 6-digit verification code sent to your registered workspace email and trigger Rotate API Key & Secret. Update KYOROX_CLIENT_SECRET in your backend environment variables immediately.

OPS 05 • OPEN-SOURCE VERIFICATION REPOS

Official Node.js & Python JWT Verifiers

Clone our zero-dependency reference implementations on GitHub: kyorox-node-jwt-example ↗ and kyorox-python-jwt-example ↗, or read our architecture deep-dives on Dev.to (@kyorox) ↗.

OPS 04 • 24–36H ENGINEERING DESK

Direct Engineering Assistance

Need help debugging an enterprise buyer's custom SAML assertion or upgrading your connection quota? Email support@kyorox.com for guaranteed 24 to 36 hour engineering resolution.