Contributed by Leonardo Dias

This tutorial will provide the steps to configure and integrate Ipsilon with Knox SSO, using SAML2.

Ipsilon Overview

Ipsilon is a server and a toolkit to configure Apache-based Service Providers. The server is a pluggable selfcontained mod_wsgi application that provides federated SSO to web applications. User authentication is always performed against a separate Identity Management system (for example a FreeIPA server), and communication with application is done using a federation protocol like SAML, OpenID, etc..


Knox SSO will be a Service Provider of Ipsilon.

The following picture illustrates how Ipsilon works and you can see where KnoxSSO is within the architecture as the Application (Service Provider):


  1. Apache Knox installed
  2. Apache Ambari Server installed (for Ambari UI SSO)
  3. Apache Ranger installed (from Ranger UI SSO)
  4. IPA installed and configured
  5. Ipsilon binaries already installed on system


  1. Configure Ipsilon Server with SAML2 support:

    ipsilon-server-install --saml2=yes --form=yes --gssapi=yes --ipa=yes  --info-sssd=yes
  2. Patch the Ipsilon Server to fix NameIDPolicy bug ( Patch is not included on version 1.0.0 of Ipsilon that can be downloaded from EPEL.

    From e23eead22c21258c3a0ef22a65f8e1aebc115b77 Mon Sep 17 00:00:00 2001
    From: Rob Crittenden <>
    Date: Oct 21 2015 14:52:38 +0000
    Subject: Don't crash if no NameIdPolicy is requested
    This fixes two problems:
    1. Logging was done before a None check was completed
    2. The None check was insufficient because the whole object
       could be None
    Signed-off-by: Rob Crittenden <>
    diff --git a/ipsilon/providers/saml2/ b/ipsilon/providers/saml2/
    index 6cbf5ab..6d46ad2 100644
    --- a/ipsilon/providers/saml2/
    +++ b/ipsilon/providers/saml2/
    @@ -254,10 +254,12 @@ class ServiceProvider(ServiceProviderConfig):
         def get_valid_nameid(self, nip):
    - self.debug('Requested NameId [%s]' % (nip.format,))
    - if nip.format is None:
    + if nip is None or nip.format is None:
    + self.debug('No NameId requested, returning default [%s]'
    + % SAML2_NAMEID_MAP[self.default_nameid])
                 return SAML2_NAMEID_MAP[self.default_nameid]
    + self.debug('Requested NameId [%s]' % (nip.format,))
                 allowed = self.allowed_nameids
                 self.debug('Allowed NameIds %s' % (repr(allowed)))
                 for nameid in allowed:
  3. Configure Ipsilon Client on Knox Server. Command is using "" as the Ipsilon Server FQDN.


    ipsilon-client-install --saml-idp-url 
    --saml-sp-name knox
    --saml-auth "/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client"
    --saml-no-httpd --saml-sp-post "/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client"
    --saml-sp "/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client"
    --port 8443 --saml-secure-setup=falseThis command will configure a Service Provider on Ipisilon and generate three files on the current directory:
    certificate.pem, certificate.key and metadata.xml


    Property Name

    --saml-idp-url URL for Ipsilon IDP Server
    --saml-sp-name Alias to Knox Service Provider
    --saml-auth Should match saml.serviceProviderEntityId on KnoxSSO Topology, without server:port
    --saml-no-httpd Generate metadata and certificates local and not configure HTTPD as Service Provides (Knox will be SP)
    --saml-sp-post Should match saml.serviceProviderEntityId on KnoxSSO Topology, without server:port
    --saml-sp Should match saml.serviceProviderEntityId on KnoxSSO Topology, without server:port
    --saml-sp-logout Should match saml.serviceProviderEntityId on KnoxSSO Topology, without server:port
    --portKnox port
    --saml-secure-setupDisable two way SSL




  4. Export IPA/Ipsilon certificate and root certificate to file:

    openssl x509 -in <(openssl s_client -connect -prexit 2>/dev/null) > ipa.pem
    cat /etc/ipa/ca.crt >> ipa.pem
  5. Import IPA/Ipsilon certificate and root certificate to Java Truststore:

    $JAVA_HOME/bin/keytool -import -keystore $JAVA_HOME/jre/lib/security/cacerts -file ipa.pem -alias ipa
  6. Deploy Knox SSO Topology (/etc/knox/topologies/knoxsso.xml or use Ambari to configure it). Template below consider Knox Server on and Ipsilon Server on








Below you can find a description of each parameter set:

Property NameDescription
pac4j.callbackUrlURL used by pack4j. Should match the knoxsso topology URL
clientNameSAML2Client is used for SAML2 client on pac4j
saml.identityProviderMetadataPathIt's the IDP Metadata URL, on Ipsilon use directory saml2/metadata on URL (ex:
saml.serviceProviderMetadataPathThis parameter is configured to workaround an existing bug, it can be configured to any folder. If you don't configure this entry properly, you will get a NullPointerException on Java
saml.serviceProviderEntityIdThis is the ID of the Service Provider on Ipsilon, it should be pac4j.callbackUrl + ?pac4jCallback=true&amp;client_name=SAML2Client
identity-assertionDefault rule will work. If you want to map some users to different usernames, this is the parameter to be changed if HTTPS is enabled on all URL provided by Knox, otherwise must be false
knoxsso.token.ttlTime to live of the cookie in seconds, after this time cookie will be invalid and a new authentication from Ipsilon will be required.
knoxsso.redirect.whitelist.regexRegex that should be matched for Knox to redirect URL to Ipsilon

8) Extract the Knox Certificate from Gateway Keystore, which will be used on Ambari and Ranger configuration.

JAVA_HOME/bin/keytool -export -alias gateway-identity -rfc -file knox.pem -keystore /usr/hdp/current/knox-server/data/security/keystores/gateway.jks

7) Configure Ambari UI for KnoxSSO. On Ambari Server Host run the command:


root@hdp24 ~]# ambari-server setup-sso
Using python  /usr/bin/python
Setting up SSO authentication properties...
Do you want to configure SSO authentication [y/n] (y)?y
Provider URL [URL] (
Public Certificate pem (stored) (empty line to finish input):

Do you want to configure advanced properties [y/n] (n) ?
Ambari Server 'setup-sso' completed successfully.
[root@hdp24 ~]#

NOTE: Do not paste the Header and Footer of certificate when asked for Public Certificate, which is the Knox Certificate. NOTE: LDAP Authentication is required for SSO to work properly, and need to be configured before setting SSO.

8) Restart Ambari Server to apply new configuration

9 Configure Ranger UI for KnoxSSO. On Ambari Server, go to Ranger -> Configs -> Advanced and set Knox SSO Settings:


Ranger UI SSO

NOTE: Do not paste the Header and Footer of certificate when asked for Public Certificate, which is the Knox Certificate.

10) Restart Ranger to apply new configuration

After those steps, all login requests will be redirected to Ipsilon and after authentication, will allow access to both Ranger and Ambari UI.


  • On Ambari Server, to login with local users access the url: http://:8080/#/login/local

  • On Ranger, to login with local users access the url: http://:6080/locallogin

  • No labels