Community Articles
Find and share helpful community-sourced technical articles
Alert: Welcome to the Unified Cloudera Community. Former HCC members be sure to read and learn how to activate your account here.
Labels (2)

In part I of this series, we reviewed preliminaries related to SSO, including LDAP authentication for Ambari, and we set up an application in Okta that would correspond to our KnoxSSO service provider for the SAML authentication flow. We are now ready to configure Knox within Ambari.

We will replace the Form-based IdP configuration that Knox comes with out of the box with the pac4j federation provider. Pac4j is a Java security library and it is used as a federation provider within Knox to support the OAuth, CAS, SAML and OpenID Connect protocols. It must be used for SSO, in association with the KnoxSSO service (and optionally with the SSOCookieProvider for access to REST APIs).

In Ambari, we'll navigate to Knox > Config > Advanced knoxsso-topology and add XML similar to the following:







A couple of things to note here:

  • The callback URL for KnoxSSO is the WebSSO endpoint without the URL parameter
  • The identity provider metadata path points to the metadata for the Okta application you configured in part I
    • You can find this URL in Okta, within your Application configuration on the Sign On tab. See Identity Provider metadata in the screenshot below (under the View Setup Instructions button)
  • The service provider metadata path is a dummy location, this can't be NULL or you will see an exception in the current release
  • The principal mapping converts the username that Okta presents to the shortname used throughout HDP. A regex mapping is available and be more manageable for Produciton
  • Note the setting. It's important that the session cookie only be served for HTTPS to protect from session hijacking.
  • The knoxsso.redirect.whitelist.regex must match your environment, is a dummy placeholder in the topology file above


After Knox has been configured, the last step is to configure Ambari for SSO and we'll do this from the command line. You'll need to SSH to the host where Ambari Server is running.

As a preliminary step, you'll need the public certificate for Knox. You can use this snippet, where ${knoxserver} is the host running the Knox Gateway:

openssl s_client -connect ${knoxserver}:8443 < /dev/null | openssl x509 -out /tmp/knox.crt

To configure Ambari, we'll run

sudo ambari-server setup-sso

For the provider URL, enter you callback URL


Then paste the public certificate without the header and footer (don't include the BEGIN CERTIFICATE or END CERTIFICATE lines).

You can accept all other defaults.

Finally, you'll need to run

sudo ambari-server restart

You should now be all set! After saving the above Knox configuration in Ambari and restarting Knox and any required services, try navigating to Ambari to test.

If everything has been set up correctly, you'll be logged in to Ambari after authenticating to Okta.

In future posts in this series, we'll take a look at the Form-based IdP that's included with KnoxSSO, setting up SSO for Ranger, and other topics!

Super Collaborator

Great article!


Hi There,

Following the below document from Hortonworks we have configured the KNOXSSO using OKTA(SAML). But, while accessing ambari web UI using Okta single sign on, the redirecturl is unable access the KNOX end point. Could you please share your thoughts on troubleshooting the issue as shown in the screenshots below.

Federation provider: pac4j

SAML IDP provider: Okta

Service provider: KnoxSSO


error:18/06/07 17:01:39 ||2c5194ce-fb4e-4049-bdb9-dac767934214|audit||KNOXSSO||||access|uri|/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client|failure|

gateway.log :

2018-06-07 17:01:39,605 ERROR hadoop.gateway ( - Gateway processing failed: javax.servlet.ServletException: org.pac4j.saml.exceptions.SAMLException: Error decoding saml message javax.servlet.ServletException: org.pac4j.saml.exceptions.SAMLException: Error decoding saml message at org.apache.hadoop.gateway.filter.AbstractGatewayFilter.doFilter( at org.apache.hadoop.gateway.GatewayFilter$Holder.doFilter( at org.apache.hadoop.gateway.GatewayFilter$Chain.doFilter( at org.apache.hadoop.gateway.GatewayFilter.doFilter( at org.apache.hadoop.gateway.GatewayFilter.doFilter( at org.apache.hadoop.gateway.GatewayServlet.service( at org.eclipse.jetty.servlet.ServletHolder.handle( at org.eclipse.jetty.servlet.ServletHandler.doHandle( at org.eclipse.jetty.server.handler.ScopedHandler.handle( at at org.eclipse.jetty.server.session.SessionHandler.doHandle( at org.eclipse.jetty.server.handler.ContextHandler.doHandle( at org.eclipse.jetty.servlet.ServletHandler.doScope( at org.eclipse.jetty.server.session.SessionHandler.doScope( at org.eclipse.jetty.server.handler.ContextHandler.doScope( at org.eclipse.jetty.server.handler.ScopedHandler.handle( at org.eclipse.jetty.server.handler.ContextHandlerCollection.handle( at org.eclipse.jetty.server.handler.HandlerWrapper.handle( at org.apache.hadoop.gateway.trace.TraceHandler.handle(

at org.eclipse.jetty.server.handler.HandlerWrapper.handle( at org.apache.hadoop.gateway.filter.CorrelationHandler.handle( at org.eclipse.jetty.servlets.gzip.GzipHandler.handle( at org.eclipse.jetty.server.handler.HandlerWrapper.handle( at org.apache.hadoop.gateway.filter.PortMappingHelperHandler.handle( at org.eclipse.jetty.server.handler.HandlerCollection.handle( at org.eclipse.jetty.server.handler.HandlerWrapper.handle( at org.eclipse.jetty.server.Server.handle( at org.eclipse.jetty.server.HttpChannel.handle( at org.eclipse.jetty.server.HttpConnection.onFillable( at$ at org.eclipse.jetty.util.thread.QueuedThreadPool.runJob( at org.eclipse.jetty.util.thread.QueuedThreadPool$ at Caused by: org.pac4j.saml.exceptions.SAMLException: Error decoding saml message at org.pac4j.saml.sso.impl.SAML2WebSSOMessageReceiver.receiveMessage( at org.pac4j.saml.sso.impl.SAML2WebSSOProfileHandler.receive( at org.pac4j.saml.client.SAML2Client.lambda$clientInit$0( at org.pac4j.core.client.BaseClient.retrieveCredentials( at org.pac4j.core.client.IndirectClient.getCredentials( at org.pac4j.core.engine.DefaultCallbackLogic.perform( at org.pac4j.j2e.filter.CallbackFilter.internalFilter( at org.pac4j.j2e.filter.AbstractConfigFilter.doFilter( at org.apache.hadoop.gateway.pac4j.filter.Pac4jDispatcherFilter.doFilter( at org.apache.hadoop.gateway.GatewayFilter$Holder.doFilter( at org.apache.hadoop.gateway.GatewayFilter$Chain.doFilter( at org.apache.hadoop.gateway.filter.XForwardedHeaderFilter.doFilter( at org.apache.hadoop.gateway.filter.AbstractGatewayFilter.doFilter( ... 32 more Caused by: org.opensaml.messaging.decoder.MessageDecodingException: This message decoder only supports the HTTP POST method at org.pac4j.saml.transport.Pac4jHTTPPostDecoder.doDecode( at org.opensaml.messaging.decoder.AbstractMessageDecoder.decode( at org.pac4j.saml.sso.impl.SAML2WebSSOMessageReceiver.receiveMessage( ... 44 more



federation pac4j true

pac4j.callbackUrl https://knoxhost:8443/gateway/knoxsso/api/v1/websso clientName SAML2Client saml.identityProviderMetadataPath https://xxxxxxxx/app/exk1bs9c6clt0ttLo2p7/sso/saml/metadata saml.serviceProviderMetadataPath /tmp/sp-metadata.xml saml.serviceProviderEntityId https://knoxhost:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client identity-assertion Default true,admin=admin KNOXSSO true knoxsso.token.ttl 30000 knoxsso.redirect.whitelist.regex ^https:\/\/xxxxx\.xxxxx\.com|localhost|127\.0\.0\.1|0:0:0:0:0:0:0:1|::1):[0-9].*{replace49}lt;/value>

Don't have an account?
Coming from Hortonworks? Activate your account here
Version history
Revision #:
2 of 2
Last update:
‎08-17-2019 10:04 AM
Updated by:
Top Kudoed Authors