What is SAML?

Security Assertion Markup Language (SAML) is an XML-based open standard that allows organizations to set up single sign-on (SSO) across multiple websites and applications. SAML 2.0 is the latest standard, and was ratified in March 2005, replacing SAML 1.1. We’ll refer to SAML as meaning SAML 2.0 for the remainder of this document.

SAML is mostly used as a web-based authentication mechanism as it relies on using the browser to broker the authentication flow. The SAML specification defines three roles:

• A Principal (or End User)
  • Almost always a human user who is attempting to access a resource using a Browser
• An Identity Provider (IdP)
  • A service that performs the authentication, by checking usernames and passwords, verifying account status, invoking multi-factor authentication (MFA), etc.
• A Service Provider (SP)
  • Provides services to the end user. Relies of the IdP to assert the identity of a user

SP-initiated SSO with SAML Authentication

The Kong Enterprise SAML implementation supports the SP initiated SSO flow. This flow starts when a user tries to access a resource on the SP. If the SP detects the user doesn’t have a browser session active, it will redirect them to the IdP asking for the authentication request. The IdP will authenticate the user, and if successful, create the SAML assertion and redirect the user back to the SP.

XML messages are not exchanged directly between the IdP and SP, but via the Browser. This is described in the following sequence diagram:

1. Kong Enterprise initiates SSO when a user tries to access a protected Upstream Service
2. Kong Enterprise detects if the user has an active browser session. If no session exists, Kong Enterprise creates an SAML Request, also known as an authentication request. The request can be digitally signed
3. The User’s Browser relays the SAML authentication request to the IdP
4. A SAML Response is generated by the IdP. This response contains the assertion of the authenticated user. This response is digitally signed and optionally encrypted.
5. The SAML Assertion is relayed to Kong Enterprise
6. Kong Enterprise verifies the SAML Response, and either accepts or rejects the initial request to access the Upstream Service

Advantages of SAML

SAML 2.0 is widely adopted by enterprises, for several reasons:

• Improves the user experience, because SAML provides the ability for users to securely access multiple applications with a single set of credentials entered once
• Reduces the risk of weak passwords because users only have one password for all systems
• Moves the responsibility for authentication & management to the IdP, which has the ability to invest in multiple layers of security such as multi-factor authentication (MFA), session management, & user sign-on/off processes (e.g. when an employee leaves a company)
• Reduces IT help desk costs, because users have less access issues and need less help resetting passwords

Kong SAML Plugin Configuration Options

The Kong Enterprise SAML implementation is provided using the Kong SAML plugin, which is available in Kong Enterprise v3.1+. Kong Plugins provide advanced functionality and extend the use of Kong Enterprise. Refer to the [Kong Documentation Plugin Overview](https://docs.konghq.com/hub/plugins/overview/)Kong Documentation Plugin Overview for more information on Kong Plugins.

The minimum configuration for the Kong SAML plugin is detailed below:

• An IdP certificate
  • The SP needs to obtain the public certificate from the IdP to validate the signature in a SAML response. The certificate is stored on the SP and is to verify that a response is coming from the IdP
• ACS Endpoint
  • This is the endpoint provided by the SP where SAML responses are sent. The SP needs to provide this information to the IdP
• IdP Sign-in URL
  • This is the IdP Sign-in endpoint where the Kong SAML plugin will issue authentication requests. The SP needs to obtain this information from the IdP
• Issuer
  • The unique identifier of the IdP application

At the time of writing this document, this plugin supports Microsoft Azure Active Directory as the SAML IdP. Please refer to the [Microsoft AzureAD SAML documentation](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/auth-saml)Microsoft AzureAD SAML documentation for more information about SAML authentication with Azure Active Directory.

Now let’s walk through adding SAML Authentication to a Service in Kong Enterprise using Microsoft Azure AD as the SAML IdP:

1. Set-up a SAML Enterprise Application in Microsoft AzureAD:

   1. Create a SAML Enterprise Application. Refer to the [Microsoft AzureAD documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal)Microsoft AzureAD documentation for more information
   2. From the Manage section of the Enterprise application in AzureAD, select “Single sign-on” and note the Identifier (Entity ID) and Login URL parameters
   3. In the “Basic SAML Configuration” tab displayed above, configure the “Reply URL (Assertion Consumer Service URL)”, for example, https://<your Kong Enterprise IP address here>:8443/aad/consume
   4. From the Manage section of Azure AD Enterprise application, select “Users and groups”, and assign users who will be able to login via SAML SSO

2. Create an Anonymous Kong Consumer

   This permits anonymous Kong Consumer access via SAML Authentication to the Service we will configure in the next step. The anonymous consumer is configured in the SAML plugin

curl --request PUT \
 --url http://localhost:8001/consumers/anonymous

{
   "created_at": 1667352450,
   "custom_id": null,
   "id": "bec9d588-073d-4491-b210-1d07099bfcde",
   "tags": null,
   "type": 0,
   "username": "anonymous",
   "username_lower": null
}

3. Create a Service

curl --request PUT \
 --url http://localhost:8001/services/aad-service \
 --data url=https://httpbin.org/anything

{
   "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd",
   "name": "aad-service",
   "protocol": "https",
   "host": "httpbin.org",
   "port": 443,
   "path": "/anything"
}

4. Create a Route

curl --request PUT \
 --url http://localhost:8001/services/aad-service/routes/aad-route \
 --data paths=/aad

{
   "id": "ac1e86bd-4bce-4544-9b30-746667aaa74a",
   "name": "aad-route",
   "paths": [ "/aad" ]
}

5. Configure the SAML plugin on the Service

Replace the <AzureAD_Identity_ID>, <AzureAD_Sign_on_URL> and <AzureAD_Certificate> placeholders with the values identified in the previous steps

curl --request POST \
 --url http://localhost:8001/services/aad-service/plugins \
 --header 'Content-Type: multipart/form-data' \
 --form name=saml \
 --form config.anonymous=anonymous \
 --form config.issuer=<AzureAD_Identity_ID> \
 --form config.idp_sso_url=<AzureAD_Sign_on_URL> \
 --form config.idp_certificate=<AzureAD_Certificate> \
 --form config.assertion_consumer_path=/consume \

{
   "id": "a8655ba0-de99-48fc-b52f-d7ed030a755c",
   "name": "saml",
   "service": {
       "id": "5fa9e468-0007-4d7e-9aeb-49ca9edd6ccd"
   },
   "config": {
       "assertion_consumer_path": "/consume",
       "validate_assertion_signature": true,
       "idp_sso_url": "https://login.microsoftonline.com/f177d1d6-50rf-49e0-818a-a0585cbafd8d/saml2",
       "issuer": "https://samltoolkit.azurewebsites.net/kong_saml"
   }
}

6. Finally, using a Browser, go to the proxy url exposed by Kong Enterprise “https://:8443/aad”. Since the user is not authenticated, they will be redirected for authentication to Azure AD

Once successfully logged in, Kong Enterprise will allow access to the configured Service.

Conclusion

SAML is a complex XML-based protocol, and in modern terms it is considered legacy compared to the more modern OAuth 2.0 and OpenID Connect protocols. That said, SAML isn’t going away anytime soon; SAML is a widely adopted enterprise solution. For that reason Kong have invested in developing the SAML plugin, and will expand functionality and support for other SAML IdPs in the future.