Page tree
Skip to end of metadata
Go to start of metadata


How to setup Kiuwan with a Local Authentication system

You can integrate Kiuwan with a Local Authentication system.

This is a common scenario in organizations that validate their employees' credentials against their own authentication system, and do not want them to use other credentials when accessing external services. 

If your company uses a corporate authentication service, your users and passwords will most probably be stored in Active Directory, OpenLDAP, IBM Tivoli or any other similar system.

If that is your case, it’s not needed to have different credentials for your Kiuwan account, you can use existing ones.


By integrating Kiuwan with your Local Auth service, you will make Kiuwan authentication to delegate on your own system, avoiding the need to use/maintain additional credentials.


Local Authentication scenarios

Depending on your infrastructure, there are at least two possible scenarios:

  1. Centralized Authentication

    1. Do you need to login to every system in your organization using the same user/password ? Are you tired to type the same credentials to access different systems? This is a clue that your organization maintains a centralized authentication system (i.e. your organization is keeping your credentials in a unique system) that is used by the different systems.

  2. Single Sign-On (SSO)

    1. Do you only need to authenticate once and you are able to access the different systems? That is an evidence that your systems are internally using an authentication system that is shared by the different applications, making unneeded to type your credentials when you access those systems. This is what is called a Single Sign-On environment.

If you want to avoid using/maintaining Kiuwan credentials, ask you first which of the above models apply to your organization, and don’t care, Kiuwan supports both !!


Follows two different mechanisms to make Kiuwan work in a SSO environment.

  1. If your organization is using a centralized credentials repository that does not support SAML (the most widely adopted SSO standard), you can configure Kiuwan to use it as described in section DelegatedAuthenticationSingleSign-On 

  2. Instead, if you organization is using a SAML-compliant repository (e.g. Active Directory FS, Azure AD, CA Single Sign-On, etc), you can configure Kiuwan to use SAML (as described in section SingleSign-on(SSO)withSAML2.0)


Delegated Authentication Single Sign-On

Centralized authentication is also known as “delegated authentication”.

In this scenario, Kiuwan delegates your authentication to an external system, it’s a matter of trust!!

How this can be accomplished? Take a look at the next image.

In this scenario:

  1. Login to Kiuwan

    1. First, you must login to Kiuwan …. but not to !! No, you need to setup an specific URL within your domain. Something similar to, or something similar.

  2. Identify user

    1. That URL will be received by an “authentication service application” that will delegate your authentication to an external system, e.g. Active Directory, LDAP or a similar system.

  3. Redirect to with token

    1. The corporate authentication system checks if you do already have a security context or you need to identify. If the authentication succeeds, the authentication service application will generate a JWT authentication token including the username (encrypted using a secret key that you can generate in your Kiuwan account settings page).

    2. Once the auth token is ready, the system redirects to your browser

  4. Authenticated request

    1. The browser request access to with an authenticated request that recognizes, granting access to the requested resource.

You can find a sample authentication service application (kiuwan/kiuwan-local-authentication) as a sample to get started. This sample application uses Tomcat (tomcat-users.xml) as authentication mechanism, but you can freely adapt to any other external auth system.

You can find details on how to set up here 

Single Sign-on (SSO) with SAML 2.0

As you have seen during the explanation of Centralized Authentication scenario, you need to provide some authentication service application that generates the auth token based on kiuwan’s provided secret key. Therefore, to use this scenario you must setup this specific app.


A different approach is to use a more advanced approach that makes use of a “standard” mechanism to which most vendors adhere to (SAML’s Single Sign-One)


Since April 2019 release, Kiuwan allows you to login in a SAML Single Sign-One (SSO) environment.


By implementing SSO, a user is able to log in to different independent systems through the use of a single set of credentials, centrally managed in a repository

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

  • A User requesting for some resource or service

  • A Service Provider (SP) that receives the request and provides the service or access to the resource

  • An Identity Provider (IdP) that authenticate the user and asserts the user identity

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

Kiuwan currently supports SAML and this document serves as a how-to use Kiuwan in a SSO-SAML environment.

In summary, if your organization is using some kind of centralized users’ credentials repository implementing SAML and you want to use those enterprise credentials to authenticate in Kiuwan, this document provides you with information on how to set up Kiuwan to participate in a SSO-SAML environment.

What is SAML?


SAML stands for Security Assertion Markup Language and it’s an open standard for exchanging authentication and authorization data between partiesIn particular, between an identity Provider (IdP) and a Service Provider (SP).

SAML is an XML-based markup language for security assertions usually transferred from IdPs to SPs. These assertions are used by SPs to make access-control decisions.

Basically, SAML assertions contains 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 does 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 are:

  • 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


The most important SAML 2.0 profile is the Web Browser SSO Profile, and it’s fully supported by Kiuwan.


SAML Security requirements

The SAML specifications recommends:

  • TLS 1.0+ for transport-level security

  • XML Signature and XML Encryption for message-level security

Web Browser Single Sign-On

  1. The user (usually a trough a web browser) requests a resource to 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 not a 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, SP returns the resource to the user agent.

SAML 2.0 Metadata

In the Web Browser SSO workflow above, there are some interactions between the IdP and the SP that 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?


These and other similar “trust” conditions are based on the use of SAML 2.0 Metadata.


Metadata ensures a secure transaction between an IdP and a SP through sharing of trust information.

SAML 2.0 provides a well-defined, interoperable metadata format that entities can leverage to bootstrap the trust process.

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

  • Identity Provider metadata (to publish identity information about the IdP itself)

  • Service Provider metadata (to publish identity information about the SP itself)

Also the endpoints of communication are also 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)

How to configure Kiuwan to work with SSO - SAML


As explained before, Kiuwan plays the role of Service Provider (SP) in a SSO - SAML context.

To configure SSO in Kiuwan you must first, of course, rely on an existing Identity Provider (IdP). There are many available IdP systems, all of them sharing SAML concepts (more or less adapted to their own 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


Kiuwan provides an administration page to configure your IdP metadata.

You can find SSO configuration page at Account Management >> Organization and clicking on Configure SSO button.

Please read carefully the notes:

  • By activating the SSO in your account, all users of your account will be automatically migrated to your own domain to avoid conflict with other usernames in other Kiuwan accounts.

  • After this migration, all users of your account must use a new URL for the Login, leaving the login URL that you have been using until now. This new URL will be communicated to you in the next step of this page.

  • In order to continue using the Kiuwan Local Analyzer, API REST, Kiuwan for Developers, or any other plugin that needs to request for some data to Kiuwan, you must change the configuration and indicate the DOMAIN ID in their respective configuration screens. This DOMAIN ID will be provided when you activate the SSO. (see further sections on these topics)

  • Once activated the SSO, you must communicate to all your users the new login URL and your DOMAIN ID.

  • Once SSO is activated, it is NOT possible to disable it or re-migrate users to the previous Kiuwan domain.

  • Event though the activation process is completed, you will need to register Kiuwan as SP in your IdP. Till then, you can not use SSO. See section on “Kiuwan’s metadata configuration in ADFS”

Clicking on Continue button you can upload you IdP Metadata XML.

In a typical ADFS installation you can commonly get it at: https://<your_idp_domainname>/FederationMetadata/2007-06/FederationMetadata.xml


If your IdP is Azure AD, please be sure to check My IdP is Azure AD.

Once it’s loaded, click on Continue button


At this moment, you should have received an email with an activation code as well as Domain Id and Login URL. Enter the activation code and click Activate SSO button.

Note: See How to login at Kiuwan in a Web SSO scenario on how to use the loign URL.

  • If you want to avoid currently existing Kiuwan users to 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 login through SSO (using the provided URL).
  • If you don’t check that option, existing users can still login using user/password, but using the new URL. Older Kiuwan URL will not work any more because all the users have been migrated to SSO.


IMPORTANT: Is your users are using Kiuwan Local Analyzer, DO NOT CHECK THIS OPTION, because all the users will be forced to use SSO. Because KLA still does not fully support SSO, if checked you will need to manually activate user/password auth for all KLA’s users !!


Admin users can ALWAYS login both ways. Other users can be managed individually as using Kiuwan auth or SSO (see User management).

Example mail with activation code:



After SSO activation, you will get the URL you need to configure Kiuwan as a SP in your IdP  (see section Kiuwan’s metadata configuration in ADFS here ).

Close the page and .. voilà ! Your Kiuwan SSO configuration is done!!

In case you further need to update existing metadata with new IdP metadata just to SSO initial configuration page and Upload a new IdP Metadata.

Click on Save to complete the update

After metadata configuration, you will see the following data into your Kiuwan account.

At Account Management >> Profile you will see :

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

  • This ID is needed to login to your kiuwan account and it’s shared by all users of a Kiuwan account, but unique for every Kiuwan account.

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

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

IdP configuration : How to configure Kiuwan as Service Provider


You must configure your IdP (Identity Provider) so it can recognize Kiuwan as a SP (Service Provider).

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

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

Active Directory Federation Services (ADFS) configuration

You can use ADFS’s Add Relying Party Trust wizard

Select Claims aware option and Start.

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 (see image below)

In case your ADFS cannot reach the Kiuwan server, you can 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

Next step is to provide a Display name for Kiuwan.

You can choose any name, it doesn’t have to be a domain hostname.

Next step is to choose the Access Control Policy that will govern the access rules of your organization’s users to Kiuwan.

After choosing a policy, just confirm (or change) and click Next.

Review the information from the SP (relying party) and click next to finish the SP configuration in ADFS.

Notice that “Configure claims issuance policy ..” is checked.

When checked, you will define how to map/transform your organization’s users to Kiuwan users.

 Edit Claim Issuance Policy dialog will pop up:

Clicking on Add Rule will open Add Transform Claim Rule Wizard.

First, you must select the template rule most adequate to your organization.

In the example, we select to map a LDAP attribute




You can select whatever LDAP attribute that it’s unique to every user. In this example we are using 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.

Doing this way, Kiuwan will store as username the selected attribute value.


After finishing, apply changes


How to login at Kiuwan in a Web SSO scenario



First time you login at Kiuwan in SSO-modeyou need to specify the full URL such as:


Please note that, once SSO has been activated, the login URL must specify both sso and domain parameters. 


  • sso=on will make Kiuwan to authenticate against the configured IdP
  • sso=off will make Kiuwan to authenticate locally, so login page will ask for credentials and will check them against kiuwan database (obviously this process will only work for users that are allowed to login with kiuwan passwords, see SSO login vs username-passwordl ogin)


If you don't specify sso, it defaults to off.



Most commonly, in a 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 manually such url.

Anyway, once you have successfully accessed Kiuwan for the first time, your browser will store the domain id, so you can just type and everything will work.

Then, Kiuwan SSO Login page will be displayed.

Just click on Log In button 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 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:


Just select the site (the Display Name defined at your IdP) , you will be asked for your credentials and will be redirected to Kiuwan dashboard!!

How to configure Kiuwan clients to work with SSO - SAML



After configuring SSO, you web users can immediately login to Kiuwan website using the new login URL.

But, Kiuwan “clients” (i.e. Kiuwan Local Analyzer, Kiuwan 4 Developers, and any custom program using Kiuwan REST-API) need to be configured to use SSO.


Kiuwan Local Analyzer (KLA) : SSO configuration


Once SSO is configured, it's mandatory to configure KLA with the SSO Domain ID.

Otherwise KLA will stop to work!!


Nevertheless, KLA will still use user/password configuration (a new KLA with SSO authentication will be released shortly).


In summary, after SSO activation:

  1. Configure KLA with SSO Domain ID

  2. Be sure KLA users are allowed to use username/password authentication

KLA’s SSO Domain ID configuration can be done in three different ways:

First, by using KLA GUI as the image shows:

Also, by modifying file:

Additionally, if you are using KLA CLI you can also specify property as a command line parameter.

Kiuwan for Developers (K4D) : SSO configuration



Similarly to KLA SSO configuration, K4D also needs to be configured with Domain ID

Go to you IDE’s Kiuwan configuration, select Connection Properties >> Single Sign-On section/tab 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: {}" -u {username}:{password}


SSO login vs username-password login


When a Kiuwan account is converted to SSO-enabled, by default, all existing users :

  1. They must use the new login URL (see How to login at Kiuwan in a Web SSO scenario )
    1. Previous URL login ( will not work any more 
  2. Usernames and permissions are entirely preserved
    1. Only the authentication mechanism has changed. Usernames, assgined roles, permissions, usergroups, etc are maintained.
  3. By default, existing users (not admins) are not allowed to login to kiuwan using former Kiuwan's password
    1. They will be authenticated by the configured IdentityProvider (IdP), not by Kiuwan.


Nevertheless, you might want certain users to being authenticated also by Kiuwan, i,e, some user might choose to authenticate either by SSO or by Kiuwan.


The Kiuwan admin can enable username-password access through User Administration page, enabling Login with password enabled to selected users 





Users with privilege "Login with password enabled" can then login to Kiuwan in two ways:

  1. Authenticated by SSO 
  2. Authenticated by Kiuwan (by password)



Adding a new user in a SSO-enabled account


In a SSO-enabled account, when you create a new user you can decide if that user can access Kiuwan with password (besides SSO).


Just check Enable login with password option at New User page and, of course, click on Generate password to let him/her know (wink)



Obviously, do not click on Generating password and not Enable Login with password, that password would be useless (...)


Appendix  - Azure Active Directory configuration : How to configure Kiuwan as Service Provider

You must configure your Idp (Azure AD) so it recognizes Kiuwan as a SP (Service Provider).

In Azure AD, you should create an Enterprise Application (Kiuwan SSO, in this example).

To do it, select Azure Active Directory >> Enterprise applications 


and click on New application 

Select Non-gallery application and fill in the app name (Kiuwan SSO in our example) and click Add button

Just created, you will see a page like this.


Next, you will need to add users that will be allowed to login at Kiuwan SSO application.


Select the users from your Azure Active Directory that will be allowed to login to Kiuwan SSO application.

Now that some user has been added, you need to configure the Single sign-on 

First, you need to export the Azure Active Directory metadata and import it to Kiuwan.

To export AAD metadata, click on Download link at Federation Metadata XML.




Downloaded XML file needs to be imported into your Kiuwan account , as shown before.

After importing AAD metadata into Kiuwan, your Kiuwan account will be ready to generate its own metadata that you will import into AAD.



To export Kiuwan metadata, go to Account Management >> Organization and you will see the URL to download Kiuwan metadata.


Just type the URL in a browser and save the content as a XML file.



Now, you can import (upload) the Kiuwan metadata XML file into AAD.


Once uploaded, click con Save.

Once done, you need to set your Claims policy. To do it, click on User Attributes & Claims

Select Name identifier value

and setup the policy on how to manage your ADA usernames to Kiuwan usernames.

In this example, we take the first part of email.

For example, an AAD user with email will be mapped to john.doe when sent to Kiuwan.

Now, you can test Single Sign-On with Kiuwan SSO app.

Just click to Test button.

Select the user (the current or someone else)



Because you are already logged in ADD (and therefore authenticated) you will be forwarded directly to Kiuwan app.


Login from Kiuwan site

Login from Kiuwan site

To login at Kiuwan site, you must go to SSO URL (remember to set sso=on and set the domain)
You will be presented with the login page (without need to write your credentials)

When you click on Login button, you will be forwarded to Azure login page:



Type your credentials (AAD will authenticate you), and (if succesfull)  you will be logged in at Kiuwan site




Probalby, you are worndering why do you need to authenticate if you are already logged at AAD..

This second authentication has been deliberately forced by Kiuwan, because very often IdPs (AAD, ADFS, etc) send to Kiuwan "old" auth tokens, making SSO fail.
To prevent these situations, Kiuwan force IdP to perform the auth process and send to Kiuwan a "fresh" tocken, that's the reason AAD asks you to authenticate.

  • No labels