Add configurable issuer setting for JWT validation (#639)

Fixes issuer mismatch errors when the IDP's issuer differs from the
login endpoint base URL. The issuer can be configured via the Issuer
setting, OIDC_ISSUER constant, or auto-populated from discovery
documents. Defaults to deriving from endpoint_login for backward
compatibility.

Author: daggerhart

includes/openid-connect-generic-client-wrapper.php

@@ -914,11 +914,16 @@ private function get_claim( $claimname, $userinfo, &$claimvalue ) {
 
 		// Check if JWKS endpoint is configured for JWT signature verification.
 		if ( ! empty( $this->settings->endpoint_jwks ) ) {
+			// Use configured issuer if provided, otherwise derive from endpoint_login.
+			$issuer = ! empty( $this->settings->issuer ) ?
+				$this->settings->issuer :
+				( ! empty( $this->settings->endpoint_login ) ? $this->client->get_issuer_from_endpoint( $this->settings->endpoint_login ) : '' );
+
 			// Use JWT validator for secure signature verification.
 			$jwt_validator = new OpenID_Connect_Generic_JWT_Validator(
 				$this->settings->endpoint_jwks,
 				$this->settings->client_id,
-				$this->client->get_issuer_from_endpoint( $this->settings->endpoint_login ),
+				$issuer,
 				$this->settings->jwks_cache_ttl,
 				$this->settings->allow_internal_idp,
 				$this->logger

includes/openid-connect-generic-client.php

@@ -100,6 +100,15 @@ class OpenID_Connect_Generic_Client {
 	 */
 	private $endpoint_jwks;
 
+	/**
+	 * The issuer URL for JWT validation.
+	 *
+	 * @see OpenID_Connect_Generic_Option_Settings::issuer
+	 *
+	 * @var string
+	 */
+	private $issuer;
+
 	/**
 	 * The JWKS cache TTL in seconds.
 	 *
@@ -146,12 +155,13 @@ class OpenID_Connect_Generic_Client {
 	 * @param string                               $redirect_uri       @see OpenID_Connect_Generic_Option_Settings::redirect_uri for description.
 	 * @param string                               $acr_values         @see OpenID_Connect_Generic_Option_Settings::acr_values for description.
 	 * @param string                               $endpoint_jwks      @see OpenID_Connect_Generic_Option_Settings::endpoint_jwks for description.
+	 * @param string                               $issuer             @see OpenID_Connect_Generic_Option_Settings::issuer for description.
 	 * @param int                                  $jwks_cache_ttl     @see OpenID_Connect_Generic_Option_Settings::jwks_cache_ttl for description.
 	 * @param int                                  $state_time_limit   @see OpenID_Connect_Generic_Option_Settings::state_time_limit for description.
 	 * @param bool                                 $allow_internal_idp @see OpenID_Connect_Generic_Option_Settings::allow_internal_idp for description.
 	 * @param OpenID_Connect_Generic_Option_Logger $logger             The plugin logging object instance.
 	 */
-	public function __construct( $client_id, $client_secret, $scope, $endpoint_login, $endpoint_userinfo, $endpoint_token, $redirect_uri, $acr_values, $endpoint_jwks, $jwks_cache_ttl, $state_time_limit, $allow_internal_idp, $logger ) {
+	public function __construct( $client_id, $client_secret, $scope, $endpoint_login, $endpoint_userinfo, $endpoint_token, $redirect_uri, $acr_values, $endpoint_jwks, $issuer, $jwks_cache_ttl, $state_time_limit, $allow_internal_idp, $logger ) {
 		$this->client_id = $client_id;
 		$this->client_secret = $client_secret;
 		$this->scope = $scope;
@@ -161,6 +171,7 @@ public function __construct( $client_id, $client_secret, $scope, $endpoint_login
 		$this->redirect_uri = $redirect_uri;
 		$this->acr_values = $acr_values;
 		$this->endpoint_jwks = $endpoint_jwks;
+		$this->issuer = $issuer;
 		$this->jwks_cache_ttl = $jwks_cache_ttl;
 		$this->state_time_limit = $state_time_limit;
 		$this->allow_internal_idp = $allow_internal_idp;
@@ -543,11 +554,16 @@ public function get_id_token_claim( $token_response ) {
 
 		// Check if JWKS endpoint is configured for JWT signature verification.
 		if ( ! empty( $this->endpoint_jwks ) ) {
+			// Use configured issuer if provided, otherwise derive from endpoint_login.
+			$issuer = ! empty( $this->issuer )
+				? $this->issuer
+				: $this->get_issuer_from_endpoint( $this->endpoint_login );
+
 			// Use JWT validator for secure signature verification.
 			$jwt_validator = new OpenID_Connect_Generic_JWT_Validator(
 				$this->endpoint_jwks,
 				$this->client_id,
-				$this->get_issuer_from_endpoint( $this->endpoint_login ),
+				$issuer,
 				$this->jwks_cache_ttl,
 				$this->allow_internal_idp,
 				$this->logger
@@ -671,15 +687,16 @@ public function validate_id_token_claim( $id_token_claim ) {
 			return new WP_Error( 'invalid-aud', __( 'Token audience does not match client.', 'daggerhart-openid-connect-generic' ), $id_token_claim );
 		}
 
-		// Validate issuer claim if endpoint_login is configured.
-		if ( ! empty( $this->endpoint_login ) ) {
+		// Validate issuer claim if configured or endpoint_login is available.
+		$expected_issuer = ! empty( $this->issuer ) ?
+			$this->issuer :
+			( ! empty( $this->endpoint_login ) ? $this->get_issuer_from_endpoint( $this->endpoint_login ) : '' );
+
+		if ( ! empty( $expected_issuer ) ) {
 			if ( ! isset( $id_token_claim['iss'] ) ) {
 				return new WP_Error( 'missing-iss', __( 'Token missing issuer claim.', 'daggerhart-openid-connect-generic' ), $id_token_claim );
 			}
 
-			// Extract expected issuer from endpoint_login (base URL).
-			$expected_issuer = $this->get_issuer_from_endpoint( $this->endpoint_login );
-
 			if ( rtrim( $id_token_claim['iss'], '/' ) !== rtrim( $expected_issuer, '/' ) ) {
 				return new WP_Error(
 					'invalid-iss',

includes/openid-connect-generic-option-settings.php

@@ -35,6 +35,7 @@
  * @property string $endpoint_token       The IDP token validation endpoint URL.
  * @property string $endpoint_end_session The IDP logout endpoint URL.
  * @property string $endpoint_jwks        The IDP JWKS endpoint URL for JWT signature verification.
+ * @property string $issuer               The IDP issuer URL for JWT validation (optional - derived from endpoint_login if not set).
  * @property int    $jwks_cache_ttl       The JWKS cache TTL in seconds.
  * @property string $acr_values           The Authentication contract as defined on the IDP.
  *
@@ -98,6 +99,7 @@ class OpenID_Connect_Generic_Option_Settings {
 		'endpoint_token'            => 'OIDC_ENDPOINT_TOKEN_URL',
 		'endpoint_userinfo'         => 'OIDC_ENDPOINT_USERINFO_URL',
 		'endpoint_jwks'             => 'OIDC_ENDPOINT_JWKS_URL',
+		'issuer'                    => 'OIDC_ISSUER',
 		'login_type'                => 'OIDC_LOGIN_TYPE',
 		'scope'                     => 'OIDC_CLIENT_SCOPE',
 		'create_if_does_not_exist'  => 'OIDC_CREATE_IF_DOES_NOT_EXIST',

includes/openid-connect-generic-settings-page.php

@@ -308,6 +308,14 @@ private function get_settings_fields() {
 				'disabled'    => defined( 'OIDC_ENDPOINT_JWKS_URL' ),
 				'section'     => 'client_settings',
 			),
+			'issuer' => array(
+				'title'       => __( 'Issuer', 'daggerhart-openid-connect-generic' ),
+				'description' => __( 'Identity provider issuer URL for JWT validation. If not set, the issuer will be automatically derived from the Login Endpoint URL. Only configure this if your IDP uses a different issuer than the base URL of the login endpoint.', 'daggerhart-openid-connect-generic' ),
+				'example'     => 'https://example.com',
+				'type'        => 'text',
+				'disabled'    => defined( 'OIDC_ISSUER' ),
+				'section'     => 'client_settings',
+			),
 			'jwks_cache_ttl' => array(
 				'title'       => __( 'JWKS Cache TTL (seconds)', 'daggerhart-openid-connect-generic' ),
 				'description' => __( 'Time in seconds to cache JWKS keys. Default: 3600 (1 hour)', 'daggerhart-openid-connect-generic' ),
@@ -776,6 +784,7 @@ private function populate_settings_from_discovery( $discovery ) {
 			'token_endpoint'         => 'endpoint_token',
 			'userinfo_endpoint'      => 'endpoint_userinfo',
 			'jwks_uri'               => 'endpoint_jwks',
+			'issuer'                 => 'issuer',
 			'end_session_endpoint'   => 'endpoint_end_session',
 		);
 

openid-connect-generic.php

@@ -159,6 +159,7 @@ public function init() {
 			$this->get_redirect_uri( $this->settings ),
 			$this->settings->acr_values,
 			$this->settings->endpoint_jwks,
+			$this->settings->issuer ?? '',
 			$this->settings->jwks_cache_ttl,
 			$this->get_state_time_limit( $this->settings ),
 			$this->settings->allow_internal_idp,

tests/phpunit/includes/openid-connect-generic-client_test.php

@@ -265,6 +265,33 @@ public function test_validate_id_token_claim_with_audience_array() {
 		$this->assertTrue( $result );
 	}
 
+	/**
+	 * Test validate_id_token_claim uses configured issuer over derived issuer.
+	 *
+	 * @group ClientTests
+	 * @group IssuerValidation
+	 */
+	public function test_validate_id_token_claim_with_explicit_issuer() {
+		$client = $this->create_client(
+			array(
+				'endpoint_login' => 'https://login.example.com/authorize',
+				'issuer'         => 'https://issuer.example.com', // Explicit issuer differs from login endpoint.
+				'client_id'      => 'test_client',
+			)
+		);
+
+		$id_token_claim = array(
+			'sub' => 'user123',
+			'iss' => 'https://issuer.example.com',  // Matches configured issuer, not derived from endpoint_login.
+			'aud' => 'test_client',
+			'exp' => time() + 3600,
+			'iat' => time(),
+		);
+
+		$result = $client->validate_id_token_claim( $id_token_claim );
+		$this->assertTrue( $result );
+	}
+
 	/**
 	 * Helper to create client instance for testing.
 	 *
@@ -283,6 +310,7 @@ private function create_client( $settings = array() ) {
 			'redirect_uri'       => 'https://example.com/callback',
 			'acr_values'         => '',
 			'endpoint_jwks'      => '',
+			'issuer'             => '',
 			'jwks_cache_ttl'     => 3600,
 			'state_time_limit'   => 180,
 			'allow_internal_idp' => false,
@@ -302,6 +330,7 @@ private function create_client( $settings = array() ) {
 			$merged['redirect_uri'],
 			$merged['acr_values'],
 			$merged['endpoint_jwks'],
+			$merged['issuer'],
 			$merged['jwks_cache_ttl'],
 			$merged['state_time_limit'],
 			$merged['allow_internal_idp'],