Add authParams configuration support for OAuth2 clients

src/OAuth2.php

@@ -46,6 +46,18 @@ abstract class OAuth2 extends OAuth
      */
     protected bool $validateAuthState = true;
 
+    /**
+     * @var array additional auth parameters to be appended to authorization URL.
+     * These parameters will be merged with the default parameters in buildAuthUrl().
+     * For example, to force Google account chooser:
+     * ```php
+     * 'authParams' => [
+     *     'prompt' => 'select_account',
+     * ]
+     * ```
+     */
+    protected array $authParams = [];
+
     /**
      * BaseOAuth constructor.
      *
@@ -92,7 +104,7 @@ public function buildAuthUrl(
             $defaultParams['state'] = $authState;
         }
 
-        return RequestUtil::composeUrl($this->authUrl, array_merge($defaultParams, $params));
+        return RequestUtil::composeUrl($this->authUrl, array_merge($defaultParams, $this->authParams, $params));
     }
 
     /**
@@ -336,6 +348,26 @@ public function setOauth2ReturnUrl(string $returnUrl): void
         $this->returnUrl = $returnUrl;
     }
 
+    /**
+     * Sets additional auth parameters to be appended to authorization URL.
+     *
+     * @param array $authParams additional auth parameters.
+     */
+    public function setAuthParams(array $authParams): void
+    {
+        $this->authParams = $authParams;
+    }
+
+    /**
+     * Returns additional auth parameters.
+     *
+     * @return array additional auth parameters.
+     */
+    public function getAuthParams(): array
+    {
+        return $this->authParams;
+    }
+
     #[\Override]
     public function applyAccessTokenToRequest(RequestInterface $request, OAuthToken $accessToken): RequestInterface
     {

tests/OAuth2Test.php

@@ -63,4 +63,55 @@ public function testBuildAuthUrl(): void
         $this->assertStringContainsString($clientId, $builtAuthUrl, 'No client id present!');
         $this->assertStringContainsString(rawurlencode($returnUrl), $builtAuthUrl, 'No return URL present!');
     }
+
+    public function testBuildAuthUrlWithAuthParams(): void
+    {
+        $oauthClient = $this->createClient();
+        $authUrl = 'http://test.auth.url';
+        $oauthClient->setAuthUrl($authUrl);
+        $clientId = 'test_client_id';
+        $oauthClient->setClientId($clientId);
+        $returnUrl = 'http://test.return.url';
+        $oauthClient->setOauth2ReturnUrl($returnUrl);
+        $serverRequest = $this->getMockBuilder(ServerRequestInterface::class)->getMock();
+
+        // Set authParams
+        $oauthClient->setAuthParams([
+            'prompt' => 'select_account',
+            'access_type' => 'offline',
+        ]);
+
+        $builtAuthUrl = $oauthClient->buildAuthUrl($serverRequest, []);
+
+        $this->assertStringContainsString($authUrl, $builtAuthUrl, 'No auth URL present!');
+        $this->assertStringContainsString($clientId, $builtAuthUrl, 'No client id present!');
+        $this->assertStringContainsString(rawurlencode($returnUrl), $builtAuthUrl, 'No return URL present!');
+        $this->assertStringContainsString('prompt=select_account', $builtAuthUrl, 'No prompt parameter present!');
+        $this->assertStringContainsString('access_type=offline', $builtAuthUrl, 'No access_type parameter present!');
+    }
+
+    public function testAuthParamsCanBeOverriddenByRuntimeParams(): void
+    {
+        $oauthClient = $this->createClient();
+        $authUrl = 'http://test.auth.url';
+        $oauthClient->setAuthUrl($authUrl);
+        $clientId = 'test_client_id';
+        $oauthClient->setClientId($clientId);
+        $returnUrl = 'http://test.return.url';
+        $oauthClient->setOauth2ReturnUrl($returnUrl);
+        $serverRequest = $this->getMockBuilder(ServerRequestInterface::class)->getMock();
+
+        // Set authParams with a default value
+        $oauthClient->setAuthParams([
+            'prompt' => 'select_account',
+        ]);
+
+        // Override with runtime params
+        $builtAuthUrl = $oauthClient->buildAuthUrl($serverRequest, [
+            'prompt' => 'consent',
+        ]);
+
+        $this->assertStringContainsString('prompt=consent', $builtAuthUrl, 'Runtime params should override authParams!');
+        $this->assertStringNotContainsString('prompt=select_account', $builtAuthUrl, 'authParams should be overridden!');
+    }
 }