Configure Okta SSO for Apache Knox

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:

Form-based authentication

The login form is hosted directly by Knox.

SAML / Federated authentication

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:

Applications → Applications → Create App Integration

Select:

Bash
    
xxxxxxxxxx
 
SAML 2.0
Copy

Configure the SAML application using the following values.

SAML Settings

Bash
    
xxxxxxxxxx
 
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
Copy

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:

admin
knoxsso
Any advanced topologies that require SSO protection

In the Ambari UI, navigate to:

Services → Knox → Configs → Advanced topology

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:

Bash
    
 
<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&amp;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>
Copy

Update KnoxSSO Topology

Update the knoxsso.xml topology configuration with the following content:

Bash
    
 
<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&amp;client_name=SAML2Client</value>        </param>    </provider>     <provider>        <role>identity-assertion</role>        <name>Default</name>        <enabled>true</enabled>    </provider> </gateway>
Copy

Update Advanced Topology

Update the required advanced topology with the following content:

Bash
    
 
<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&amp;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>
Copy

Restart Knox

After updating the topology configurations:

Save the topology changes.
Restart the Knox service from Ambari.
1. Services → Knox → Restart

This applies the updated SAML authentication configuration across all configured Knox topologies.

Last updated on May 26, 2026

Was this page helpful?