This guide describes how to configure Apache Knox to authenticate users against Okta using the KnoxSSO service together with the pac4j federation provider.
After completing the steps in this guide, users accessing Knox-protected resources are redirected to Okta for authentication and then returned to Knox with a signed SSO cookie.
How It Works
Knox supports the following identity provider integration models:
The login form is hosted directly by Knox.
KnoxSSO delegates authentication to an external Identity Provider (IdP).
Okta functions as a SAML Identity Provider (IdP). To integrate Okta with KnoxSSO:
Create a SAML application in Okta that points to the KnoxSSO callback endpoint.
Enable the pac4j federation provider in the Knox topologies.
Configure Knox to delegate authentication requests to Okta.
Trino Gateway functions as a load balancer, query router, and proxy server. Unlike a generic load balancer, it supports rule-based query routing and advanced request handling capabilities.
Create the SAML Application in Okta
In the Okta Admin Console, navigate to:
Select:
Configure the SAML application using the following values.
SAML Settings
Single Sign On URL:
https://DEMO-EXAMPLE:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client
Recipient URL:
https://DEMO-EXAMPLE:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client
Destination URL:
https://DEMO-EXAMPLE:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client
Audience Restriction:
https://DEMO-EXAMPLE:8443/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client
Name ID Format:
EmailAddress
Response:
Signed
Assertion Signature:
Signed
Signature Algorithm:
RSA_SHA256
Digest Algorithm:
SHA256
Assertion Encryption:
Unencrypted
SAML Single Logout:
Disabled
SAML Signed Request:
Disabled
The following values must point to the same KnoxSSO callback endpoint:
Single Sign On URL
Recipient URL
Destination URL
Audience Restriction
Update Knox Topologies
Once the Okta application is configured, update the required Knox topologies so that Knox delegates authentication to Okta using the pac4j federation provider.
Update the following topologies:
In the Ambari UI, navigate to:
The pac4j federation provider integrates Knox with Okta SAML, while the remaining topology configuration remains unchanged.
Update Admin Topology
Update the admin.xml topology configuration with the following content:
<topology>
<gateway>
<provider>
<role>federation</role>
<name>pac4j</name>
<enabled>true</enabled>
<param>
<name>pac4j.callbackUrl</name>
<value>https://{{knox_gateway_host}}:{{knox_gateway_port}}/gateway/knoxsso/api/v1/websso</value>
</param>
<param>
<name>clientName</name>
<value>SAML2Client</value>
</param>
<param>
<name>saml.identityProviderMetadataPath</name>
<value>https://{{example.okta.com}}/app/{{appId}}/sso/saml/metadata</value>
</param>
<param>
<name>saml.serviceProviderMetadataPath</name>
<value>/tmp/sp-metadata.xml</value>
</param>
<param>
<name>saml.serviceProviderEntityId</name>
<value>https://{{knox_gateway_host}}:{{knox_gateway_port}}/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client</value>
</param>
</provider>
<provider>
<role>identity-assertion</role>
<name>Default</name>
<enabled>true</enabled>
<param>
<name>principal.mapping</name>
<value>guest@example.com=guest;</value>
</param>
</provider>
</gateway>
<service>
<role>KNOXSSO</role>
<param>
<name>knoxsso.cookie.secure.only</name>
<value>false</value>
</param>
<param>
<name>knoxsso.token.ttl</name>
<value>100000</value>
</param>
<param>
<name>knoxsso.redirect.whitelist.regex</name>
<value>^https:\\/\\/example\\.ambari-server-host\\.com(:[0-9]+)?\\/.*</value>
</param>
</service>
</topology>
Update KnoxSSO Topology
Update the knoxsso.xml topology configuration with the following content:
<gateway>
<provider>
<role>webappsec</role>
<name>WebAppSec</name>
<enabled>true</enabled>
<param>
<name>xframe.options.enabled</name>
<value>true</value>
</param>
</provider>
<provider>
<role>federation</role>
<name>pac4j</name>
<enabled>true</enabled>
<param>
<name>pac4j.callbackUrl</name>
<value>https://{{knox_gateway_host}}:{{knox_gateway_port}}/gateway/knoxsso/api/v1/websso</value>
</param>
<param>
<name>clientName</name>
<value>SAML2Client</value>
</param>
<param>
<name>saml.identityProviderMetadataPath</name>
<value>https://{{example.okta.com}}/app/{{appId}}/sso/saml/metadata</value>
</param>
<param>
<name>saml.serviceProviderMetadataPath</name>
<value>/tmp/sp-metadata.xml</value>
</param>
<param>
<name>saml.serviceProviderEntityId</name>
<value>https://{{knox_gateway_host}}:{{knox_gateway_port}}/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client</value>
</param>
</provider>
<provider>
<role>identity-assertion</role>
<name>Default</name>
<enabled>true</enabled>
</provider>
</gateway>
Update Advanced Topology
Update the required advanced topology with the following content:
<gateway>
<provider>
<role>federation</role>
<name>pac4j</name>
<enabled>true</enabled>
<param>
<name>pac4j.callbackUrl</name>
<value>https://{{knox_gateway_host}}:{{knox_gateway_port}}/gateway/knoxsso/api/v1/websso</value>
</param>
<param>
<name>clientName</name>
<value>SAML2Client</value>
</param>
<param>
<name>saml.identityProviderMetadataPath</name>
<value>https://{{example.okta.com}}/app/{{appId}}/sso/saml/metadata</value>
</param>
<param>
<name>saml.serviceProviderMetadataPath</name>
<value>/tmp/sp-metadata.xml</value>
</param>
<param>
<name>saml.serviceProviderEntityId</name>
<value>https://{{knox_gateway_host}}:{{knox_gateway_port}}/gateway/knoxsso/api/v1/websso?pac4jCallback=true&client_name=SAML2Client</value>
</param>
</provider>
<provider>
<role>identity-assertion</role>
<name>Default</name>
<enabled>true</enabled>
<param>
<name>principal.mapping</name>
<value>guest@example.com=guest;</value>
</param>
</provider>
</gateway>
Restart Knox
After updating the topology configurations:
Save the topology changes.
Restart the Knox service from Ambari.
Services → Knox → Restart
This applies the updated SAML authentication configuration across all configured Knox topologies.
