Configure SAML SSO for Konnect with Microsoft Entra ID

Before configuring Basic SAML in Entra ID, get and save your Konnect organization ID. You’ll need this to build the SAML values Entra ID expects. Send a GET request to the /organizations/me endpoint:

curl -X GET "https://global.api.konghq.com/v3/organizations/me" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

Also decide on the login path you want to use for your Konnect organization, and export it as an environment variable. This will be appended to the Konnect login, for example: https://cloud.konghq.com/login/$LOGIN_PATH You’ll use this same value in both Entra ID and Konnect:

export LOGIN_PATH='my-org'

Configure SAML authentication for your Enterprise app in Entra:

1. In the application, click Single sign-on in the sidebar.
2. Select SAML as the single sign-on method.
3. In the Basic SAML Configuration section, click Edit.
4. In the Identifier (Entity ID) field, enter https://cloud.konghq.com/sp/$KONNECT_ORG_ID.
5. In the Reply URL (Assertion Consumer Service URL) field, enter https://global.api.konghq.com/v2/authenticate/$LOGIN_PATH/saml/acs.
6. In the Sign on URL field, enter https://cloud.konghq.com/login/$LOGIN_PATH.
7. Click Save.
8. In the sidebar, click Users and groups, then click Add user/group and assign the Entra ID group you want to map to a Konnect team.
9. In the Attributes & Claims section, click Edit.
10. Configure the following claims. For each claim, clear the namespace URI before saving:
    1. Set Unique user identifier to user.userprincipalname.
    2. Click Add a group claim, select Groups assigned to the application, and set the Source attribute to Cloud-only group display names so the SAML assertion sends the group’s name rather than its object ID. Then click Advanced options, select Customize the name of the group claim, and enter user.groups in the Name field.
    3. Click Add new claim and add a claim named firstname with source attribute user.givenname. Click Save.
    4. Click Add new claim and add a claim named lastname with source attribute user.surname. Click Save.
    5. Click Add new claim and add a claim named email with source attribute user.mail. Click Save.
11. Navigate back to your SAML settings and copy the App Federation Metadata URL from the SAML Certificates section, and export it as an environment variable. You’ll need this in the next section:

    export APP_FEDERATION_METADATA_URL='YOUR-APP-FEDERATION-METADATA-URL'

    Copied!

Important: Use the App Federation Metadata URL, not the tenant-level metadata URL. Using the tenant-level URL causes an invalid SAML response error due to a certificate mismatch.

Create the SAML identity provider using the App Federation Metadata URL from Microsoft Entra ID and the login path you chose earlier, by sending a POST request to the /identity-providers endpoint. Konnect uses the login path to generate your organization’s custom login URL: https://cloud.konghq.com/login/$LOGIN_PATH.

Capture the identity provider’s ID as $IDP_ID:

IDP_ID=$(curl -X POST "https://global.api.konghq.com/v3/identity-providers" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "type": "saml",
       "login_path": "'$LOGIN_PATH'",
       "config": {
         "idp_metadata_url": "'$APP_FEDERATION_METADATA_URL'"
       }
     }' | jq -r ".id"
)

Before you can map teams from Entra, you must create them or modify the existing teams in Konnect.

1. Create the Konnect team you want to map to an Entra ID group, and capture its ID as $TEAM_ID, by sending a POST request to the /teams endpoint. If you already have a team to map, send a GET request to the /teams endpoint instead, filtered on its name, to look up its ID:

   TEAM_ID=$(curl -X POST "https://global.api.konghq.com/v3/teams" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "name": "IDM - Developers",
          "description": "The Identity Management (IDM) team."
        }' | jq -r ".id"
   )

   Copied!

2. Map the Entra ID group to the team by sending a POST request to the /identity-providers/{idpId}/team-group-mappings endpoint:

   curl -X POST "https://global.api.konghq.com/v3/identity-providers/$IDP_ID/team-group-mappings" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "team_id": "'$TEAM_ID'",
          "group": "'$ENTRA_GROUP_NAME'"
        }'

   Copied!

   The $ENTRA_GROUP_NAME is the name of the group in Entra that you exported in the prerequisites. Repeat this request for each additional team you want to map.

1. Enable SAML as an authentication method for your organization by sending a PATCH request to the /authentication-settings endpoint:

   curl -X PATCH "https://global.api.konghq.com/v3/authentication-settings" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "saml_auth_enabled": true
        }'

   Copied!

2. Team mappings let you automatically assign Konnect teams based on Entra ID group membership. Enable IdP mapping by sending a PATCH request to the /authentication-settings endpoint:

   curl -X PATCH "https://global.api.konghq.com/v3/authentication-settings" \
        --no-progress-meter --fail-with-body  \
        -H "Authorization: Bearer $KONNECT_TOKEN" \
        --json '{
          "idp_mapping_enabled": true
        }'

   Copied!

1. Navigate to your custom login URL: https://cloud.konghq.com/login/$LOGIN_PATH. You will be redirected to the Microsoft Entra ID sign-in page.
2. Log in with your Entra ID credentials. If the configuration is correct, you are authenticated into Konnect.