Setting Up Knox with JWT Federation Authentication (Lessons Learned)

["Amirthalingam, Thivviyan" <Th...@LibertyMutual.com>]

Hello,

My team and I worked on setting up Knox with our go-forward enterprise Identity Provider(IDP), PING Federate. We found the integration to be challenging but, with the recent changes the Knox team made in version 0.14, we were able to make it possible.

I’d would like to share some points here so that, the token based authorization can be more utilized with a wider range of enterprise IDPs.

Enable Client Credentials Grant Type Tokens
Despite the changes made to version 0.14, we still had to modify the source code to allow our grant type. Most OAuth 2.0 Grant Types require a “client_id” request parameter but, the JWT implementation in Knox uses a “sub” parameter instead. This greatly restricts the use of this class, and by extension the JWT Token Federation option, to other grant types such as Authorization Code, Implicit, Password Credentials, Device Code, Refresh Token and, the type PING Federate uses, Client Credentials.

Reference: https://oauth.net/2/grant-types/

As a temporary solution, we had to manually change the public string SUBJECT in JWT.java public interface from String SUBJECT = "sub"; to String SUBJECT = "client_id";. This enables us to instantiate the JWT class with the token provided by PING Federate.

Code File: https://github.com/apache/knox/blob/master/gateway-spi/src/main/java/org/apache/knox/gateway/services/security/token/impl/JWT.java

As a more tangible solution, might I suggest adding a separate parameter field for the grant types and use “sub” or “client_id” as per the type specified in the topology file?

Enable Web Location for Token Verification Pem
PING allows an URL that hosts the pem file. Most of our application are built so that it can use that web location’s content as opposed to hard coding the pem file into the topology file. Hardcoding creates a continuity problem when the IDP changes the pem file. To cater that, we had also add a public class in the CertificateUtils class that parses a RSA Public Key URL. Attached, you can find the JWTFederationFilter.java and CertificateUtils.java, the 2 main classes we had to modify to make this happen.

Code Files: https://github.com/apache/knox/blob/master/gateway-util-common/src/main/java/org/apache/knox/gateway/util/CertificateUtils.java
https://github.com/apache/knox/blob/master/gateway-provider-security-jwt/src/main/java/org/apache/knox/gateway/provider/federation/jwt/filter/JWTFederationFilter.java


Documentation Updates
I’d would like to also suggest a few additions to the JWT Provider section in the user guide so that the this method can be utilized against a wider range of IDPs.

Name

Description

Default

jwt.expected.issuer

Optional parameter. This parameter allows the administrator to constrain the use of tokens via the JWT issuer. The default provider is set to KNOXSSO and this parameter has to be modified for other IDPs.

KNOXSSO

jwt.expected.sigalg

Optional parameter. This parameter allows the administrator to constrain the tokens allowed via a specific signature algorithm. The default value is RS256 and this value has to be specific if the token issued by the IDP uses a different signature algorithm.

RS256


Hope this information will help future Knox-JWT/OAuth SSO implementations. Additionally, I’d be more than happy to contribute code or walk through our specific implementation of setting up Knox with PingFederate OAuth tokens. Please let me know!


Thivviyan Amirthalingam
Software/ Systems Engineer
Liberty Mutual Insurance - Commercial Insurance IT
Data Lake Industrialization - Data, Finance and Billing
350 E. 96th Street, Indianapolis, IN 46240
Direct Dial: 317-581-6978
[cid:C627A001-4456-457C-8098-C753EC9F3A7D]

Re: Setting Up Knox with JWT Federation Authentication (Lessons Learned)

[larry mccay <lm...@apache.org>]

Hi Tjivviyan -

This is great information - thank you for contributing it back to the Knox
community!

I think that we should actually go down a couple roads with this:

1. File a JIRA for Ping Federate support and we ca discuss there what
things are general improvements and what is Ping specific
2. Create a HowTo wiki article for Ping Federate would be really good for
folks to use as a blueprint - these are much easier to use than the Admin
Guide which is almost more like a reference guide to features.

I can help out with both of the above - if need be.

thanks again!

--larry

On Tue, Mar 27, 2018 at 6:15 PM, Amirthalingam, Thivviyan <
Thivviyan.Amirthalingam@libertymutual.com> wrote:

> Hello,
>
> My team and I worked on setting up Knox with our go-forward enterprise
> Identity Provider(IDP), PING Federate. We found the integration to be
> challenging but, with the recent changes the Knox team made in version
> 0.14, we were able to make it possible.
>
> I’d would like to share some points here so that, the token based
> authorization can be more utilized with a wider range of enterprise IDPs.
>
>
>
> *Enable Client Credentials Grant Type Tokens*
>
> Despite the changes made to version 0.14, we still had to modify the
> source code to allow our grant type. Most OAuth 2.0 Grant Types require a
> “client_id” request parameter but, the JWT implementation in Knox uses a
> “sub” parameter instead. This greatly restricts the use of this class, and
> by extension the JWT Token Federation option, to other grant types such as
> Authorization Code, Implicit, Password Credentials, Device Code, Refresh
> Token and, the type PING Federate uses, Client Credentials.
>
>
>
> Reference: https://oauth.net/2/grant-types/
>
>
>
> As a temporary solution, we had to manually change the public string
> SUBJECT in JWT.java public interface from String SUBJECT = "sub"; to String
> SUBJECT = "client_id";. This enables us to instantiate the JWT class with
> the token provided by PING Federate.
>
>
>
> Code File: https://github.com/apache/knox/blob/master/gateway-spi/
> src/main/java/org/apache/knox/gateway/services/security/
> token/impl/JWT.java
>
>
>
> As a more tangible solution, might I suggest adding a separate parameter
> field for the grant types and use “sub” or “client_id” as per the type
> specified in the topology file?
>
>
>
> *Enable Web Location for Token Verification Pem*
>
> PING allows an URL that hosts the pem file. Most of our application are
> built so that it can use that web location’s content as opposed to hard
> coding the pem file into the topology file. Hardcoding creates a continuity
> problem when the IDP changes the pem file. To cater that, we had also add a
> public class in the CertificateUtils class that parses a RSA Public Key
> URL. Attached, you can find the JWTFederationFilter.java and
> CertificateUtils.java, the 2 main classes we had to modify to make this
> happen.
>
>
> Code Files: https://github.com/apache/knox/blob/master/
> gateway-util-common/src/main/java/org/apache/knox/gateway/
> util/CertificateUtils.java
>
> https://github.com/apache/knox/blob/master/gateway-
> provider-security-jwt/src/main/java/org/apache/knox/
> gateway/provider/federation/jwt/filter/JWTFederationFilter.java
>
>
>
>
> *Documentation Updates*
>
> I’d would like to also suggest a few additions to the JWT Provider section
> in the user guide so that the this method can be utilized against a wider
> range of IDPs.
>
>
>
> Name
>
> Description
>
> Default
>
> jwt.expected.issuer
>
> Optional parameter. This parameter allows the administrator to constrain
> the use of tokens via the JWT issuer. The default provider is set to
> KNOXSSO and this parameter has to be modified for other IDPs.
>
> KNOXSSO
>
> jwt.expected.sigalg
>
> Optional parameter. This parameter allows the administrator to constrain
> the tokens allowed via a specific signature algorithm. The default value is
> RS256 and this value has to be specific if the token issued by the IDP uses
> a different signature algorithm.
>
> RS256
>
>
>
> Hope this information will help future Knox-JWT/OAuth SSO implementations.
> Additionally, I’d be more than happy to contribute code or walk through our
> specific implementation of setting up Knox with PingFederate OAuth tokens.
> Please let me know!
>
>
>
>
>
> *Thivviyan Amirthalingam*
>
> Software/ Systems Engineer
>
> Liberty Mutual Insurance - Commercial Insurance IT
>
> Data Lake Industrialization - Data, Finance and Billing
>
> 350 E. 96th <https://maps.google.com/?q=350+E.+96th&entry=gmail&source=g> Street,
> Indianapolis, IN 46240
> Direct Dial: 317-581-6978 <(317)%20581-6978>
>
>
>