SAML 2.0 SSO Integration Guide

This guide describes how to configure SAML 2.0 Single Sign-On (SSO) for AgileSec Platform, including integration with Microsoft Entra ID and other SAML-compliant identity providers. It explains the required prerequisites, configuration steps, role mapping, and troubleshooting to enable secure federated authentication.

Overview

This guide provides instructions for configuring SAML 2.0 Single Sign-On (SSO) on the AgileSec Platform. AgileSec acts as the Service Provider (SP) and supports integration with SAML 2.0 identity providers.

SSO enables users to authenticate through your organization's Identity Provider and access the AgileSec Platform without maintaining separate credentials.

Prerequisites

Before beginning SSO configuration, ensure you have:

Required Permissions

On AgileSec Platform:

• SaaS Deployment: Org Admin role

• On-Premises Deployment: Platform Admin role

On Identity Provider:

• Administrative access to create and configure applications

• Ability to retrieve IdP metadata URLs

• Permission to manage user groups and assignments

Web Configuration

To enable the SSO button on sign-in pages for on-premise, non-saas deployments, configure the following environment variables for AgileSec Frontend Web in config_envs/webui:

Restart the web service to apply the above settings changes.

Gather Service Provider Information from AgileSec

Step 1: Log into AgileSec Platform

Log into AgileSec Platform with your privileged role:

• SaaS: Log in as Org Admin

• On-Premises: Log in as a Platform Admin (e.g., admin user)

Step 2: Navigate to Authentication Options

Navigate to Settings > Authentication Options , toggle enable SAML 2.0 Single Sign-On , and click Settings:

Step 3: Get Service Provider Information

On SAML2.0 Single Sign-On Configuration screen locate the Service Provider Information section

Note: If all fields under Service Provider Information are not filled, close and open settings again

Step 4: Copy Service Provider Information

Copy the following values exactly as displayed for later. Alternatively, keep this browser window open as you complete the remaining steps:

SAML 2.0 SSO Setup

In order to configure SAML 2.0 SSO for AgileSec, this section goes through the following instructions:

1. Configuring your SAML 2.0 SSO Identity Provider

2. Configuring AgileSec Platform to trust your IdP

3. Testing the SSO configuration

Configure Your SAML 2.0 SSO Identity Provider

Step 1: Create SAML Application

1. Create a new SAML 2.0 application in your identity provider.

2. Use AgileSec Platform as the name or customize as needed.

Entra Example: Create Enterprise Application

1. Navigate to Azure Portal > Entra ID > Enterprise applications.

2. Click New application.

3. Click Create your own application.

4. Enter application name: Keyfactor AgileSec .

5. Select Integrate any other application you don't find in the gallery

6. Click Create.

Step 2: SAML Configuration

Configure the following SAML attributes in your IdP:

Entra Example: Configure Basic SAML Settings

1. In your new Enterprise Application, go to Single sign-on.

2. Select SAML as the single sign-on method.

3. In the Basic SAML Configuration section, click Edit.

4. Configure the following with the gathered prerequisite Service Provider Information:

   • Identifier (Entity ID): Paste the SP Entity ID

   • Reply URL (Assertion Consumer Service URL): Paste the Callback URL

   • Sign on URL: (Optional) Paste the SP-initiated SSO URL

5. Click Save.

Step 3: Configure Group/Role Claim Attributes

For role mapping, configure your IdP to send user group memberships with the following:

1. Attribute Name: Configure a name for the group attribute (e.g., groups, roles, memberOf)

2. Attribute Value: Configure to send user group memberships

3. Format: Set group names or identifiers to map to AgileSec roles

Important:

• Document the exact attribute name you use (e.g., groups) – this will be your customKey (API) or Claim Name (UI) in when submitting the configuration.

• Note the exact group names/identifiers your IdP sends – these must match exactly in role mapping (case-sensitive).

• Ensure the attribute sends all relevant groups for each user.

Entra Example: Configure Group Claims for Role Mappings

1. In the Attributes & Claims section, click Edit.

2. Click Add a group claim.

3. Configure the group claim:

   • Select Security groups

   • Source attribute: Group ID

4. Click Save.

5. Note the group Claim name for use later. It is typically http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

Step 4: Configure User Attributes

Your IdP must send the following attributes in the SAML response for user profile mapping:

Note: The exact attribute names may vary by IdP. Some providers use givenName and surname. Document the attribute names you configure—you will need them when submitting the configuration.

Entra Example: Verify Name Attributes (optional but recommended)

To map first and last names to user profiles:

1. Verify the following claims are present in Attributes & Claims:

   • givenname → User's first name

   • surname → User's last name

2. If not present, add them using the default mappings.

Step 5: Complete Application Setup

1. Save your SAML configuration.

2. Complete any additional provider-specific settings.

3. Ensure the application is enabled/active.

Step 6: Retrieve IdP SAML Metadata URL

Locate your Identity Provider's SAML metadata:

1. Find the SAML metadata section in your application configuration

2. Copy the SAML Metadata URL (also called Federation Metadata URL)

3. The URL typically ends with /metadata or federationmetadata.xml

Example formats:

• Generic: https://idp.example.com/app/app-id/sso/saml/metadata

• Okta: https://dev-xxxx.okta.com/app/exk.../sso/saml/metadata

• Azure AD: https://login.microsoftonline.com/{tenant}/federationmetadata/2007-06/federationmetadata.xml

Verify the metadata URL:

• Open the URL in a browser

• Confirm it returns XML content containing certificates and endpoints

• If the URL is not publicly accessible, check if you need to whitelist AgileSec IP addresses

Save this URL - you will need it for submitting the configuration.

Entra Example: Retrieve IdP SAML (Federation) Metadata URL

1. In the SAML Certificates section locate App Federation Metadata URL.

2. Copy and save the complete URL for later.

3. Example format: https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml.

Step 7: Assign Users and Groups

1. Navigate to your identify provider’s user/group assignment section.

2. Assign the users or groups who should have access to AgileSec Platform.

3. Verify assigned users are members of groups you plan to map to AgileSec roles.

4. Ensure at least one test user is assigned with appropriate group membership.

Entra Example: Assign Users and Groups

1. Go to Users and groups.

2. Click Add user/group.

3. Select the users or groups who should have access to AgileSec Platform.

4. Assign and save.

Configure AgileSec Platform to Trust SAML 2.0 IdP

You may submit the configuration via AgileSec Platform’s UI or API.

Submit Configuration via UI

Step 1: Navigate to Configuration Page

1. Sign in to AgileSec with an Org Admin role (SaaS) or Platform Admin (On-Premises) role.

2. Navigate to: Settings > Authentication Options > SAML 2.0 Single Sign-On Configuration.

Step 2: Configuration

1. Authorization Settings

   1. Assertions Signed: Enable (recommended)

   2. Authentication Response Signed: Disabled (or enable based on your IdP configuration)

2. Identity Provider Configuration

   1. Either paste IdP Federation metadata manually by selecting Manual or enter SAML Metadata URL to fetch information automatically.

3. Role Mapping Configuration

   1. Claim Name: Enter the claim attribute name

      1. For Entra groups, this is typically http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

   2. Click + to add role mappings for each Azure AD group:

      1. IDP Role: IdP Group/Role ID or name

         1. For Entra, this is the Azure AD Group Object ID (GUID format)

      2. AgileSec Role: Select the corresponding role (e.g., Platform Admin, Org Admin, or Org User)

4. User Profile Mapping (Optional)

   1. First Name Attribute: SAML attribute for user's first name

      1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

   2. Last Name Attribute: SAML attribute for user's last name

      1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

5. Click Save.

Submit Configuration via API

Step 1: Obtain Access Token

To submit configuration using the API, you first need to authenticate and obtain an access token.

Use the following curl command to get a web access token:

curl -X 'POST' \
  'https://<analytics external fqdn>/v1/organization/users/sign-in' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "staySignIn": true,
  "email": "admin@<agilesec-org-domain>",
  "password": "<admin password>"
  }'

Parameters:

• <agilesec-platform-fqdn>: Your AgileSec Platform FQDN (e.g., analytics.kf-agilesec.com).

• <agilesec-org-admin>: Your AgileSec Platform organization domain(e.g., kf-agilesec.com).

• <admin-password>: The admin user password set during installation.

Example Response:

{
  "accessToken":"eyJhbGciOiJFUzM4NCIsInRva2VuVmVyc2lvbiI6IjAxIiwia2lkIjoiN2U5MDdlMGVlOTQwZGU5MmUyMTFlYzM3ZjZkNDQ2YWUifQ.eyJzdWIiOiIxNzcwNjYzODg0MTA3IiwiaXNzIjoic20tc2VydmljZSIsInR5cGUiOiJyb290IiwidXNlcklkIjoiNjk4NmIwYWUyNzFhZjFmMjliZWI1YzQ5Iiwib3JnSWQiOiI2OTg2YjBhZTI3MWFmMWYyOWJlYjVjMTciLCJhdWQiOiJpc2ctc2Vuc29yIiwiZmVhdHVyZXMiOlsiYW5hbHl0aWNzIl0sInJlZiI6IjE3NzA2NjM4ODQxMDciLCJuYmYiOjE3NzA2NjAyODQsImV4cCI6MTc3MDY2NTY4NCwiaXNnLXJvbGUiOiJrZi1hZ2lsZXNlY19jb20tYWRtaW4iLCJpYXQiOjE3NzA2NjAyODQsImVtYWlsIjoiYWRtaW5Aa2YtYWdpbGVzZWMuY29tIn0.AqpfE104NUeHvPZBlrbPDBXY3EJLMUK6Pt6qdRiPo8KACuy5QlTxDKrziXgqT1TWWf6rFQ_7WrFsOhAYcDCVF7j2NLoe69a7pCv0rYVshJdoO-6yr1_LwaVAZHCXW5NY",
  "refreshToken":"eyJhbGciOiJFUzM4NCIsInRva2VuVmVyc2lvbiI6IjAxIiwia2lkIjoiN2U5MDdlMGVlOTQwZGU5MmUyMTFlYzM3ZjZkNDQ2YWUifQ.eyJzdWIiOiIxNzcwNjYzODg0MTA3IiwiaXNzIjoic20tc2VydmljZSIsInR5cGUiOiJyb290IiwidXNlcklkIjoiNjk4NmIwYWUyNzFhZjFmMjliZWI1YzQ5Iiwib3JnSWQiOiI2OTg2YjBhZTI3MWFmMWYyOWJlYjVjMTciLCJhdWQiOiJpc2ctc2Vuc29yIiwiZmVhdHVyZXMiOlsiYW5hbHl0aWNzIl0sInJlZiI6IjE3NzA2NjM4ODQxMDciLCJuYmYiOjE3NzA2NjAyODQsImV4cCI6MTc3MDc1MDI4NCwiaXNnLXJvbGUiOiJrZi1hZ2lsZXNlY19jb20tYWRtaW4iLCJpYXQiOjE3NzA2NjAyODQsImVtYWlsIjoiYWRtaW5Aa2YtYWdpbGVzZWMuY29tIn0.gj6y-7OzDdB_Z_ieakN4QaqnTauTm554iiEVcX45jFfG_VDHaZRmjLRhz33_urxrxHpL1ytt-tiW1cIQzvPOFwjU2MPsn7JdoXWysUuBtA4Uj1oR_c7c1Y2ZgBZLUST-",
  "identifyToken":"eyJhbGciOiJFUzM4NCIsInRva2VuVmVyc2lvbiI6IjAxIiwia2lkIjoiN2U5MDdlMGVlOTQwZGU5MmUyMTFlYzM3ZjZkNDQ2YWUifQ.eyJzdWIiOiIxNzcwNjYzODg0MTA3IiwiaXNzIjoic20tc2VydmljZSIsInR5cGUiOiJyb290IiwidXNlcklkIjoiNjk4NmIwYWUyNzFhZjFmMjliZWI1YzQ5Iiwib3JnSWQiOiI2OTg2YjBhZTI3MWFmMWYyOWJlYjVjMTciLCJhdWQiOiJpc2ctc2Vuc29yIiwiZmVhdHVyZXMiOlsiYW5hbHl0aWNzIl0sInJlZiI6IjE3NzA2NjM4ODQxMDciLCJuYmYiOjE3NzA2NjAyODQsImV4cCI6MTc3MTI2ODY4NCwiaXNnLXJvbGUiOiJrZi1hZ2lsZXNlY19jb20tYWRtaW4iLCJpYXQiOjE3NzA2NjAyODQsImVtYWlsIjoiYWRtaW5Aa2YtYWdpbGVzZWMuY29tIn0.bQAxWAEaZ_biYxrAcJBkGgoqCbS7EhvrSvLc2j_zkcBLC_pZkDujbwEgpvcGoQvNZHzZ4_dptcI6dEkBSA4Bdy2bXlcaYioEAJ6to82nD2vmca833G48o6LMBp77Z17A",
  "tokenExpireAt":"2026-02-09T19:34:44.107Z",
  "refreshTokenExpireAt":"2026-02-10T19:04:44.124Z",
  "identifyTokenExpireAt":"2026-02-16T19:04:44.125Z",
  "type":"root",
  "name":"Admin User",
  "firstName":"Admin",
  "lastName":"User",
  "defaultOrg":true
}

Copy the accessToken value from the response. You will use this token when submitting the configuration.

Step 2: Create Configuration File

Create a json file named idp-config.json with your IdP SAML metadata URL and other SSO configuration details:

{
  "orgSamlId": "<orgSAMLId>",
  "idpMetadata": "metadata_url",
  "metadataUrl": "<metadata url>",
  "wantAssertionsSigned": true,
  "wantAuthnResponseSigned": false,
  "signatureAlgorithm": "sha256",
  "customKey": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups",
  "rolesMapping": [
    {
      "idp": "<group id of admin group from Entra ID>",
      "isg": "admin"
    },
    {
      "idp": "<group id of user group from Entra ID",
      "isg": "user"
    }
  ],
  "nameMapping": {
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
  }
}

If the SAML Metadata URL is not accessible from the AgileSec Platform, you can configure the IdP metadata manually:

1. Go to your IdP's SAML metadata URL.

2. Copy the entire XML content.

3. Escape all double quotes (") as \".

4. Replace all line breaks with \n to make it a single line string.

5. Set idpMetadata: "manual" and paste the escaped XML string into metadataUrl.

{
  "orgSamlId": "<orgSAMLId>",
  "idpMetadata": "manual",
  "metadataUrl": "<md:EntityDescriptor xmlns:md=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"http://www.okta.com/exkz624hhp\">\r\n<script id=\"magic-eden-extension\" data-extension-id=\"mkpegjkblkkefacfnmkajcjmabijhclg\"/>\r\n<md:IDPSSODescriptor WantAuthnRequestsSigned=\"false\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\">\r\n<md:KeyDescriptor use=\"signing\">\r\n<ds:KeyInfo xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\">\r\n<ds:X509Data>\r\n<ds:X509Certificate>MIIDtDCCApygAwIB...HRWpIiFO8H7Q==</ds:X509Certificate>\r\n</ds:X509Data>\r\n</ds:KeyInfo>\r\n</md:KeyDescriptor>\r\n<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>\r\n<md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"https://sample.okta.com/app/sample_agilesec/exkz624hhp/sso/saml\"/>\r\n<md:SingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"https://sample.okta.com/app/sample_agilesec/exkz624hhp/sso/saml\"/>\r\n</md:IDPSSODescriptor>\r\n</md:EntityDescriptor>",
  "wantAssertionsSigned": true,
  "wantAuthnResponseSigned": false,
  "signatureAlgorithm": "sha256",
  "customKey": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups",
  "rolesMapping": [
    {
      "idp": "<group id of admin group from Entra ID>",
      "isg": "admin"
    },
    {
      "idp": "<group id of user group from Entra ID",
      "isg": "user"
    }
  ],
  "nameMapping": {
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
  }
}

Parameter Descriptions:

The following parameters are used when submitting the configuration:

Step 3: Submit configuration

Submit the IdP configuration using the following curl command:

curl -X 'POST' \
  'https://<agilesec-platform-fqdn>/v1/organization/idp-config' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access-token>' \
  -d @idp-config.json

Parameters:

• <agilesec-platform-fqdn>: Your AgileSec Platform FQDN (e.g., analytics.kf-agilesec.com)

• <access-token>: The accessToken value obtained in Step 1.

• idp-config.json: The JSON configuration file created in Step 2.

Example:

curl -X 'POST' \
  'https://analytics.kf-agilesec.com/v1/organization/idp-config' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJFUzM4NCIsInRva2VuVmVyc2lvbiI6IjAxIi...' \
  -d @idp-config.json

Expected Response:

Upon successful configuration, you will receive an HTTP 201 Created status code with a response payload containing the saved configuration:

Test SAML 2.0 SSO

1. Open an incognito/private browser window.

2. Go to SP initiate URL from Service Provider Information.

3. Verify successful login and correct role assignment.

SSO Flow Comparison

Troubleshooting

"CLAIM_NAME_NOT_FOUND" Error

Symptoms:

• Login fails with error message about missing claim

• User cannot complete authentication

Cause: The SAML attribute (claim) name configured in customKey for user roles is not returned by the Identity Provider in the SAML response..

Solution:

For Entra ID:

1. Verify the group claim is configured in Attributes & Claims.

2. Ensure the claim name in Entra ID matches the customKey in AgileSec configuration.

3. Check the claim name includes the full URI if required.

For Okta or other SAML 2.0:

1. Verify the Group Attribute Statement is configured.

2. Ensure the attribute Name matches the customKey in AgileSec configuration.

3. Check if the filter is returning groups for test users.

Issue: "INVALID_ROLE_MAPPING" Error

Symptoms:

• Login fails with error about invalid role.

• User authenticates but cannot access platform.

Cause: The SAML claim specified in customKey is present in the SAML response, but its value does not match any entry in the rolesMapping configuration.

Solution:

For Entra ID:

1. Use the Group Object ID (GUID format), not the display name.

2. Verify the Object ID is copied correctly (no extra spaces).

3. Check if test users are members of mapped groups.

4. Example correct format: "idp": "a1b2c3d4-5678-90ab-cdef-1234567890ab"

For Okta or other SAML 2.0:

1. Use the exact group name as it appears in Okta.

2. Verify case-sensitivity: Okta-Admins ≠ okta-admins.

3. Check if test users are assigned to mapped groups.

4. Verify the group filter is including the correct groups.

Issue: Signature Validation Failed

Symptoms:

• Login fails with signature or certificate error

• Error message mentions signature verification

Cause: SAML signature cannot be verified against IdP certificate.

Solution:

1. Verify Metadata URL:

   • Ensure metadataUrl is correct and accessible.

   • Test URL in browser to confirm it returns XML.

   • Check for network/firewall issues.

2. Check Signing Configuration:

   • For wantAssertionsSigned: true → IdP must sign the Assertion element.

   • For wantAuthnResponseSigned: true → IdP must sign the Response element.

   • Verify signing is enabled in IdP configuration.

3. Verify Algorithm:

   • Ensure signatureAlgorithm matches IdP configuration.

   • Most providers use sha256.

Issue: User Profile Not Updated

Symptoms:

• User login succeeds but name is missing or incorrect

• User profile shows placeholder values

Cause: Name attributes are not being mapped correctly from SAML response.

Solution:

For Entra ID:

1. Verify givenname and surname claims are present in Attributes & Claims.

2. Ensure nameMapping uses full schema URIs in idp-config.json:

   "nameMapping": {
     "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
     "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
   }

For Okta or other SAML 2.0:

1. Verify attribute statements for firstName and lastName are configured

2. Ensure attribute mappings match idp-config.json:

   "nameMapping": {
     "firstName": "firstName",
     "lastName": "lastName"
   }

Issue: Access Denied After Successful Login

Symptoms:

• User can log in but sees "Access Denied" or insufficient permissions

• Dashboard or features not accessible

Cause: User's role is not granted required permissions.

Solution:

1. Verify Group Membership:

   • Check user is member of correct group in IdP.

   • For Entra ID: Check Security Group membership.

   • For Okta: Check Group assignments.

2. Verify Role Assignment:

   • Confirm mapped group grants appropriate AgileSec role.

   • Check rolesMapping configuration includes user's group.

   • Verify isg role value is valid (e.g., root, admin).

3. Check Group Filter:

   • For Okta: Verify group filter regex includes user’s groups

   • Ensure filter pattern: .* or specific pattern matches

Issue: Metadata URL Not Accessible

Symptoms:

• Configuration fails when submitting to AgileSec

• Error about unable to fetch metadata

Cause: AgileSec cannot access the IdP metadata URL.

Solution:

1. Verify URL Accessibility:

   • Test metadata URL from AgileSec server (not just your browser).

   • Check for network/firewall restrictions.

   • Ensure URL is publicly accessible or whitelisted.

2. Check URL Format:

   • Verify complete URL including protocol (https://).

   • Ensure no extra spaces or characters.

   • Confirm URL returns valid XML.

3. Network Configuration:

   • Check if AgileSec server can reach IdP endpoints.

   • Verify DNS resolution.

   • Check for proxy requirements.

4. Alternative: Manual Metadata Configuration

   • If the Metadata URL is not accessible from the AgileSec Platform (e.g., due to firewall restrictions), you can configure the IdP metadata manually by pasting the XML content directly.