From ea41747b2ea456cd15595c9ce8dcce6ef5b578ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robin=20Hru=C5=A1ka?= Date: Thu, 11 Apr 2024 18:40:46 +0200 Subject: [PATCH 1/6] add missing parameter attributes, remove those that are not widely supported --- seacatauth/authn/handler.py | 4 +- seacatauth/client/handler.py | 2 +- seacatauth/client/service.py | 3 +- seacatauth/cookie/handler.py | 17 ++++---- seacatauth/credentials/handler.py | 3 +- .../credentials/registration/handler.py | 3 +- seacatauth/credentials/schemas.py | 22 +++++----- seacatauth/tenant/schemas.py | 40 +++++++++++-------- 8 files changed, 52 insertions(+), 42 deletions(-) diff --git a/seacatauth/authn/handler.py b/seacatauth/authn/handler.py index e1d57cae7..357eabdae 100644 --- a/seacatauth/authn/handler.py +++ b/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"} @@ -467,7 +467,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: diff --git a/seacatauth/client/handler.py b/seacatauth/client/handler.py index 6706a2387..a605f28ce 100644 --- a/seacatauth/client/handler.py +++ b/seacatauth/client/handler.py @@ -52,7 +52,7 @@ async def list(self, request): description: Items per page schema: type: integer - - name: p + - name: f in: query description: Filter schema: diff --git a/seacatauth/client/service.py b/seacatauth/client/service.py index df7f1268c..784f1f0cf 100644 --- a/seacatauth/client/service.py +++ b/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."}, diff --git a/seacatauth/cookie/handler.py b/seacatauth/cookie/handler.py index 08ef774e6..13d46a421 100644 --- a/seacatauth/cookie/handler.py +++ b/seacatauth/cookie/handler.py @@ -122,6 +122,8 @@ async def nginx(self, request): 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 +138,10 @@ async def nginx(self, request): headers: Authorization: description: Bearer + 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. @@ -287,10 +284,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 +302,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) diff --git a/seacatauth/credentials/handler.py b/seacatauth/credentials/handler.py index 5c88219e9..0b2c76f4f 100644 --- a/seacatauth/credentials/handler.py +++ b/seacatauth/credentials/handler.py @@ -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"} } } }) diff --git a/seacatauth/credentials/registration/handler.py b/seacatauth/credentials/registration/handler.py index 6cf63729b..4c9e7e19e 100644 --- a/seacatauth/credentials/registration/handler.py +++ b/seacatauth/credentials/registration/handler.py @@ -103,7 +103,8 @@ async def public_create_invitation(self, request, *, tenant, credentials_id, jso "expiration": { "oneOf": [{"type": "string"}, {"type": "number"}], "description": "How long until the invitation expires.", - "examples": ["6 h", "3d", "1w", 7200]}, + "example": "6 h", + }, }, }) @access_control("seacat:tenant:assign") diff --git a/seacatauth/credentials/schemas.py b/seacatauth/credentials/schemas.py index a346f985f..3ae265608 100644 --- a/seacatauth/credentials/schemas.py +++ b/seacatauth/credentials/schemas.py @@ -12,30 +12,28 @@ "email": { "description": "Email address", "anyOf": [ - {"type": "null"}, - {"type": "string", "const": ""}, + {"type": "string", "enum": [""]}, {"type": "string", "format": "email"}, ], }, "phone": { "description": "Mobile number", "anyOf": [ - {"type": "null"}, - {"type": "string", "const": ""}, + {"type": "string", "enum": [""]}, {"type": "string", "pattern": r"^\+?[0-9 ]+$"}, ], }, "data": { "type": "object", "description": "Custom data", - "patternProperties": { - "^[a-zA-Z][a-zA-Z0-9_-]{0,126}[a-zA-Z0-9]$": {"anyOf": [ - {"type": "string"}, - {"type": "number"}, - {"type": "boolean"}, - {"type": "null"}, - ]} - }, + # "patternProperties": { + # "^[a-zA-Z][a-zA-Z0-9_-]{0,126}[a-zA-Z0-9]$": {"anyOf": [ + # {"type": "string"}, + # {"type": "number"}, + # {"type": "boolean"}, + # {"type": "null"}, + # ]} + # }, "additionalProperties": False, }, "suspended": { diff --git a/seacatauth/tenant/schemas.py b/seacatauth/tenant/schemas.py index 22164adcb..a64c9a4c8 100644 --- a/seacatauth/tenant/schemas.py +++ b/seacatauth/tenant/schemas.py @@ -11,12 +11,14 @@ "description": "Custom tenant data. Shallow JSON object that maps string keys " "to non-structured values.", - "patternProperties": { - "^[a-zA-Z][a-zA-Z0-9_-]{0,126}[a-zA-Z0-9]$": {"anyOf": [ - {"type": "string"}, - {"type": "number"}, - {"type": "boolean"}, - {"type": "null"}]}}}} + # "patternProperties": { + # "^[a-zA-Z][a-zA-Z0-9_-]{0,126}[a-zA-Z0-9]$": {"anyOf": [ + # {"type": "string"}, + # {"type": "number"}, + # {"type": "boolean"}, + # {"type": "null"}]}} + } +} CREATE_TENANT = { "type": "object", @@ -79,11 +81,13 @@ "To grant tenant access without assigning any roles, " "leave the role array empty. \n\n" "To assign global roles, list them under the `'*'` key.", - "patternProperties": { - r"^\*$|^[a-z][a-z0-9._-]{2,31}$": { - "type": "array", - "description": "List of the tenant's roles to be assigned", - "items": {"type": "string"}}}}}, + # "patternProperties": { + # r"^\*$|^[a-z][a-z0-9._-]{2,31}$": { + # "type": "array", + # "description": "List of the tenant's roles to be assigned", + # "items": {"type": "string"}}} + } + }, "example": { "credential_ids": [ "mongodb:default:abc123def456", "htpasswd:local:zdenek"], @@ -110,12 +114,14 @@ "To completely revoke credentials' access to the tenant, provide `\"UNASSIGN-TENANT\"` as the " "tenant value, instead of the array of roles. \n\n" "To unassign global roles, list them under the `\"*\"` key.", - "patternProperties": { - r"^\*$|^[a-z][a-z0-9._-]{2,31}$": { - "anyOf": [ - {"type": "array", "items": {"type": "string"}}, - {"type": "string", "enum": ["UNASSIGN-TENANT"]} - ]}}}}, + # "patternProperties": { + # r"^\*$|^[a-z][a-z0-9._-]{2,31}$": { + # "anyOf": [ + # {"type": "array", "items": {"type": "string"}}, + # {"type": "string", "enum": ["UNASSIGN-TENANT"]} + # ]}} + } + }, "example": { "credential_ids": [ "mongodb:default:abc123def456", "htpasswd:local:zdenek"], From ec8dce967e62a4f4a8d33308f2684047c9dd9446 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robin=20Hru=C5=A1ka?= Date: Thu, 11 Apr 2024 19:02:51 +0200 Subject: [PATCH 2/6] remove endpoint resource ids --- seacatauth/tenant/handler.py | 34 ---------------------------------- 1 file changed, 34 deletions(-) diff --git a/seacatauth/tenant/handler.py b/seacatauth/tenant/handler.py index 1c12fd75c..01713ff1f 100644 --- a/seacatauth/tenant/handler.py +++ b/seacatauth/tenant/handler.py @@ -138,11 +138,6 @@ async def get(self, request): async def create(self, request, *, credentials_id, json_data): """ Create a tenant - - --- - security: - - oAuth: - - authz:superuser """ role_service = self.App.get_service("seacatauth.RoleService") tenant_id = json_data["id"] @@ -190,10 +185,6 @@ async def create(self, request, *, credentials_id, json_data): async def update_tenant(self, request, *, json_data, tenant): """ Update tenant description and/or its structured data - --- - security: - - oAuth: - - seacat:tenant:edit """ result = await self.TenantService.update_tenant(tenant, **json_data) return asab.web.rest.json_response(request, data=result) @@ -203,11 +194,6 @@ async def update_tenant(self, request, *, json_data, tenant): async def delete(self, request, *, tenant): """ Delete a tenant. Also delete all its roles and assignments linked to this tenant. - - --- - security: - - oAuth: - - authz:superuser """ await self.TenantService.delete_tenant(tenant) return asab.web.rest.json_response(request, {"result": "OK"}) @@ -242,11 +228,6 @@ async def set_tenants(self, request, *, json_data): async def assign_tenant(self, request, *, tenant): """ Grant specified tenant access to requested credentials - - --- - security: - - oAuth: - - authz:tenant:assign """ await self.TenantService.assign_tenant( request.match_info["credentials_id"], @@ -261,11 +242,6 @@ async def unassign_tenant(self, request, *, tenant): Revoke specified tenant access to requested credentials The tenant's roles are unassigned in the process. - - --- - security: - - oAuth: - - authz:tenant:assign """ await self.TenantService.unassign_tenant( request.match_info["credentials_id"], @@ -314,11 +290,6 @@ async def propose_tenant_name(self, request): async def bulk_assign_tenants(self, request, *, json_data): """ Grant tenant access and/or assign roles to a list of credentials - - --- - security: - - oAuth: - - authz:superuser """ credential_service = self.TenantService.App.get_service("seacatauth.CredentialsService") role_service = self.TenantService.App.get_service("seacatauth.RoleService") @@ -395,11 +366,6 @@ async def bulk_assign_tenants(self, request, *, json_data): async def bulk_unassign_tenants(self, request, *, json_data): """ Revoke tenant access and/or unassign roles from a list of credentials - - --- - security: - - oAuth: - - authz:superuser """ role_service = self.TenantService.App.get_service("seacatauth.RoleService") From 0b46fc815493914d90561ad480b8d2c148cc7d0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robin=20Hru=C5=A1ka?= Date: Fri, 12 Apr 2024 14:50:57 +0200 Subject: [PATCH 3/6] more readable route tags --- seacatauth/authn/handler.py | 32 ++++++++++++------- seacatauth/authn/m2m.py | 3 ++ seacatauth/authn/webauthn/handler.py | 2 +- seacatauth/authz/rbac/handler.py | 2 +- seacatauth/authz/resource/handler.py | 2 +- seacatauth/authz/role/handler/role.py | 2 +- seacatauth/authz/role/handler/roles.py | 6 ++-- seacatauth/batman/handler.py | 6 ++-- seacatauth/client/handler.py | 3 +- seacatauth/cookie/handler.py | 5 +++ .../credentials/change_password/handler.py | 2 +- seacatauth/credentials/handler.py | 2 +- .../credentials/registration/handler.py | 2 +- seacatauth/external_login/handler.py | 2 +- seacatauth/feature/handler.py | 2 +- .../openidconnect/handler/introspect.py | 3 ++ seacatauth/otp/handler.py | 2 +- seacatauth/tenant/handler.py | 2 +- 18 files changed, 51 insertions(+), 29 deletions(-) diff --git a/seacatauth/authn/handler.py b/seacatauth/authn/handler.py index 357eabdae..414f6b9e3 100644 --- a/seacatauth/authn/handler.py +++ b/seacatauth/authn/handler.py @@ -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: diff --git a/seacatauth/authn/m2m.py b/seacatauth/authn/m2m.py index 316df0608..9511fb941 100644 --- a/seacatauth/authn/m2m.py +++ b/seacatauth/authn/m2m.py @@ -144,6 +144,9 @@ async def nginx(self, request): proxy_pass http://seacat-auth-svc:8081/m2m/nginx; } ``` + + --- + tags: ["Nginx"] """ # TODO: API key auth # TODO: Certificate auth diff --git a/seacatauth/authn/webauthn/handler.py b/seacatauth/authn/webauthn/handler.py index fcd031856..7252ea08b 100644 --- a/seacatauth/authn/webauthn/handler.py +++ b/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): diff --git a/seacatauth/authz/rbac/handler.py b/seacatauth/authz/rbac/handler.py index c55543ea8..c91ed5b7c 100644 --- a/seacatauth/authz/rbac/handler.py +++ b/seacatauth/authz/rbac/handler.py @@ -17,7 +17,7 @@ class RBACHandler(object): Resource-based access control --- - tags: ["Resource access"] + tags: ["Authorization"] """ def __init__(self, app, rbac_svc): diff --git a/seacatauth/authz/resource/handler.py b/seacatauth/authz/resource/handler.py index e7f83a0d9..80e8532e3 100644 --- a/seacatauth/authz/resource/handler.py +++ b/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): diff --git a/seacatauth/authz/role/handler/role.py b/seacatauth/authz/role/handler/role.py index c53577da2..512e180ca 100644 --- a/seacatauth/authz/role/handler/role.py +++ b/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 diff --git a/seacatauth/authz/role/handler/roles.py b/seacatauth/authz/role/handler/roles.py index dcf98b32b..ef83e84ef 100644 --- a/seacatauth/authz/role/handler/roles.py +++ b/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 "*": diff --git a/seacatauth/batman/handler.py b/seacatauth/batman/handler.py index 59906364d..510291c9e 100644 --- a/seacatauth/batman/handler.py +++ b/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): @@ -42,6 +39,9 @@ async def batman_nginx(self, request): Validate Batman 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") diff --git a/seacatauth/client/handler.py b/seacatauth/client/handler.py index a605f28ce..0a5db9a29 100644 --- a/seacatauth/client/handler.py +++ b/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 diff --git a/seacatauth/cookie/handler.py b/seacatauth/cookie/handler.py index 13d46a421..3dfdce6a7 100644 --- a/seacatauth/cookie/handler.py +++ b/seacatauth/cookie/handler.py @@ -79,6 +79,9 @@ class CookieHandler(object): } } ``` + + --- + tags: ["HTTP Cookies"] """ def __init__(self, app, cookie_svc, session_svc, credentials_svc): @@ -115,6 +118,7 @@ async def nginx(self, request): **Internal endpoint for Nginx auth_request.** --- + tags: ["Nginx"] parameters: - name: X-Request-Uri in: header @@ -185,6 +189,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 diff --git a/seacatauth/credentials/change_password/handler.py b/seacatauth/credentials/change_password/handler.py index cfeeadead..3b17d53c4 100644 --- a/seacatauth/credentials/change_password/handler.py +++ b/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): diff --git a/seacatauth/credentials/handler.py b/seacatauth/credentials/handler.py index 0b2c76f4f..39175dda8 100644 --- a/seacatauth/credentials/handler.py +++ b/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): diff --git a/seacatauth/credentials/registration/handler.py b/seacatauth/credentials/registration/handler.py index 4c9e7e19e..54d754bb9 100644 --- a/seacatauth/credentials/registration/handler.py +++ b/seacatauth/credentials/registration/handler.py @@ -22,7 +22,7 @@ class RegistrationHandler(object): Credential registration --- - tags: ["Register or invite credentials"] + tags: ["User registration"] """ def __init__(self, app, registration_svc, credentials_svc): diff --git a/seacatauth/external_login/handler.py b/seacatauth/external_login/handler.py index b1b5c2bca..53e1a85f8 100644 --- a/seacatauth/external_login/handler.py +++ b/seacatauth/external_login/handler.py @@ -21,7 +21,7 @@ class ExternalLoginHandler(object): External login --- - tags: ["External login"] + tags: ["Login with external provider"] """ def __init__(self, app, external_login_svc: ExternalLoginService): diff --git a/seacatauth/feature/handler.py b/seacatauth/feature/handler.py index 71384ff7d..bfd3a9cb7 100644 --- a/seacatauth/feature/handler.py +++ b/seacatauth/feature/handler.py @@ -15,7 +15,7 @@ class FeatureHandler(object): Login and registration features --- - tags: ["Login and registration features"] + tags: ["Login and authentication"] """ def __init__(self, app, feture_svc): diff --git a/seacatauth/openidconnect/handler/introspect.py b/seacatauth/openidconnect/handler/introspect.py index f80804345..4e34e3860 100644 --- a/seacatauth/openidconnect/handler/introspect.py +++ b/seacatauth/openidconnect/handler/introspect.py @@ -138,6 +138,9 @@ async def introspect_nginx(self, request): } } + + --- + tags: ["Nginx"] """ session = await self._authenticate_request(request) diff --git a/seacatauth/otp/handler.py b/seacatauth/otp/handler.py index c6b4206ed..ddbbeb142 100644 --- a/seacatauth/otp/handler.py +++ b/seacatauth/otp/handler.py @@ -18,7 +18,7 @@ class OTPHandler(object): Manage TOTP --- - tags: ["Manage TOTP"] + tags: ["One-Time PIN (TOTP)"] """ def __init__(self, app, otp_svc): diff --git a/seacatauth/tenant/handler.py b/seacatauth/tenant/handler.py index 01713ff1f..b26c0a582 100644 --- a/seacatauth/tenant/handler.py +++ b/seacatauth/tenant/handler.py @@ -18,7 +18,7 @@ class TenantHandler(object): Tenant management --- - tags: ["Tenant management"] + tags: ["Tenants"] """ def __init__(self, app, tenant_svc): From 9a3ca4009e62ad9bd791e7d1a080be4ea0570c9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robin=20Hru=C5=A1ka?= Date: Fri, 12 Apr 2024 16:20:22 +0200 Subject: [PATCH 4/6] docstrings --- seacatauth/authz/rbac/handler.py | 6 +++--- seacatauth/openidconnect/handler/token.py | 4 +++- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/seacatauth/authz/rbac/handler.py b/seacatauth/authz/rbac/handler.py index c91ed5b7c..08d141ecf 100644 --- a/seacatauth/authz/rbac/handler.py +++ b/seacatauth/authz/rbac/handler.py @@ -17,7 +17,7 @@ class RBACHandler(object): Resource-based access control --- - tags: ["Authorization"] + 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 `+`. """ diff --git a/seacatauth/openidconnect/handler/token.py b/seacatauth/openidconnect/handler/token.py index 3aeacf22d..56d47300a 100644 --- a/seacatauth/openidconnect/handler/token.py +++ b/seacatauth/openidconnect/handler/token.py @@ -271,7 +271,9 @@ async def token_error_response(self, request, error_description): async def validate_id_token(self, request): """ - Read the JWT token either from the request body or from the Authorization header. + Check the validity of a JWToken + + Read the JWToken either from the request body or from the Authorization header. Validate the token: send back the contents if successful; otherwise respond with error. """ body = await request.read() From 6779ed9fa40e6b7575298280ca2fc56391c3106b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robin=20Hru=C5=A1ka?= Date: Fri, 12 Apr 2024 16:29:18 +0200 Subject: [PATCH 5/6] docstrings --- seacatauth/authn/m2m.py | 4 +++- seacatauth/batman/handler.py | 6 ++++-- seacatauth/cookie/handler.py | 11 ++++++++--- seacatauth/openidconnect/handler/introspect.py | 2 +- seacatauth/openidconnect/handler/token.py | 4 ++-- 5 files changed, 18 insertions(+), 9 deletions(-) diff --git a/seacatauth/authn/m2m.py b/seacatauth/authn/m2m.py index 9511fb941..ccfc4a4ce 100644 --- a/seacatauth/authn/m2m.py +++ b/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. diff --git a/seacatauth/batman/handler.py b/seacatauth/batman/handler.py index 510291c9e..fa6d34d31 100644 --- a/seacatauth/batman/handler.py +++ b/seacatauth/batman/handler.py @@ -36,9 +36,11 @@ 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.** + **Internal endpoint for Nginx auth_request** + + Validate Seacat Auth cookie and respond with Basic Authorization header. --- tags: ["Nginx"] diff --git a/seacatauth/cookie/handler.py b/seacatauth/cookie/handler.py index 3dfdce6a7..057d04798 100644 --- a/seacatauth/cookie/handler.py +++ b/seacatauth/cookie/handler.py @@ -110,13 +110,15 @@ 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: @@ -179,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. diff --git a/seacatauth/openidconnect/handler/introspect.py b/seacatauth/openidconnect/handler/introspect.py index 4e34e3860..309fbfa2d 100644 --- a/seacatauth/openidconnect/handler/introspect.py +++ b/seacatauth/openidconnect/handler/introspect.py @@ -94,7 +94,7 @@ async def _authenticate_request(self, request): async def introspect_nginx(self, request): """ - Access token introspection for Nginx + Access token introspection Non-standard version of RFC7662 chapter 2.Introspection Endpoint that is usable with Nginx auth_request module. diff --git a/seacatauth/openidconnect/handler/token.py b/seacatauth/openidconnect/handler/token.py index 56d47300a..649e0ef74 100644 --- a/seacatauth/openidconnect/handler/token.py +++ b/seacatauth/openidconnect/handler/token.py @@ -239,9 +239,9 @@ async def _token_request_authorization_code(self, request, qs_data): }) async def token_revoke(self, request, *, json_data): """ - https://tools.ietf.org/html/rfc7009 + OAuth 2.0 Token revocation - 2.1. Revocation Request + https://tools.ietf.org/html/rfc7009 """ # TODO: Confidential clients must authenticate (query params or Authorization header) # TODO: Public clients are not allowed to revoke other clients' tokens From 6201686d6c3261cc215e48981911f21ef1c89269 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robin=20Hru=C5=A1ka?= Date: Fri, 12 Apr 2024 16:33:00 +0200 Subject: [PATCH 6/6] docstrings --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2aa3f40a9..499c45f99 100644 --- a/CHANGELOG.md +++ b/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`)