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 diff --git a/src/security.md b/src/security.md index f0191f2..99937e3 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](https://spec.openapis.org/oas/latest.html#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](https://spec.openapis.org/oas/latest.html#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](https://spec.openapis.org/oas/latest.html#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.