From 25c02ffd065a451fed9f1987e5a12633db72b1b8 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 29 Aug 2024 14:39:22 -0700 Subject: [PATCH] feat(security): more endpoint + flow type examples --- 3.0/json/security.json | 103 ++++++++++++++++++++++++++++++++++++++-- 3.0/yaml/security.yaml | 96 +++++++++++++++++++++++++++++++++++-- 3.1/json/security.json | 105 +++++++++++++++++++++++++++++++++++++++-- 3.1/yaml/security.yaml | 101 ++++++++++++++++++++++++++++++++++++--- 4 files changed, 388 insertions(+), 17 deletions(-) diff --git a/3.0/json/security.json b/3.0/json/security.json index 0e84d73..a641f1b 100644 --- a/3.0/json/security.json +++ b/3.0/json/security.json @@ -126,7 +126,7 @@ }, "/anything/oauth2": { "post": { - "summary": "General support", + "summary": "General support (all flow types)", "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23", "tags": ["OAuth 2"], "responses": { @@ -139,6 +139,66 @@ "oauth2": ["write:things"] } ] + }, + "get": { + "summary": "General support (authorizationCode flow type)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23", + "tags": ["OAuth 2"], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "oauth2_authorizationCode": ["write:things"] + } + ] + }, + "put": { + "summary": "General support (clientCredentials flow type)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23", + "tags": ["OAuth 2"], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "oauth2_clientCredentials": ["write:things"] + } + ] + }, + "patch": { + "summary": "General support (implicit flow type)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23", + "tags": ["OAuth 2"], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "oauth2_implicit": ["write:things"] + } + ] + }, + "delete": { + "summary": "General support (password flow type)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23", + "tags": ["OAuth 2"], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "oauth2_password": ["write:things"] + } + ] } }, "/anything/openIdConnect": { @@ -273,9 +333,34 @@ } } }, - "oauth2_alternate": { + "oauth2_authorizationCode": { "type": "oauth2", - "description": "An alternate OAuth 2 security flow. Functions identially to the other `oauth2` scheme, just with alternate URLs to authenticate against. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23", + "description": "An OAuth 2 security flow that only supports the `authorizationCode` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object", + "flows": { + "authorizationCode": { + "authorizationUrl": "http://alt.example.com/oauth/dialog", + "tokenUrl": "http://alt.example.com/oauth/token", + "scopes": { + "write:things": "Add things to your account" + } + } + } + }, + "oauth2_clientCredentials": { + "type": "oauth2", + "description": "An OAuth 2 security flow that only supports the `clientCredentials` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object", + "flows": { + "clientCredentials": { + "tokenUrl": "http://alt.example.com/oauth/token", + "scopes": { + "write:things": "Add things to your account" + } + } + } + }, + "oauth2_implicit": { + "type": "oauth2", + "description": "An OAuth 2 security flow that only supports the `implicit` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object", "flows": { "implicit": { "authorizationUrl": "http://alt.example.com/oauth/dialog", @@ -285,6 +370,18 @@ } } }, + "oauth2_password": { + "type": "oauth2", + "description": "An OAuth 2 security flow that only supports the `password` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object", + "flows": { + "password": { + "tokenUrl": "http://alt.example.com/oauth/token", + "scopes": { + "write:things": "Add things to your account" + } + } + } + }, "openIdConnect": { "type": "openIdConnect", "openIdConnectUrl": "https://example.com/.well-known/openid-configuration", diff --git a/3.0/yaml/security.yaml b/3.0/yaml/security.yaml index eccacb6..ec4fab3 100644 --- a/3.0/yaml/security.yaml +++ b/3.0/yaml/security.yaml @@ -89,7 +89,7 @@ paths: - bearer_jwt: [] '/anything/oauth2': post: - summary: General support + summary: General support (all flow types) description: |- > ℹ️ > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. @@ -103,6 +103,66 @@ paths: security: - oauth2: - write:things + get: + summary: General support (authorizationCode flow type) + description: |- + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23 + tags: + - OAuth 2 + responses: + '200': + description: OK + security: + - oauth2_authorizationCode: + - write:things + put: + summary: General support (clientCredentials flow type) + description: |- + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23 + tags: + - OAuth 2 + responses: + '200': + description: OK + security: + - oauth2_clientCredentials: + - write:things + patch: + summary: General support (implicit flow type) + description: |- + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23 + tags: + - OAuth 2 + responses: + '200': + description: OK + security: + - oauth2_implicit: + - write:things + delete: + summary: General support (password flow type) + description: |- + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23 + tags: + - OAuth 2 + responses: + '200': + description: OK + security: + - oauth2_password: + - write:things '/anything/openIdConnect': post: summary: General support @@ -205,15 +265,43 @@ components: tokenUrl: http://example.com/oauth/token scopes: write:things: Add things to your account - oauth2_alternate: + oauth2_authorizationCode: type: oauth2 - description: An alternate OAuth 2 security flow. Functions identially to the - other `oauth2` scheme, just with alternate URLs to authenticate against. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23 + description: An OAuth 2 security flow that only supports the `authorizationCode` + flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object + flows: + authorizationCode: + authorizationUrl: http://alt.example.com/oauth/dialog + tokenUrl: http://alt.example.com/oauth/token + scopes: + write:things: Add things to your account + oauth2_clientCredentials: + type: oauth2 + description: An OAuth 2 security flow that only supports the `clientCredentials` + flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object + flows: + clientCredentials: + tokenUrl: http://alt.example.com/oauth/token + scopes: + write:things: Add things to your account + oauth2_implicit: + type: oauth2 + description: An OAuth 2 security flow that only supports the `implicit` flow + type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object flows: implicit: authorizationUrl: http://alt.example.com/oauth/dialog scopes: write:things: Add things to your account + oauth2_password: + type: oauth2 + description: An OAuth 2 security flow that only supports the `password` flow + type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oauth-flows-object + flows: + password: + tokenUrl: http://alt.example.com/oauth/token + scopes: + write:things: Add things to your account openIdConnect: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration diff --git a/3.1/json/security.json b/3.1/json/security.json index 2e802b1..e5fc59c 100644 --- a/3.1/json/security.json +++ b/3.1/json/security.json @@ -145,8 +145,8 @@ }, "/anything/oauth2": { "post": { - "summary": "General support", - "description": ">ℹ️We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23", + "summary": "General support (all flow types)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23", "tags": ["OAuth 2"], "responses": { "200": { @@ -158,6 +158,66 @@ "oauth2": ["write:things"] } ] + }, + "get": { + "summary": "General support (authorizationCode flow type)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23", + "tags": ["OAuth 2"], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "oauth2_authorizationCode": ["write:things"] + } + ] + }, + "put": { + "summary": "General support (clientCredentials flow type)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23", + "tags": ["OAuth 2"], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "oauth2_clientCredentials": ["write:things"] + } + ] + }, + "patch": { + "summary": "General support (implicit flow type)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23", + "tags": ["OAuth 2"], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "oauth2_implicit": ["write:things"] + } + ] + }, + "delete": { + "summary": "General support (password flow type)", + "description": "> ℹ️\n> We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that.\n\nhttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23", + "tags": ["OAuth 2"], + "responses": { + "200": { + "description": "OK" + } + }, + "security": [ + { + "oauth2_password": ["write:things"] + } + ] } }, "/anything/openIdConnect": { @@ -278,9 +338,34 @@ } } }, - "oauth2_alternate": { + "oauth2_authorizationCode": { + "type": "oauth2", + "description": "An OAuth 2 security flow that only supports the `authorizationCode` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object", + "flows": { + "authorizationCode": { + "authorizationUrl": "http://alt.example.com/oauth/dialog", + "tokenUrl": "http://alt.example.com/oauth/token", + "scopes": { + "write:things": "Add things to your account" + } + } + } + }, + "oauth2_clientCredentials": { "type": "oauth2", - "description": "An alternate OAuth 2 security flow. Functions identially to the other `oauth2` scheme, just with alternate URLs to authenticate against. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23", + "description": "An OAuth 2 security flow that only supports the `clientCredentials` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object", + "flows": { + "clientCredentials": { + "tokenUrl": "http://alt.example.com/oauth/token", + "scopes": { + "write:things": "Add things to your account" + } + } + } + }, + "oauth2_implicit": { + "type": "oauth2", + "description": "An OAuth 2 security flow that only supports the `implicit` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object", "flows": { "implicit": { "authorizationUrl": "http://alt.example.com/oauth/dialog", @@ -290,6 +375,18 @@ } } }, + "oauth2_password": { + "type": "oauth2", + "description": "An OAuth 2 security flow that only supports the `password` flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object", + "flows": { + "password": { + "tokenUrl": "http://alt.example.com/oauth/token", + "scopes": { + "write:things": "Add things to your account" + } + } + } + }, "openIdConnect": { "type": "openIdConnect", "openIdConnectUrl": "https://example.com/.well-known/openid-configuration", diff --git a/3.1/yaml/security.yaml b/3.1/yaml/security.yaml index c14f3f7..dfb4bb9 100644 --- a/3.1/yaml/security.yaml +++ b/3.1/yaml/security.yaml @@ -98,11 +98,12 @@ paths: - mutualTLS: [] '/anything/oauth2': post: - summary: General support + summary: General support (all flow types) description: |- - >ℹ️We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-23 + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23 tags: - OAuth 2 responses: @@ -111,6 +112,66 @@ paths: security: - oauth2: - write:things + get: + summary: General support (authorizationCode flow type) + description: |- + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23 + tags: + - OAuth 2 + responses: + '200': + description: OK + security: + - oauth2_authorizationCode: + - write:things + put: + summary: General support (clientCredentials flow type) + description: |- + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23 + tags: + - OAuth 2 + responses: + '200': + description: OK + security: + - oauth2_clientCredentials: + - write:things + patch: + summary: General support (implicit flow type) + description: |- + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23 + tags: + - OAuth 2 + responses: + '200': + description: OK + security: + - oauth2_implicit: + - write:things + delete: + summary: General support (password flow type) + description: |- + > ℹ️ + > We currently do not handle OAuth 2 authentication flows so if an operation has an `oauth2` requirement we assume that the user, or the projects JWT, has a qualified `bearer` token and will use that. + + https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23 + tags: + - OAuth 2 + responses: + '200': + description: OK + security: + - oauth2_password: + - write:things '/anything/openIdConnect': post: summary: General support @@ -202,15 +263,43 @@ components: tokenUrl: http://example.com/oauth/token scopes: write:things: Add things to your account - oauth2_alternate: + oauth2_authorizationCode: type: oauth2 - description: An alternate OAuth 2 security flow. Functions identially to the - other `oauth2` scheme, just with alternate URLs to authenticate against. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-23 + description: An OAuth 2 security flow that only supports the `authorizationCode` + flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object + flows: + authorizationCode: + authorizationUrl: http://alt.example.com/oauth/dialog + tokenUrl: http://alt.example.com/oauth/token + scopes: + write:things: Add things to your account + oauth2_clientCredentials: + type: oauth2 + description: An OAuth 2 security flow that only supports the `clientCredentials` + flow type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object + flows: + clientCredentials: + tokenUrl: http://alt.example.com/oauth/token + scopes: + write:things: Add things to your account + oauth2_implicit: + type: oauth2 + description: An OAuth 2 security flow that only supports the `implicit` flow + type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object flows: implicit: authorizationUrl: http://alt.example.com/oauth/dialog scopes: write:things: Add things to your account + oauth2_password: + type: oauth2 + description: An OAuth 2 security flow that only supports the `password` flow + type. https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oauth-flows-object + flows: + password: + tokenUrl: http://alt.example.com/oauth/token + scopes: + write:things: Add things to your account openIdConnect: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration