Merge pull request #360 from TeskaLabs/fix/openapi-specs

Update OpenAPI specs

CHANGELOG.md

@@ -30,6 +30,7 @@
 - Fix the initialization of NoTenantsError (#346, `v24.06-alpha2`)
 
 ### Features
+- Update OpenAPI specs (#360, `v24.06-alpha12`)
 - Client secret management (#359, `v24.06-alpha11`)
 - External login provider label contains just the display name (#352, `v24.06-alpha10`)
 - ElasticSearch index and Kibana space authorization (#353, `v24.06-alpha7.2`)

seacatauth/authn/handler.py

@@ -26,7 +26,7 @@
 JWK_PARAMS = {
 	"crv": {"type": "string"},
 	"ext": {"type": "boolean"},
-	"key_ops": {"type": "array"},
+	"key_ops": {"type": "array", "items": {"type": "string"}},
 	"kty": {"type": "string"},
 	"x": {"type": "string"},
 	"y": {"type": "string"}
@@ -94,7 +94,9 @@ def __init__(self, app, authn_svc):
 	})
 	async def login_prologue(self, request, *, json_data):
 		"""
-		Locate credentials by `ident` and establish an encrypted login session
+		Initiate a new login process
+
+		Locate credentials by `ident` and establish an encrypted login session.
 
 		Flow:
 		- Locate credentials by ident
@@ -161,7 +163,9 @@ async def login_prologue(self, request, *, json_data):
 
 	async def login(self, request):
 		"""
-		Perform an encrypted login request
+		Submit login
+
+		Perform an encrypted login request.
 
 		Flow:
 		- Locate login session by it ID
@@ -272,7 +276,9 @@ async def login(self, request):
 
 	async def logout(self, request):
 		"""
-		Log out of the current session and all its subsessions
+		Log out
+
+		Terminate current Single Sign-On session and all client subsessions.
 		"""
 		try:
 			session = await self.CookieService.get_session_by_request_cookie(request)
@@ -316,7 +322,9 @@ async def logout(self, request):
 
 	async def prepare_smslogin_challenge(self, request):
 		"""
-		Generate a one-time passcode and send it via SMS
+		Prepare authentication via SMS code
+
+		Generate a one-time passcode and send it via SMS.
 		"""
 		# Decode JSON request
 		lsid = request.match_info["lsid"]
@@ -350,7 +358,9 @@ async def prepare_smslogin_challenge(self, request):
 
 	async def prepare_webauthn_login_challenge(self, request):
 		"""
-		Initialize WebAuthn challenge and return WebAuthn authentication options object
+		Prepare authentication via FIDO2/WebAuthn
+
+		Initialize WebAuthn challenge and return WebAuthn authentication options object.
 		"""
 		# Decode JSON request
 		lsid = request.match_info["lsid"]
@@ -421,10 +431,10 @@ async def _get_client_login_key(self, client_id):
 	@access_control("authz:impersonate")
 	async def impersonate(self, request, *, json_data):
 		"""
-		Open a root session impersonated as a different user.
-		Response contains a Set-Cookie header with the new root session cookie.
+		Impersonate another user
 
-		Requires `authz:impersonate`.
+		Open an SSO session impersonated as a different user.
+		Response contains a Set-Cookie header with the new root session cookie.
 		"""
 		from_info = [request.remote]
 		ff = request.headers.get("X-Forwarded-For")
@@ -449,12 +459,12 @@ async def impersonate(self, request, *, json_data):
 	@access_control("authz:impersonate")
 	async def impersonate_and_redirect(self, request):
 		"""
-		Open a root session impersonated as a different user. Response contains a Set-Cookie header with the new
+		Impersonate another user
+
+		Open an SSO session impersonated as a different user. Response contains a Set-Cookie header with the new
 		root session cookie and redirection to the authorize endpoint. This effectively overwrites user's current
 		root cookie. Reference to current root session is kept in the impersonated session.
 		On logout, the original root cookie is set again.
-
-		Requires `authz:impersonate`.
 		---
 		requestBody:
 			content:
@@ -467,7 +477,7 @@ async def impersonate_and_redirect(self, request):
 								description: Credentials ID of the impersonation target.
 							client_id:
 								type: string
-								description:
+								description: Client ID
 							redirect_uri:
 								type: string
 								description:

seacatauth/authn/m2m.py

@@ -122,7 +122,9 @@ async def _authenticate_request(self, request, client_id):
 
 	async def nginx(self, request):
 		"""
-		Authenticate M2M call
+		M2M (machine-to-machine) introspection
+
+		**Internal endpoint for Nginx auth_request**
 
 		If introspection is successful, Basic auth header is replaced with Bearer token.
 
@@ -144,6 +146,9 @@ async def nginx(self, request):
 			proxy_pass            http://seacat-auth-svc:8081/m2m/nginx;
 		}
 		```
+
+		---
+		tags: ["Nginx"]
 		"""
 		# TODO: API key auth
 		# TODO: Certificate auth

seacatauth/authn/webauthn/handler.py

@@ -20,7 +20,7 @@ class WebAuthnHandler(object):
 	Manage FIDO2 Web Authentication
 
 	---
-	tags: ["Manage FIDO2 Web Authentication"]
+	tags: ["FIDO2/WebAuthn"]
 	"""
 
 	def __init__(self, app, webauthn_svc):

seacatauth/authz/rbac/handler.py

@@ -17,7 +17,7 @@ class RBACHandler(object):
 	Resource-based access control
 
 	---
-	tags: ["Resource access"]
+	tags: ["Resources"]
 	"""
 
 	def __init__(self, app, rbac_svc):
@@ -28,9 +28,9 @@ def __init__(self, app, rbac_svc):
 		web_app.router.add_get("/rbac/{tenant}/{resources}", self.rbac)
 
 	@access_control()
-	async def rbac(self, request, *, tenant):
+	async def rbac(self, request, *, tenant=None):
 		"""
-		Validate the current credentials' access to requested resources
+		Verify whether the current session is authorized to access requested resources
 
 		Multiple resources must be separated by `+`.
 		"""

seacatauth/authz/resource/handler.py

@@ -19,7 +19,7 @@ class ResourceHandler(object):
 	Resource management
 
 	---
-	tags: ["Resource management"]
+	tags: ["Resources"]
 	"""
 
 	def __init__(self, app, rbac_svc):

seacatauth/authz/role/handler/role.py

@@ -20,7 +20,7 @@ class RoleHandler(object):
 	Manage roles
 
 	---
-	tags: ["Manage roles"]
+	tags: ["Roles"]
 	"""
 	def __init__(self, app, role_svc):
 		self.App = app

seacatauth/authz/role/handler/roles.py

@@ -19,7 +19,7 @@ class RolesHandler(object):
 	Assign or unassign roles
 
 	---
-	tags: ["Assign or unassign roles"]
+	tags: ["Roles"]
 	"""
 
 	def __init__(self, app, role_svc):
@@ -71,7 +71,9 @@ async def get_roles_batch(self, request, *, tenant, json_data):
 	@access_control("seacat:role:assign")
 	async def set_roles(self, request, *, json_data, tenant, resources):
 		"""
-		For given credentials, assign listed roles and unassign existing roles that are not in the list
+		Set credentials' roles
+
+		For given credentials ID, assign listed roles and unassign existing roles that are not in the list
 
 		Cases:
 		1) The requester is superuser AND requested `tenant` is "*":

seacatauth/batman/handler.py

@@ -19,9 +19,6 @@ class BatmanHandler(object):
 	Batman (Basic auth)
 
 	Translates Seacat Auth cookies into Basic auth headers for applications that only support Basic auth (Kibana, Grafana).
-
-	---
-	tags: ["Batman (Basic auth)"]
 	"""
 
 	def __init__(self, app, batman_svc):
@@ -39,9 +36,14 @@ def __init__(self, app, batman_svc):
 
 	async def batman_nginx(self, request):
 		"""
-		Validate Batman cookie and respond with Basic Authorization header
+		Cookie introspection for basic auth apps
+
+		**Internal endpoint for Nginx auth_request**
+
+		Validate Seacat Auth cookie and respond with Basic Authorization header.
 
-		**Internal endpoint for Nginx auth_request.**
+		---
+		tags: ["Nginx"]
 		"""
 		cookie_service = self.App.get_service("seacatauth.CookieService")
 		oidc_service = self.App.get_service("seacatauth.OpenIdConnectService")

seacatauth/client/handler.py

@@ -19,8 +19,7 @@ class ClientHandler(object):
 	Client management
 
 	---
-	tags:
-	- Client management
+	tags: ["Clients (Applications)"]
 	"""
 	def __init__(self, app, client_svc):
 		self.ClientService = client_svc
@@ -52,7 +51,7 @@ async def list(self, request):
 			description: Items per page
 			schema:
 				type: integer
-		-	name: p
+		-	name: f
 			in: query
 			description: Filter
 			schema:

seacatauth/client/service.py

@@ -76,7 +76,8 @@
 			"Public URI of the client's cookie entrypoint."},
 	"redirect_uris": {
 		"type": "array",
-		"description": "Array of Redirection URI values used by the Client."},
+		"description": "Array of Redirection URI values used by the Client.",
+		"items": {"type": "string"}},
 	#  "contacts": {},
 	# "custom_data": {  # NON-CANONICAL
 	# 	"type": "object", "description": "(Non-canonical) Additional client data."},

seacatauth/cookie/handler.py

@@ -79,6 +79,9 @@ class CookieHandler(object):
 		}
 	}
 	```
+
+	---
+	tags: ["HTTP Cookies"]
 	"""
 
 	def __init__(self, app, cookie_svc, session_svc, credentials_svc):
@@ -107,21 +110,26 @@ def __init__(self, app, cookie_svc, session_svc, credentials_svc):
 
 	async def nginx(self, request):
 		"""
+		Cookie introspection
+
+		**Internal endpoint for Nginx auth_request**
+
 		Authenticate (and optionally authorize) the incoming request by its Cookie + Client ID and respond with
 		corresponding ID token. If the auth fails, respond with 401 or 403.
 
 		Optionally check for resource access and/or add requested user info to headers.
 
-		**Internal endpoint for Nginx auth_request.**
-
 		---
+		tags: ["Nginx"]
 		parameters:
 		-	name: X-Request-Uri
 			in: header
 			description:
 				Original request URI. In case of auth failure (401 or 403), it can be internally stored during the
 				authorization process and then used for redirection to the original location. If this header is
 				present, the response will include `X-State` header, which should be added to the OAuth Authorize query.
+			schema:
+				type: string
 		-	name: verify
 			in: query
 			description: Resources to authorize
@@ -136,15 +144,10 @@ async def nginx(self, request):
 				headers:
 					Authorization:
 						description: Bearer <JWT_ID_TOKEN>
+						schema:
+							type: string
 			401:
 				description: Authentication failed
-				headers:
-					X-State:
-						description:
-							Random string which should be passed in the OAuth Authorize request's `state` query
-							parameter to ensure correct redirection after successful authorization.
-							*This header is only present if the request contains an `X-Request-Uri` header
-							with a redirect URI that is valid for the Client.*
 			403:
 				description:
 					Authorization failed because of the End-User's or the Client's insufficient permissions.
@@ -178,7 +181,10 @@ async def nginx(self, request):
 
 	async def nginx_anonymous(self, request):
 		"""
-		**Internal endpoint for Nginx auth_request.**
+		Anonymous (guest) cookie introspection
+
+		**Internal endpoint for Nginx auth_request**
+
 		Authenticate (and optionally authorize) the incoming request by its Cookie + Client ID and respond with
 		corresponding ID token. If the auth fails with 401, initialize an "unauthenticated" anonymous session
 		and set a session cookie in the response.
@@ -188,6 +194,7 @@ async def nginx_anonymous(self, request):
 		Optionally check for resource access and/or add requested user info to headers.
 
 		---
+		tags: ["Nginx"]
 		parameters:
 		-	name: client_id
 			in: query
@@ -287,10 +294,14 @@ async def bouncer_get(self, request):
 			in: query
 			description: OAuth Client ID
 			required: true
+			schema:
+				type: string
 		-	name: redirect_uri
 			in: query
 			description: Original request URI
 			required: true
+			schema:
+				type: string
 		-	name: grant_type
 			in: query
 			description: OAuth Grant Type
@@ -301,6 +312,8 @@ async def bouncer_get(self, request):
 			in: query
 			description: OAuth Authorization code returned by the authorize endpoint
 			required: true
+			schema:
+				type: string
 		"""
 		params = request.query
 		return await self._bouncer(request, params)

seacatauth/credentials/change_password/handler.py

@@ -21,7 +21,7 @@ class ChangePasswordHandler(object):
 	Manage password
 
 	---
-	tags: ["Manage password"]
+	tags: ["Passwords"]
 	"""
 
 	def __init__(self, app, change_password_svc):

seacatauth/credentials/handler.py

@@ -25,7 +25,7 @@ class CredentialsHandler(object):
 	Credential management
 
 	---
-	tags: ["Credential management"]
+	tags: ["Users and credentials"]
 	"""
 
 	def __init__(self, app, credentials_svc):
@@ -465,7 +465,8 @@ async def update_my_credentials(self, request, *, json_data, credentials_id):
 		"properties": {
 			"factors": {
 				"type": "array",
-				"description": "Factors to enforce/reset"
+				"description": "Factors to enforce/reset",
+				"items": {"type": "string"}
 			}
 		}
 	})