From 5c29750373b27dec408540c5d3dd0b4aaf656997 Mon Sep 17 00:00:00 2001 From: YuriyZ Date: Mon, 28 Nov 2022 13:46:51 +0200 Subject: [PATCH] doc(jans-auth-server): added docs and updated swagger with new minimum acr related properties #343 --- .../configuration/client-config.md | 46 +++++++++++++++++++ jans-auth-server/docs/swagger.yaml | 38 ++++++++++++++- 2 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 docs/admin/auth-server/client-management/configuration/client-config.md diff --git a/docs/admin/auth-server/client-management/configuration/client-config.md b/docs/admin/auth-server/client-management/configuration/client-config.md new file mode 100644 index 00000000000..f03bd35dbc1 --- /dev/null +++ b/docs/admin/auth-server/client-management/configuration/client-config.md @@ -0,0 +1,46 @@ +--- +tags: + - administration + - client + - configuration +--- + +# Client Configuration + +## ACR client configuration + +There are 4 client configuration properties related to ACR: + +- `default_acr_values` - string array, default acr values which are set when `acr_values` is missed in authorization request. +- `minimumAcrLevel` - integer value which sets minimum acr level. +- `minimumAcrLevelAutoresolve` - boolean value, if `false` and `minimumAcrLevel` is higher then current `acr_values` then reject request. If `true` - resolve acr according to either client's `minimumAcrPriorityList` or AS `auth_level_mapping` +- `minimumAcrPriorityList` - string array, enables client to specify the acr order of preference, rather then just the next lowest integer value + +AS process properties in following order: +1. if `acr_values` is absent, set `acr_values` from `default_acr_values` +2. Otherwise if present, checking minimum acr level: +- check `minimumAcrLevel`, if current acr level is higher or equals to `minimumAcrLevel` then proceed request processing without changes +- if `minimumAcrLevel` is less then current acr level and `minimumAcrLevelAutoresolve=false` -> reject request (return bad request error) +- if `minimumAcrLevel` is less then current acr level and `minimumAcrLevelAutoresolve=true` -> pickup value from `minimumAcrPriorityList` or if it's empty take nearest acr value that satisfy `minimumAcrLevel` + +For example, given: +1. `minimumAcrLevel` = 14 +1. `default_acr_values` = "basic" +1. `minimumAcrPriorityList` = ["u2f", "passkey", "usb_fido_key", "super_gluu"] +1. OP `auth_level_mapping` : +``` +"auth_level_mapping": { + "1": ["basic"], + "5": ["otp"], + "10": ["u2f"], + "11": ["super_gluu"], + "20": ["passkey"], + "30": ["usb_fido_key"] + } +``` + +- if current `acr_values=u2f` and `minimumAcrLevelAutoresolve=false` -> request is rejected +- if current `acr_values=u2f` and `minimumAcrLevelAutoresolve=true` -> `acr_values` set to `acr_values=passkey` and request continue processing +- if current `acr_values=usb_fido_key` -> current acr is higher then minimum. Thus nothing to do. + +If `minimumAcrPriorityList` is missing, then the AS can pick the next highest acr in the `auth_level_mapping`. In the example above, that would be `passkey`. \ No newline at end of file diff --git a/jans-auth-server/docs/swagger.yaml b/jans-auth-server/docs/swagger.yaml index 1a9c115560d..cfd3246b4cb 100644 --- a/jans-auth-server/docs/swagger.yaml +++ b/jans-auth-server/docs/swagger.yaml @@ -1274,6 +1274,18 @@ paths: processing requests from the Client. items: type: string + minimum_acr_level: + type: integer + description: Integer value which sets minimum acr level. + example: 10 + minimum_acr_level_autoresolve: + type: boolean + description: boolean value, if false and minimum_acr_level is higher then current acr_values then reject request. If true - resolve acr according to either client's minimum_acr_priority_list or AS auth_level_mapping + minimum_acr_priority_list: + type: array + description: enables client to specify the acr order of preference, rather then just the next lowest integer value + items: + type: string groups: type: array description: Array of client's groups. @@ -1614,6 +1626,18 @@ paths: processing requests from the Client. items: type: string + minimum_acr_level: + type: integer + description: Integer value which sets minimum acr level. + example: 10 + minimum_acr_level_autoresolve: + type: boolean + description: boolean value, if false and minimum_acr_level is higher then current acr_values then reject request. If true - resolve acr according to either client's minimum_acr_priority_list or AS auth_level_mapping + minimum_acr_priority_list: + type: array + description: enables client to specify the acr order of preference, rather then just the next lowest integer value + items: + type: string initiate_login_uri: type: string description: Specifies the URI using the https scheme that the authorization server can call to initiate a login at the client. @@ -1956,6 +1980,18 @@ paths: processing requests from the Client. items: type: string + minimum_acr_level: + type: integer + description: Integer value which sets minimum acr level. + example: 10 + minimum_acr_level_autoresolve: + type: boolean + description: boolean value, if false and minimum_acr_level is higher then current acr_values then reject request. If true - resolve acr according to either client's minimum_acr_priority_list or AS auth_level_mapping + minimum_acr_priority_list: + type: array + description: enables client to specify the acr order of preference, rather then just the next lowest integer value + items: + type: string initiate_login_uri: type: string description: Specifies the URI using the https scheme that the authorization server can call to initiate a login at the client. @@ -4282,7 +4318,7 @@ paths: - SSA summary: Create SSA. description: Create `SSA` for the organization with `expiration` (optional). - operationId: post-register + operationId: post-register-ssa security: - bearer: [ ] requestBody: