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.

1. 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.

2. 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

3. Microsoft Entra ID SAML 2.0 SSO Setup

This section guides you through configuring Microsoft Azure AD (Entra ID) as your Identity Provider for AgileSec Platform using SAML 2.0.

3.1 Gather Service Provider Information from AgileSec

Step 1: Log in to AgileSec Platform

Log in to AgileSec Platform with your privileged role:

• SaaS: Log in as Org Admin

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

Step 2: Navigate to Authentication Options

Navigate to Settings > Authentication Options and 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, they will be needed later. Alternatively, keep this browser window open as you complete the remaining steps:

3.2 Setup Enterprise Application in Entra ID

Step 1: 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: 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:

   • Identifier (Entity ID): Paste the SP Entity ID from Section 3.1: Service Provider Information page

   • Reply URL (Assertion Consumer Service URL): Paste the Callback URL from Section 3.1: Service Provider Information page

   • Sign on URL: (Optional) Paste the SP-initiated SSO URL from Section 3.1: Service Provider Information page

5. Click Save

Step 3: 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 Claim name. It is typically http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

Step 4: 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: Retrieve IdP Metadata URL

1. In the SAML Certificates section

2. Locate App Federation Metadata URL

3. Copy the complete URL

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

Save this URL - you will need it when configuring AgileSec Platform to Trust Entra ID in the next section.

Step 6: Assign Users and Groups

1. Go to Users and groups

2. Click Add user/group

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

4. Assign and save

3.3 Configure AgileSec Platform to Trust Entra ID

3.3.1 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>: You AgileSec Platform FQDN (e.g., analytics.kf-agilesec.com)

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

• <adnmin-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 value of the accessToken attribute from the response. You will use this token in the next step 3.

Step 2: Create Configuration File

Create a json file named idp-config.json with your SSO configuration:

{
  "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 Metadata URL is not accessible from the AgileSec Platform, you can manually configure the IdP metadata .

1. Go to your IdP's 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. Use 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:

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 <acces-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:

3.4 Test Entra ID SSO

1. Open an incognito/private browser window

2. Go to SP initiate URL from Section 3.1: Service Provider Information page

3. Verify successful login and correct role assignment

4. Configure SAML 2.0 SSO with other IdP

This section provides instructions for configuring SAML 2.0 SSO with any SAML 2.0 compliant Identity Provider. The process is similar to Entra ID but with provider-specific differences.

4.1 Gather Service Provider Information from AgileSec

This step is identical to Service Provider Information step in the Entra ID setup. Follow the instructions from Section 3.1: Service Provider Information.

4.2 Configure Your SAML 2.0 Identity Provider

The following instructions are generalized for any SAML 2.0 compliant Identity Provider. Consult your IdP's documentation for specific steps.

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

Step 2: SAML Configuration

Configure the following SAML parameters in your IdP:

Step 3: 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'll need them in Section 4.3.1: Submit Configuration.

Step 4: Configure Group/Role Attribute Statements

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

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

2. Attribute Value: Configure to send user's group memberships

3. Format: Send group names or identifiers that you'll map to AgileSec roles

Important:

• Document the exact attribute name you use (e.g., groups)—this will be your customKey in 4.3.1: Submit 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

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 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 4.3.1: Submit Configuration.

Step 7: Assign Users and Groups

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

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

3. Verify that 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

4.3 Configure AgileSec Platform to Trust SAML 2.0 IdP

4.3.1 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>: You AgileSec Platform FQDN (e.g., analytics.kf-agilesec.com)

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

• <adnmin-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 value of the accessToken attribute from the response. You will use this token in the next step.

Step 2: Create Configuration File

Create a json file named idp-config.json with your SSO configuration:

{
  "orgSamlId": "<orgSAMLId>",
  "idpMetadata": "metadata_url",
  "metadataUrl": "<metadata url>",
  "wantAssertionsSigned": true,
  "wantAuthnResponseSigned": false,
  "signatureAlgorithm": "sha256",
  "customKey": "<group claim>",
  "rolesMapping": [
    {
      "idp": "<group name of admin group from IdP>",
      "isg": "admin"
    },
    {
      "idp": "<group name of user group from IdP",
      "isg": "user"
    }
  ],
  "nameMapping": {
    "firstName": "<first name attribute>",
    "lastName": "<last name attribute>"
  }
}

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

1. Go to your IdP's 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. Use 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": "<group claim>",
  "rolesMapping": [
    {
      "idp": "<group name of admin group from IdP>",
      "isg": "admin"
    },
    {
      "idp": "<group name of user group from IdP",
      "isg": "user"
    }
  ],
  
  "nameMapping": {
    "firstName": "<first name attribute>",
    "lastName": "<last name attribute>"
  }
}

Parameter Descriptions:

Important Notes:

• Use the **exact group name/identifier** as it appears in your IdP

• Role mapping is **case-sensitive**: `Okta-Admins` ≠ `okta-admins`

• Each user must belong to at least one mapped group - Document your `customKey` and group identifiers for future reference

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 <acces-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:

4.4 Test SAML 2.0 SSO

1. Open an incognito/private browser window

2. Go to SP initiate URL from Section 3.1: Service Provider Information page

3. Verify successful login and correct role assignment

5. SSO Flow Comparison

6. Troubleshooting

6.1 "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 that the claim name includes the full URI if required

For SAML 2.0 (Okta):

1. Verify the Group Attribute Statement is configured

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

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

6.2 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 that test users are members of mapped groups

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

For SAML 2.0 (Okta):

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

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

3. Check that test users are assigned to mapped groups

4. Verify the group filter is including the correct groups

6.3 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

6.4 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:

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 SAML 2.0 (Okta):

1. Verify attribute statements for firstName and lastName are configured

2. Ensure attribute mappings match:

json

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

6.5 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 doesn't grant 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

6.6 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.