From d5a6b4298889aca3f7085df531de1ee502413d49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Fi=C5=A1er?= Date: Fri, 31 Jul 2026 15:15:35 +0200 Subject: [PATCH 1/5] fix: allow OAuth flows to omit URLs the spec does not require The OAuth Flow Object marks only scopes as REQUIRED. authorizationUrl applies to implicit and authorizationCode, tokenUrl to password, clientCredentials and authorizationCode, and refreshUrl to none of them. Treating all four as mandatory made an implicit flow fail with a TypeError on the official example from the specification. --- src/Schema/OAuthFlow.php | 56 ++++++++++++++++++---------- tests/Cases/Schema/OAuthFlowTest.php | 47 +++++++++++++++++++++++ 2 files changed, 83 insertions(+), 20 deletions(-) diff --git a/src/Schema/OAuthFlow.php b/src/Schema/OAuthFlow.php index 4f7c0cf..ef3321c 100644 --- a/src/Schema/OAuthFlow.php +++ b/src/Schema/OAuthFlow.php @@ -5,19 +5,24 @@ class OAuthFlow { - private string $authorizationUrl; + private ?string $authorizationUrl; - private string $tokenUrl; + private ?string $tokenUrl; - private string $refreshUrl; + private ?string $refreshUrl; /** @var array */ - private array $scopes = []; + private array $scopes; /** * @param array $scopes */ - public function __construct(string $authorizationUrl, string $tokenUrl, string $refreshUrl, array $scopes) + public function __construct( + ?string $authorizationUrl = null, + ?string $tokenUrl = null, + ?string $refreshUrl = null, + array $scopes = [], + ) { $this->authorizationUrl = $authorizationUrl; $this->tokenUrl = $tokenUrl; @@ -31,9 +36,9 @@ public function __construct(string $authorizationUrl, string $tokenUrl, string $ public static function fromArray(array $data): self { return new self( - $data['authorizationUrl'], - $data['tokenUrl'], - $data['refreshUrl'], + $data['authorizationUrl'] ?? null, + $data['tokenUrl'] ?? null, + $data['refreshUrl'] ?? null, $data['scopes'], ); } @@ -43,40 +48,51 @@ public static function fromArray(array $data): self */ public function toArray(): array { - return [ - 'authorizationUrl' => $this->authorizationUrl, - 'tokenUrl' => $this->tokenUrl, - 'refreshUrl' => $this->refreshUrl, - 'scopes' => $this->scopes, - ]; + $data = []; + + if ($this->authorizationUrl !== null) { + $data['authorizationUrl'] = $this->authorizationUrl; + } + + if ($this->tokenUrl !== null) { + $data['tokenUrl'] = $this->tokenUrl; + } + + if ($this->refreshUrl !== null) { + $data['refreshUrl'] = $this->refreshUrl; + } + + $data['scopes'] = $this->scopes; + + return $data; } - public function getAuthorizationUrl(): string + public function getAuthorizationUrl(): ?string { return $this->authorizationUrl; } - public function setAuthorizationUrl(string $authorizationUrl): void + public function setAuthorizationUrl(?string $authorizationUrl): void { $this->authorizationUrl = $authorizationUrl; } - public function getTokenUrl(): string + public function getTokenUrl(): ?string { return $this->tokenUrl; } - public function setTokenUrl(string $tokenUrl): void + public function setTokenUrl(?string $tokenUrl): void { $this->tokenUrl = $tokenUrl; } - public function getRefreshUrl(): string + public function getRefreshUrl(): ?string { return $this->refreshUrl; } - public function setRefreshUrl(string $refreshUrl): void + public function setRefreshUrl(?string $refreshUrl): void { $this->refreshUrl = $refreshUrl; } diff --git a/tests/Cases/Schema/OAuthFlowTest.php b/tests/Cases/Schema/OAuthFlowTest.php index c220e6f..de83157 100644 --- a/tests/Cases/Schema/OAuthFlowTest.php +++ b/tests/Cases/Schema/OAuthFlowTest.php @@ -36,6 +36,53 @@ public function testRequired(): void Assert::same($expectedData, OAuthFlow::fromArray($realData)->toArray()); } + public function testImplicitFlowWithoutTokenUrl(): void + { + $data = [ + 'authorizationUrl' => 'https://example.com/authorization', + 'scopes' => ['read' => 'Read access'], + ]; + + $flow = OAuthFlow::fromArray($data); + + Assert::same('https://example.com/authorization', $flow->getAuthorizationUrl()); + Assert::null($flow->getTokenUrl()); + Assert::null($flow->getRefreshUrl()); + Assert::same($data, $flow->toArray()); + } + + public function testClientCredentialsFlowWithoutAuthorizationUrl(): void + { + $data = [ + 'tokenUrl' => 'https://example.com/token', + 'scopes' => [], + ]; + + $flow = OAuthFlow::fromArray($data); + + Assert::null($flow->getAuthorizationUrl()); + Assert::same('https://example.com/token', $flow->getTokenUrl()); + Assert::same($data, $flow->toArray()); + } + + /** + * The OpenAPI Specification marks `scopes` as REQUIRED on the OAuth Flow Object (the map MAY + * be empty, but the key MUST be present). fromArray() must not silently manufacture it - a + * missing key has to surface as an error instead of producing an OAuthFlow with scopes = []. + */ + public function testMissingScopesIsNotSilentlyAccepted(): void + { + $data = [ + 'tokenUrl' => 'https://example.com/token', + ]; + + Assert::exception(static function () use ($data): void { + Assert::error(static function () use ($data): void { + OAuthFlow::fromArray($data); + }, E_WARNING, 'Undefined array key "scopes"'); + }, \TypeError::class); + } + } (new OAuthFlowTest())->run(); From 8bafe65f3cb250496caac4bcaaaeefc2764cbd28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Fi=C5=A1er?= Date: Fri, 31 Jul 2026 15:23:24 +0200 Subject: [PATCH 2/5] fix: do not require bearerFormat for http bearer schemes The specification calls bearerFormat 'a hint to the client [...] primarily for documentation purposes'. It is not REQUIRED, so a bearer scheme without it is valid and must be accepted. --- src/Schema/SecurityScheme.php | 4 ---- tests/Cases/Schema/SecuritySchemeTest.php | 17 +++++++++++------ 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/src/Schema/SecurityScheme.php b/src/Schema/SecurityScheme.php index 9d82d35..08bb3fd 100644 --- a/src/Schema/SecurityScheme.php +++ b/src/Schema/SecurityScheme.php @@ -204,10 +204,6 @@ public function getBearerFormat(): ?string public function setBearerFormat(?string $bearerFormat): void { - if ($this->type === self::TYPE_HTTP && $this->scheme === 'bearer' && $bearerFormat === null) { - throw new InvalidArgumentException('Attribute "bearerFormat" is required for type "http" and scheme "bearer".'); - } - $this->bearerFormat = $bearerFormat; } diff --git a/tests/Cases/Schema/SecuritySchemeTest.php b/tests/Cases/Schema/SecuritySchemeTest.php index 1ce5f93..b418f6e 100644 --- a/tests/Cases/Schema/SecuritySchemeTest.php +++ b/tests/Cases/Schema/SecuritySchemeTest.php @@ -158,13 +158,18 @@ public function testMissingScheme(): void }, InvalidArgumentException::class, 'Attribute "scheme" is required for type "http".'); } - public function testMissingBearerFormat(): void + public function testBearerFormatIsOptional(): void { - Assert::exception(static function (): void { - $securityScheme = new SecurityScheme(SecurityScheme::TYPE_HTTP); - $securityScheme->setScheme('bearer'); - $securityScheme->setBearerFormat(null); - }, InvalidArgumentException::class, 'Attribute "bearerFormat" is required for type "http" and scheme "bearer".'); + $data = [ + 'type' => SecurityScheme::TYPE_HTTP, + 'scheme' => 'bearer', + ]; + + Assert::noError(static function () use ($data): void { + SecurityScheme::fromArray($data); + }); + + Assert::same($data, SecurityScheme::fromArray($data)->toArray()); } public function testMissingFlows(): void From a189808eec1ba7817bdabe0feb42965aeb949a0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Fi=C5=A1er?= Date: Fri, 31 Jul 2026 15:31:40 +0200 Subject: [PATCH 3/5] fix: accept oauth2 schemes that define a subset of flows The OAuth Flows Object marks no field as REQUIRED, so defining only the flows an API actually supports is valid. Requiring all four rejected almost every real-world document, including the specification's own example. Unknown flow keys are still rejected, and an oauth2 scheme with no flows at all remains invalid. --- src/Schema/SecurityScheme.php | 22 ++++++++++++------- tests/Cases/Schema/SecuritySchemeTest.php | 26 +++++++++++++++++------ 2 files changed, 34 insertions(+), 14 deletions(-) diff --git a/src/Schema/SecurityScheme.php b/src/Schema/SecurityScheme.php index 08bb3fd..5bff288 100644 --- a/src/Schema/SecurityScheme.php +++ b/src/Schema/SecurityScheme.php @@ -31,11 +31,16 @@ class SecurityScheme self::IN_QUERY, ]; + public const FLOW_IMPLICIT = 'implicit'; + public const FLOW_PASSWORD = 'password'; + public const FLOW_CLIENT_CREDENTIALS = 'clientCredentials'; + public const FLOW_AUTHORIZATION_CODE = 'authorizationCode'; + public const FLOWS = [ - 'implicit', - 'password', - 'clientCredentials', - 'authorizationCode', + self::FLOW_IMPLICIT, + self::FLOW_PASSWORD, + self::FLOW_CLIENT_CREDENTIALS, + self::FLOW_AUTHORIZATION_CODE, ]; private string $type; @@ -225,11 +230,12 @@ public function setFlows(array $flows): void } if ($this->type === self::TYPE_OAUTH2) { - foreach (self::FLOWS as $flow) { - if (!array_key_exists($flow, $flows)) { + foreach (array_keys($flows) as $flowType) { + if (!in_array($flowType, self::FLOWS, true)) { throw new InvalidArgumentException(sprintf( - 'Attribute "flows" is missing required key "%s".', - $flow + 'Invalid flow type "%s" given. It must be one of "%s".', + $flowType, + implode(', ', self::FLOWS) )); } } diff --git a/tests/Cases/Schema/SecuritySchemeTest.php b/tests/Cases/Schema/SecuritySchemeTest.php index b418f6e..f2d9b2d 100644 --- a/tests/Cases/Schema/SecuritySchemeTest.php +++ b/tests/Cases/Schema/SecuritySchemeTest.php @@ -180,19 +180,33 @@ public function testMissingFlows(): void }, InvalidArgumentException::class, 'Attribute "flows" is required for type "oauth2".'); } - public function testMissingFlow(): void + public function testSingleFlowIsAccepted(): void + { + $data = [ + 'type' => SecurityScheme::TYPE_OAUTH2, + 'flows' => [ + 'authorizationCode' => [ + 'authorizationUrl' => 'https://example.com/authorization', + 'tokenUrl' => 'https://example.com/token', + 'scopes' => ['read' => 'Read access'], + ], + ], + ]; + + Assert::same($data, SecurityScheme::fromArray($data)->toArray()); + } + + public function testUnknownFlowTypeIsRejected(): void { Assert::exception(static function (): void { $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); $securityScheme->setFlows([ - 'implicit' => OAuthFlow::fromArray([ + 'telepathy' => OAuthFlow::fromArray([ 'authorizationUrl' => 'https://example.com/authorization', - 'tokenUrl' => 'https://example.com/token', - 'refreshUrl' => 'https://example.com/refresh', - 'scopes' => ['read' => 'Read access', 'write' => 'Write access'], + 'scopes' => [], ]), ]); - }, InvalidArgumentException::class, 'Attribute "flows" is missing required key "password".'); + }, InvalidArgumentException::class, 'Invalid flow type "telepathy" given. It must be one of "implicit, password, clientCredentials, authorizationCode".'); } public function testMissingOpenIdConnectUrl(): void From d607715618396b736aa7cf76faf9066f36d8fa0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Fi=C5=A1er?= Date: Fri, 31 Jul 2026 15:42:54 +0200 Subject: [PATCH 4/5] fix: validate OAuth flow URLs against the flow type Each flow type has its own required fields: implicit needs authorizationUrl, password and clientCredentials need tokenUrl, and authorizationCode needs both. refreshUrl is never required. SecurityScheme performs this check because it knows the flow type of each entry, which OAuthFlow itself does not. --- src/Schema/SecurityScheme.php | 32 +++++++++++++++- tests/Cases/Schema/SecuritySchemeTest.php | 46 +++++++++++++++++++++++ 2 files changed, 77 insertions(+), 1 deletion(-) diff --git a/src/Schema/SecurityScheme.php b/src/Schema/SecurityScheme.php index 5bff288..b06a3b5 100644 --- a/src/Schema/SecurityScheme.php +++ b/src/Schema/SecurityScheme.php @@ -230,7 +230,7 @@ public function setFlows(array $flows): void } if ($this->type === self::TYPE_OAUTH2) { - foreach (array_keys($flows) as $flowType) { + foreach ($flows as $flowType => $flow) { if (!in_array($flowType, self::FLOWS, true)) { throw new InvalidArgumentException(sprintf( 'Invalid flow type "%s" given. It must be one of "%s".', @@ -238,6 +238,8 @@ public function setFlows(array $flows): void implode(', ', self::FLOWS) )); } + + self::validateFlow($flowType, $flow); } } @@ -258,4 +260,32 @@ public function setOpenIdConnectUrl(?string $openIdConnectUrl): void $this->openIdConnectUrl = $openIdConnectUrl; } + private static function validateFlow(string $flowType, OAuthFlow $flow): void + { + $needsAuthorizationUrl = in_array($flowType, [ + self::FLOW_IMPLICIT, + self::FLOW_AUTHORIZATION_CODE, + ], true); + + if ($needsAuthorizationUrl && $flow->getAuthorizationUrl() === null) { + throw new InvalidArgumentException(sprintf( + 'Attribute "authorizationUrl" is required for flow "%s".', + $flowType + )); + } + + $needsTokenUrl = in_array($flowType, [ + self::FLOW_PASSWORD, + self::FLOW_CLIENT_CREDENTIALS, + self::FLOW_AUTHORIZATION_CODE, + ], true); + + if ($needsTokenUrl && $flow->getTokenUrl() === null) { + throw new InvalidArgumentException(sprintf( + 'Attribute "tokenUrl" is required for flow "%s".', + $flowType + )); + } + } + } diff --git a/tests/Cases/Schema/SecuritySchemeTest.php b/tests/Cases/Schema/SecuritySchemeTest.php index f2d9b2d..f8b5919 100644 --- a/tests/Cases/Schema/SecuritySchemeTest.php +++ b/tests/Cases/Schema/SecuritySchemeTest.php @@ -217,6 +217,52 @@ public function testMissingOpenIdConnectUrl(): void }, InvalidArgumentException::class, 'Attribute "openIdConnectUrl" is required for type "openIdConnect".'); } + public function testImplicitFlowRequiresAuthorizationUrl(): void + { + Assert::exception(static function (): void { + $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); + $securityScheme->setFlows([ + SecurityScheme::FLOW_IMPLICIT => OAuthFlow::fromArray(['scopes' => []]), + ]); + }, InvalidArgumentException::class, 'Attribute "authorizationUrl" is required for flow "implicit".'); + } + + public function testClientCredentialsFlowRequiresTokenUrl(): void + { + Assert::exception(static function (): void { + $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); + $securityScheme->setFlows([ + SecurityScheme::FLOW_CLIENT_CREDENTIALS => OAuthFlow::fromArray(['scopes' => []]), + ]); + }, InvalidArgumentException::class, 'Attribute "tokenUrl" is required for flow "clientCredentials".'); + } + + public function testAuthorizationCodeFlowRequiresBothUrls(): void + { + Assert::exception(static function (): void { + $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); + $securityScheme->setFlows([ + SecurityScheme::FLOW_AUTHORIZATION_CODE => OAuthFlow::fromArray([ + 'authorizationUrl' => 'https://example.com/authorization', + 'scopes' => [], + ]), + ]); + }, InvalidArgumentException::class, 'Attribute "tokenUrl" is required for flow "authorizationCode".'); + } + + public function testRefreshUrlIsNeverRequired(): void + { + Assert::noError(static function (): void { + $securityScheme = new SecurityScheme(SecurityScheme::TYPE_OAUTH2); + $securityScheme->setFlows([ + SecurityScheme::FLOW_PASSWORD => OAuthFlow::fromArray([ + 'tokenUrl' => 'https://example.com/token', + 'scopes' => [], + ]), + ]); + }); + } + } (new SecuritySchemeTest())->run(); From d9ea66a8079e79c3a2ce43ae300b78f422adb424 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Fi=C5=A1er?= Date: Fri, 31 Jul 2026 16:54:53 +0200 Subject: [PATCH 5/5] test: add the specification's OAuth Flow example as a fixture This document is the OAuth Flow Object Example from OAS 3.1.1. Before the preceding fixes it could not be parsed at all. --- tests/Cases/Schema/ExamplesTest.php | 8 +++++++ .../Schema/examples/oauth-flows-example.yaml | 21 +++++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 tests/Cases/Schema/examples/oauth-flows-example.yaml diff --git a/tests/Cases/Schema/ExamplesTest.php b/tests/Cases/Schema/ExamplesTest.php index 245a453..9306974 100644 --- a/tests/Cases/Schema/ExamplesTest.php +++ b/tests/Cases/Schema/ExamplesTest.php @@ -95,6 +95,14 @@ public function testRedoclyMuseum(): void self::assertSameDataStructure($rawData, $openApiData); } + public function testOauthFlows(): void + { + $rawData = Yaml::parseFile(__DIR__ . '/examples/oauth-flows-example.yaml'); + $openApi = OpenApi::fromArray($rawData); + $openApiData = $openApi->toArray(); + self::assertSameDataStructure($rawData, $openApiData); + } + /** * @param mixed[] $expected * @param mixed[] $actual diff --git a/tests/Cases/Schema/examples/oauth-flows-example.yaml b/tests/Cases/Schema/examples/oauth-flows-example.yaml new file mode 100644 index 0000000..406bff2 --- /dev/null +++ b/tests/Cases/Schema/examples/oauth-flows-example.yaml @@ -0,0 +1,21 @@ +openapi: 3.1.0 +info: + title: OAuth Flows Example + version: 1.0.0 +paths: {} +components: + securitySchemes: + petstore_auth: + type: oauth2 + flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + scopes: + "write:pets": modify pets in your account + "read:pets": read your pets + authorizationCode: + authorizationUrl: https://example.com/api/oauth/dialog + tokenUrl: https://example.com/api/oauth/token + scopes: + "write:pets": modify pets in your account + "read:pets": read your pets