Single Sign-on SSO with SAML

This guide explains how to integrate SSO with SAML 2.0 and Kiuwan.

In a SAML-based SSO environment, we can define the following actors or participants:

• User: Request access to a resource or service
• Service Provider (SP): Provides access to the service or resource (Kiuwan acts as a SP)
• Identity Provider (IdP): Authenticates the user and confirms their identity

SSO can be implemented through different protocols, with SAML and OpenId Connect being the most widely used.

Kiuwan currently supports SAML. This document serves as a how-to for using Kiuwan in an SSO-SAML environment.

If your organization uses a centralized user credential system based on SAML, you can integrate it with Kiuwan for seamless authentication.

 

What is SAML?

SAML assertions contain three types of statements:

1. Authentication statements
   • Example: User U has been successfully authenticated at time T using method M of authentication
2. Attribute statements
   • Example: User U contains value V for attribute A
3. Authorization statements
   • Example: User U is permitted to perform action A on resource R

Besides assertions, SAML defines SAML protocols, i.e., the processing rules to use assertions between SPs and IdPs.

Examples of such protocols are :

• Assertion Query and Request Protocol
• Authentication Request Protocol
• etc.

These SAML protocols can be mapped to standard messaging formats. This mapping is called a SAML binding. Examples of such bindings include:

• SAML SOAP Binding
• HTTP Redirect (GET) Binding
• HTTP POST Binding
• etc.

Finally, SAML profiles describe in detail how SAML assertions, protocols, and bindings combine to support a defined use case.

SAML 2.0 provides support for many profiles such as:

• Web Browser SSO Profile
• Identity Provider Discovery Profile
• Assertion Query/Request Profile
• etc

SAML Security Requirements

The SAML specifications recommend:

• TLS 1.0+ for transport-level security
• XML Signature and XML Encryption for message-level security

 

Web Browser Single Sign-On

The following image describes how Single Sign-On works: 

1. The user (usually through a web browser) requests a resource from a Service Provider (SP)
2. If a valid security context does not exist, the SP redirects the user agent to the Identity Provider’s (IdP) SSO Service
3. The user agent issues a request to the IdP’s SSO Service to identify the user (if there’s no previous security context)
4. IdP validates the request and responds to the user agent
5. The user agent sends the “authentication” assertion to the SP
6. The SP processes the assertion and redirects the user agent to the requested resource
7. The user agent requests SP for the requested resource
8. Finally, the SP returns the resource to the user agent.

SAML 2.0 Metadata

In the Web Browser SSO workflow above, some interactions between the IdP and the SP are based on mutual trust, for example:

• How does the SP know the IDP is authentic? And in turn, how does the IdP know the SP is authentic?
• How does the SP know where to send the user agent with the auth request? And how does the IDP know where to send the user agent with the auth response?
• How does the IdP encrypt the SAML assertion so that the trusted SP (and only the trusted SP) can decrypt the assertion?
• How does the service provider know that the auth response is coming from a trusted IDP?

Regarding SSO SAML actor’s identity, metadata are defined for:

• Identity Provider metadata (to publish identifying information about the IdP itself)
• Service Provider metadata (to publish identifying information about the SP itself)

Also, the endpoints of communication are defined by metadata, such as:

• SSO Service metadata (description of IdP’s SSO endpoint)
• Assertion Consumer Service (desc of SP’s service to send assertions from the IDP)

 

Configure Kiuwan for SSO - SAML

To configure SSO in Kiuwan, first, rely on an existing Identity Provider (IdP). There are many available IDP systems, sharing SAML concepts (more or less adapted to their terminology).

As seen above, to set up a Web SSO environment, SAML agents (idP and SP) need to be identified and let each other know of their existence. This step is accomplished by exchanging each other’s metadata.

 

Kiuwan configuration: How to configure your IDP in Kiuwan

1. Go to Account Management > Organization and select Configure SSO.Read the notes shown in the window carefully.
   
2. Click Continue to upload your IdP Metadata XML.
   In a typical ADFS installation, you can commonly get it at https://<your_idp_domainname>/FederationMetadata/2007-06/FederationMetadata.xml
   
3. If your IdP is Azure AD, check the checkbox My IdP is Azure AD. After loading click Continue.
   
4. Activate SSO, using the activation code from Kiuwan's email. This email also includes the Domain ID and Login URL
   
   • If you want to avoid currently existing Kiuwan users login using former credentials (username and password), check Disable login with password for all my users. By checking this option, all the users will be forced to log in through SSO (using the provided URL).

   • If you don’t check that option, existing users can still log in using user/password, but using the new URL. The older Kiuwan URL will not work anymore because all the users have been migrated to SSO.

     Note: If you have users who use the Kiuwan Local Analyzer Checking this option, a user launching the Kiuwan Local Analyzer will not be able to use it unless:
     - Configures KLA to use SSO, selecting "Enable Single sign-on" and filling in the Domain ID and connection credentials.
     - An administrator allows him to still use Kiuwan credentials (see  User Management) AND the KLA is configured filling the Domain ID and with "Enable Single sign-on" unchecked. 

     Admin users can ALWAYS log in both ways. Also, can always modify which Kiuwan users are allowed to log in using Kiuwan credentials (see User Management).

5. After SSO activation, you will get the URL you need to configure Kiuwan as an SP in your IdP.
   

Update existing metadata

If you need to update existing metadata with new IdP metadata, follow these steps:

1. Go to the SSO initial configuration page and click Upload a new IdP Metadata. Click Save to complete the update.
   
2. The wizard displays a message indicating that the update was successful.
   

After metadata configuration, go to Account Management > Profile and you will see the following data in your Kiuwan account.

Domain ID only appears when your Kiuwan account is configured to use SSO.

• This ID is needed to log in to your Kiuwan account. It is shared by all users of a Kiuwan account, but unique for every Kiuwan account.

Username field contains your Kiuwan username. It matches the Claim mapping (Name ID) defined in your IDP when you defined Kiuwan as a Service Provider (see image above for ADFS).

Note: Email, Name, and Lastname fields are descriptive data about the user.

IdP configuration: How to configure Kiuwan as Service Provider

The IdP (Identity Provider) must be configured to recognize Kiuwan as an SP (Service Provider).

Any SAML-compliant IdP (Active Directory FS, Azure AD, CA Single Sign-On, etc)  follows its configuration method, although the steps are similar.

We provide a detailed example of how to configure Active Directory Federation Services (ADFS). For other IdPs please refer to your sysadmins or product documentation.

Active Directory Federation Services (ADFS) configuration

1. Open ADFS’s Add Relying Party Trust wizard
2. Select Claims aware and click Start.
   

3. Then, ADFS will ask you about Kiuwan’s identity metadata.
   

   Ideally, if your ADFS can reach Kiuwan servers, you will select the first option (Import data .. online).

   Then you must provide the address that can be found at your Kiuwan website at Account Management > Organization page.

   If your ADFS cannot reach the Kiuwan server, upload the XML metadata document by selecting Import data... from a file.

   In this case, you must previously download the XML document from the KIuwan URL above. Just paste the URL in a browser that can access the Kiuwan server

4. Provide a Display name for Kiuwan (It doesn’t have to be a domain hostname.)
   
5. Choose the Access Control Policy that will govern the access rules of your organization’s users to Kiuwan. Click Next to confirm.
   
6. Review the information from the SP (relying party) and click Next to finish the SP configuration in ADFS.
   
7. Notice that Configure claims issuance policy.. is checked. When checked, you will define how to map/transform your organization’s users to Kiuwan users.
   Click Close and Edit Claim Issuance Policy dialog will pop up.
   
8. Click Add Rule to open Add Transform Claim Rule Wizard.
   
9. Select the template rule most adequate for your organization. In the example, we select to map an LDAP attribute.
   
10. You can select whatever LDAP attribute that it’s unique to every user (i.e. the user’s email address) and map that attribute to the Name ID claim type. Do not select any other claim type, Kiuwan will only use Name ID. Kiuwan will store as a username the selected attribute value. Click Finish.
    
11. Click Apply to apply changes.
    

How to log into Kiuwan in a Web SSO scenario

Most commonly, in an SSO environment, you will access Kiuwan from an existing link in a corporate intranet page, so the Kiuwan URL should be changed to it and you will not need to type the URL manually. Regardless, once you have successfully accessed Kiuwan for the first time, your browser will store the domain ID, so you can just type https://www.kiuwan.com and everything will work.

Then, the Kiuwan SSO Login page will be displayed.

Just click Log In and the SSO-SAML protocol will be activated.

• If you were already successfully authenticated, you will log in to Kiuwan.
• If not, you will be redirected to your organizational authentication page. Once authenticated, you will be redirected to the Kiuwan dashboard.

An alternative method to login to Kiuwan is from your IdP.

If you are using ADF, you will find a URL like this: https://<your_idp_hostname>/adfs/ls/idpInitiatedsignon.htm

Just select the site (the Display Name defined at your IDP). Provide your credentials to be redirected to the Kiuwan dashboard.

Configuring Kiuwan clients for SSO -SAML

Kiuwan Local Analyzer (KLA): SSO configuration

Further reading: Please refer to Single Sign On for more information on how to configure Kiuwan Local Analyzer with SSO.

Kiuwan for Developers (K4D): SSO configuration

K4D needs to be configured with the Domain ID of your account.

Go to your IDE’s Kiuwan configuration, select Connection Properties > Single Sign-On, and enter your Domain ID.

REST-API: SSO configuration

For custom programs using Kiuwan REST-API calls, you have to add a new header (X-KW-CORPORATE-DOMAIN-ID) to indicate the Domain ID to pass the BASIC authentication.

For example:

curl -H "X-KW-CORPORATE-DOMAIN-ID: {domain.id}" -u {username}:{password} https://api.kiuwan.com/info