From 69d063c35df8276c482cc11a4e3387d1e0c502bc Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 21 Aug 2026 11:36:48 -0700 Subject: [PATCH 1/3] Copy over security Objects from the OAS This commit is an exact copy of the Security Scheme Object, OAuth Flows Object, and OAuth FLow Object sections of the OAS as they appear on the v3.3 branch in the OpenAPI-Specification repository (commit 22026f5a876674d0fbe5f5d1f9d9a1380587a4be). --- src/security.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/src/security.md b/src/security.md index f0191f2..d2f465a 100644 --- a/src/security.md +++ b/src/security.md @@ -10,6 +10,126 @@ TODO: Define the Security Specification. +## Specification + +### Security Scheme Object + +Defines a security scheme that can be used by the operations. + +Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), OAuth2 device authorization flow as defined in [RFC8628](https://tools.ietf.org/html/rfc8628), and [[OpenID-Connect-Core]]. +Please note that as of 2020, the implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use cases is Authorization Code Grant flow with PKCE. + +#### Fixed Fields + +| Field Name | Type | Applies To | Description | +| ---- | :----: | ---- | ---- | +| type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"mutualTLS"`, `"oauth2"`, `"openIdConnect"`. | +| description | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | +| name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. | +| in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"`, or `"cookie"`. | +| scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authentication scheme to be used in the [Authorization header as defined in RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-16.4.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). The value is case-insensitive, as defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-11.1). | +| bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. | +| flows | [OAuth Flows Object](#oauth-flows-object) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. | +| openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. [Well-known URL](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) to discover the [[OpenID-Connect-Discovery]] [provider metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). | +| oauth2MetadataUrl | `string` | `oauth2` | URL to the OAuth2 authorization server metadata [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required. | +| deprecated | `boolean` | Any | Declares this security scheme to be deprecated. Consumers SHOULD refrain from usage of the declared scheme. Default value is `false`. | + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +#### Security Scheme Object Examples + +##### Basic Authentication Example + +```yaml +type: http +scheme: basic +``` + +##### API Key Example + +```yaml +type: apiKey +name: api-key +in: header +``` + +##### JWT Bearer Example + +```yaml +type: http +scheme: bearer +bearerFormat: JWT +``` + +##### MutualTLS Example + +```yaml +type: mutualTLS +description: Cert must be signed by example.com CA +``` + +##### Implicit OAuth2 Example + +```yaml +type: oauth2 +flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + scopes: + write:pets: modify pets in your account + read:pets: read your pets +``` + +### OAuth Flows Object + +Allows configuration of the supported OAuth Flows. + +#### Fixed Fields + +| Field Name | Type | Description | +| ---- | :----: | ---- | +| implicit | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow | +| password | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Password flow | +| clientCredentials | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. | +| authorizationCode | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. | +| deviceAuthorization | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Device Authorization flow. | + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +### OAuth Flow Object + +Configuration details for a supported OAuth Flow + +#### Fixed Fields + +| Field Name | Type | Applies To | Description | +| ---- | :----: | ---- | ---- | +| authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. | +| deviceAuthorizationUrl | `string` | `oauth2` (`"deviceAuthorization"`) | **REQUIRED**. The device authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. | +| tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`, `"deviceAuthorization"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. | +| refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. | +| scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. | + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +#### OAuth Flow Object Example + +```yaml +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 +``` + ## Appendix A - Revision History TODO: Document notable changes between versions. From 67558bd7ad71c5f276f58429976ea98c686947a0 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 21 Aug 2026 11:37:08 -0700 Subject: [PATCH 2/3] Fix links to OAS sections. --- src/security.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/security.md b/src/security.md index d2f465a..99937e3 100644 --- a/src/security.md +++ b/src/security.md @@ -34,7 +34,7 @@ Please note that as of 2020, the implicit flow is about to be deprecated by [OAu | oauth2MetadataUrl | `string` | `oauth2` | URL to the OAuth2 authorization server metadata [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). TLS is required. | | deprecated | `boolean` | Any | Declares this security scheme to be deprecated. Consumers SHOULD refrain from usage of the declared scheme. Default value is `false`. | -This object MAY be extended with [Specification Extensions](#specification-extensions). +This object MAY be extended with [Specification Extensions](https://spec.openapis.org/oas/latest.html#specification-extensions). #### Security Scheme Object Examples @@ -94,7 +94,7 @@ Allows configuration of the supported OAuth Flows. | authorizationCode | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. | | deviceAuthorization | [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Device Authorization flow. | -This object MAY be extended with [Specification Extensions](#specification-extensions). +This object MAY be extended with [Specification Extensions](https://spec.openapis.org/oas/latest.html#specification-extensions). ### OAuth Flow Object @@ -110,7 +110,7 @@ Configuration details for a supported OAuth Flow | refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. | | scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. | -This object MAY be extended with [Specification Extensions](#specification-extensions). +This object MAY be extended with [Specification Extensions](https://spec.openapis.org/oas/latest.html#specification-extensions). #### OAuth Flow Object Example From 790d5885dea2fcc61805ecbc982a19e78e650632 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 24 Sep 2026 10:55:02 -0700 Subject: [PATCH 3/3] Add initial schemas. --- src/schemas/validation/README.md | 20 +++ src/schemas/validation/schema.yaml | 230 +++++++++++++++++++++++++++++ 2 files changed, 250 insertions(+) create mode 100644 src/schemas/validation/README.md create mode 100644 src/schemas/validation/schema.yaml diff --git a/src/schemas/validation/README.md b/src/schemas/validation/README.md new file mode 100644 index 0000000..6bb2cf7 --- /dev/null +++ b/src/schemas/validation/README.md @@ -0,0 +1,20 @@ +# OpenAPI Security Specification JSON Schema + +This directory contains the YAML sources for generating the JSON Schemas for validating OpenAPI Security Specification (OSS) Standardized API Features (SAFs), which are published on [https://spec.openapis.org](https://spec.openapis.org). + +***NOTE:*** The exact structure and versioning policy of SAF schemas is still being discussed. The current schemas are ported over from the OpenAPI Specification but the approach is subject to change. + +Due to limitations of GitHub pages, the schemas on the spec site are served with `Content-Type: application/octet-stream`, but should be interpreted as `application/schema+json`. + +The sources in this directory, which have `WORK-IN-PROGRESS` in their `$id`s, are _not intended for direct use_. + +## Schema `$id` dates + +The published schemas on the spec site have an _iteration date_ in their `id`s. +This allows the schemas for a release line to be updated independent of the spec patch release cycle. + +The iteration version of the JSON Schema can be found in the `$id` field. +For example, the value of `$id: https://spec.openapis.org/oas/3.1/schema/2021-03-02` means this iteration was created on March 2nd, 2021. + +We are [working on](https://github.com/OAI/OpenAPI-Specification/issues/4152) how to best provide programmatic access for determining the latest date for each schema. + diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml new file mode 100644 index 0000000..ac50562 --- /dev/null +++ b/src/schemas/validation/schema.yaml @@ -0,0 +1,230 @@ +$id: 'https://spec.openapis.org/security/legacy/3.3/schema/WORK-IN-PROGRESS' +$schema: 'https://json-schema.org/draft/2020-12/schema' + +description: The description of OpenAPI legacy security Objects + +$defs: + security-scheme: + $comment: https://spec.openapis.org/oas/v3.3#security-scheme-object + type: object + properties: + type: + enum: + - apiKey + - http + - mutualTLS + - oauth2 + - openIdConnect + description: + type: string + deprecated: + default: false + type: boolean + required: + - type + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/security-scheme/$defs/type-apikey' + - $ref: '#/$defs/security-scheme/$defs/type-http' + - $ref: '#/$defs/security-scheme/$defs/type-http-bearer' + - $ref: '#/$defs/security-scheme/$defs/type-oauth2' + - $ref: '#/$defs/security-scheme/$defs/type-oidc' + unevaluatedProperties: false + + $defs: + type-apikey: + if: + properties: + type: + const: apiKey + then: + properties: + name: + type: string + in: + enum: + - query + - header + - cookie + required: + - name + - in + + type-http: + if: + properties: + type: + const: http + then: + properties: + scheme: + type: string + required: + - scheme + + type-http-bearer: + if: + properties: + type: + const: http + scheme: + type: string + pattern: ^[Bb][Ee][Aa][Rr][Ee][Rr]$ + required: + - type + - scheme + then: + properties: + bearerFormat: + type: string + + type-oauth2: + if: + properties: + type: + const: oauth2 + then: + properties: + flows: + $ref: '#/$defs/oauth-flows' + oauth2MetadataUrl: + type: string + format: uri-reference + required: + - flows + + type-oidc: + if: + properties: + type: + const: openIdConnect + then: + properties: + openIdConnectUrl: + type: string + format: uri-reference + required: + - openIdConnectUrl + + oauth-flows: + type: object + properties: + implicit: + $ref: '#/$defs/oauth-flows/$defs/implicit' + password: + $ref: '#/$defs/oauth-flows/$defs/password' + clientCredentials: + $ref: '#/$defs/oauth-flows/$defs/client-credentials' + authorizationCode: + $ref: '#/$defs/oauth-flows/$defs/authorization-code' + deviceAuthorization: + $ref: '#/$defs/oauth-flows/$defs/device-authorization' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + $defs: + implicit: + type: object + properties: + authorizationUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + $ref: '#/$defs/map-of-strings' + required: + - authorizationUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + password: + type: object + properties: + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + $ref: '#/$defs/map-of-strings' + required: + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + client-credentials: + type: object + properties: + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + $ref: '#/$defs/map-of-strings' + required: + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + authorization-code: + type: object + properties: + authorizationUrl: + type: string + format: uri-reference + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + $ref: '#/$defs/map-of-strings' + required: + - authorizationUrl + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + device-authorization: + type: object + properties: + deviceAuthorizationUrl: + type: string + format: uri-reference + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + $ref: '#/$defs/map-of-strings' + required: + - deviceAuthorizationUrl + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + specification-extensions: + $comment: https://spec.openapis.org/oas/v3.3#specification-extensions + patternProperties: + '^x-': true + + additionalProperties: + $ref: '#/$defs/example-or-reference' + + map-of-strings: + type: object + additionalProperties: + type: string