PH44692: OIDC: ADD METHODS TO THE OIDCCLIENTHELPER API TO VERIFY JWTS

APAR status

• Closed as program error.

Error description

• Add methods to the
  com.ibm.websphere.security.oidc.util.OidcClientHelper API to
  verify JSON Web Tokens (JWTs).
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:  Application developers using IBM WebSphere  *
  *                  Application Server and OIDC                 *
  ****************************************************************
  * PROBLEM DESCRIPTION: Add methods to the OidcClientHelper API *
  *                      to verify JWTs.                         *
  ****************************************************************
  * RECOMMENDATION:  Install a fix pack or interim fix that      *
  *                  contains this APAR.                         *
  ****************************************************************
  Add methods to the
  com.ibm.websphere.security.oidc.util.OidcClientHelper API to
  verify JWTs.
  Methods should be available to verify JWTs using OIDC TAI
  configuration information or discovery.
  

Problem conclusion

• The OIDC com.ibm.websphere.security.oidc.util.OidcClientHelper
  API is updated to add methods to verify JWTs.
  
  * The verifyJwt methods always use discovery if the OIDC TAI is
  not configured or if the TAI did not initialize successfully.
  * The verifyJwtUsingDiscovery methods always use discovery and
  do not require that the OIDC TAI be configured or initialized.
  * The verifyJwtUsingTAIConfig methods always use the OIDC TAI
  config, therefore they require configuration and successful
  initialization of the TAI.
  
  
  A new OIDC TAI property is introduced:
  
  Name: provider_(id).useIssuer
  Values: true/false, default=true
  Description:
  Set this property to false if do not want the runtime to use
  this provider entry to service JWT verification requests by API
  for JWTs that have an iss claim that that matches this
  provider's issuer. If there is more than one provider entry with
  the same issuer name, only one of the provider entries can have
  this property set to true, otherwise this property is set to
  false for all matching issuers.
  
  When the provider_(id).allowJwtIssuerSelection property is set
  to true, it will override the value of this property and set it
  to true.
  
  
  The following methods are added:
  
  public static boolean verifyJwt(String jwtString) throws
  Exception;
  public static boolean verifyJwt(String jwtString, String
  defaultIssuer) throws Exception;
  public static boolean verifyJwtUsingDiscovery(String jwtString)
  throws Exception;
  public static boolean verifyJwtUsingDiscovery(String jwtString,
  String discoveryUrl) throws Exception;
  public static boolean verifyJwtUsingTAIConfig(String jwtString)
  throws Exception;
  public static boolean verifyJwtUsingTAIConfig(String jwtString,
  String defaultIssuer) throws Exception;
  
  /**
   * Verify a JWT
   *
   * * To find the information required to verify the JWT, this
   * method will first attempt to find an OIDC TAI config entry
   * that matches the iss claim in the JWT.
   * * If one is not found, the method will attempt to obtain the
   * information to verify the JWT using discovery.
   * * The discovery endpoint is calculated from the iss claim
   * in the JWT:
   * (issuer)/.well-known/openid-configuration</code>
   * * The discovery result is cached to optimize method
   * performance.
   * * An iss claim must be present in the JWT.
   *
   * @param jwtString JWT string to verify
   *
   * @return true if the JWT is valid
   *
   * @throws Exception if the JWT is not valid or an error occurs
   *                   while accessing the discovery endpoint on
   *                   the OP.
   */
  public static boolean verifyJwt(String jwtString) throws
  Exception;
  
  /**
   * Verify a JWT
   *
   * * To find the information required to verify the JWT, this
   * method will first attempt to find an OIDC TAI config entry
   * that matches the issuer.
   * * If one is not found, the method will attempt to obtain the
   * information to verify the JWT using discovery.
   * * The discovery endpoint is calculated from the issuer:
   * (issuer)/.well-known/openid-configuration
   * * The discovery result is cached to optimize method
   * performance.
   *
   * @param jwtString JWT string to verify
   * @param defaultIssuer Default issuer to use if there is no iss
   *                      claim in the JWT
   *
   * @return true if the JWT is valid
   *
   * @throws Exception if the JWT is not valid or an error occurs
   *                   while accessing the discovery endpoint on
   *                   the OP.
   */
  public static boolean verifyJwt(String jwtString, String
  defaultIssuer) throws Exception;
  
  /**
   * Verify a JWT using discovery
   *
   * * This method will obtain the information to verify the JWT
   * using discovery.
   * * The discovery endpoint is calculated from the iss claim
   * in the JWT:
   * (issuer)/.well-known/openid-configuration
   * * The discovery result is cached to optimize method
   * performance.
   * * An iss claim must be present in the JWT.
   *
   * @param jwtString JWT string to verify
   *
   * @return true if the JWT is valid
   *
   * @throws Exception if the JWT is not valid or an error occurs
   *                   while accessing the discovery endpoint on
   *                   the OP.
   */
  public static boolean verifyJwtUsingDiscovery(String jwtString)
  throws Exception;
  
  /**
   * Verify a JWT using discovery
   *
   * * This method will obtain the information to verify the JWT
   * using the specified discovery endpoint.
   * * The discovery result is cached to optimize method
   * performance.
   *
   * @param jwtString JWT string to verify
   * @param discoveryUrl Discovery endpoint URL
   *
   * @return true if the JWT is valid
   *
   * @throws Exception if the JWT is not valid or an error occurs
   *                   while accessing the discovery endpoint on
   *                   the OP.
   */
  public static boolean verifyJwtUsingDiscovery(String jwtString,
  String discoveryUrl) throws Exception;
  
  /**
   * Verify a JWT using the OpenID Connect (OIDC) TAI
   * configuration
   *
   * * To find the information required to verify the JWT, this
   * method will attempt to find an OIDC TAI config entry that
   * matches the iss claim in the JWT.
   * * An iss claim must be present in the JWT.
   *
   * @param jwtString JWT string to verify
   *
   * @return true if the JWT is valid
   *
   * @throws Exception if the JWT is not valid or an error occurs
   *                   while attempting to find an OIDC TAI config
   *                   entry that matches the issuer.
   */
  public static boolean verifyJwtUsingTAIConfig(String jwtString)
  throws Exception;
  
  /**
   * Verify a JWT using the OpenID Connect (OIDC) TAI
   * configuration
   *
   * To find the information required to verify the JWT,
   * this method will attempt to find an OIDC TAI config entry
   * that matches the issuer.
   *
   * @param jwtString JWT string to verify
   * @param defaultIssuer Default issuer to use if there is no iss
   *                      claim in the JWT
   *
   * @return true if the JWT is valid
   *
   * @throws Exception if the JWT is not valid or an error occurs
   *                   while attempting to find an OIDC TAI config
   *                   entry that matches the issuer.
   */
  public static boolean verifyJwtUsingTAIConfig(String jwtString,
  String defaultIssuer) throws Exception;
  
  The fix for this APAR is targeted for inclusion in fix packs
  8.5.5.22 and 9.0.5.12. For more information, see 'Recommended
  Updates for WebSphere Application Server':
  https://www.ibm.com/support/pages/node/715553
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

• Fixed component name

  WEBSPHERE APP S

• Fixed component ID

  5724J0800

Applicable component levels