From 90b0690861efe461a56315e89561223608da50c9 Mon Sep 17 00:00:00 2001 From: gmo Date: Wed, 21 Apr 2021 12:30:18 +0200 Subject: [PATCH 1/5] draft RAR --- design/rich-authorization-requests.md | 177 ++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 design/rich-authorization-requests.md diff --git a/design/rich-authorization-requests.md b/design/rich-authorization-requests.md new file mode 100644 index 0000000..2c53f28 --- /dev/null +++ b/design/rich-authorization-requests.md @@ -0,0 +1,177 @@ +# Rich Authorization Requests (RAR) + +* **Status**: Notes +* **JIRA**: TBD + + +## Motivation + +[Rich Authorization Requests][1] is designed to allow OAuth Client to include detailed information to an authorization request. Thus, Client can make a specific authorization requirement. + +## Specifications + +The spec introduces a new parameter "authorization_details" that allows clients to specify their fine-grained authorization, such as `please let me make a payment with the amount of 45 Euros` or `please give me read access to folder A and write access to file X`. + +An example of authorization details using +the payment authorization object: + +```` +[ + { + "type": "payment_initiation", + "actions": [ + "initiate", + "status", + "cancel" + ], + "locations": [ + "https://example.com/payments" + ], + "instructedAmount": { + "currency": "EUR", + "amount": "123.50" + }, + "creditorName": "Merchant123", + "creditorAccount": { + "iban": "DE02100100109307118603" + }, + "remittanceInformationUnstructured": "Ref Number Merchant" + } + ] +```` + +The type of data contained in authorization details is infinite and depends on the field (Payment, Health, Tax Data, etc...) + +Therefore, it will be more scalable to add the processing of authorization details as SPI (e.g. `RarProcessor.Class`). Then, an extension can come with the specific implementation. + +However, there is some default configuration and behavior keycloak should implement: + +- Add parameters in Authorization Server Metadata +- Add parameters in Client Metadata +- Accept `authorization_details` parameter in all places where the `scope` parameter is used +- Add authorization details to access tokens and token introspection + +### Authorization Server Metadata + +These parameters should be added to the .well-known/openid-configuration: + +- **authorization_details_supported** + +The AS advertises support for "authorization_details" using the +metadata parameter "authorization_details_supported" of type boolean. + + +- **authorization_data_types_supported** + +The authorization data types supported can be determined using the metadata parameter "authorization_data_types_supported", which is an JSON array. + +### Client Metadata + +- **authorization_data_types** + +Clients announce the authorization data types they use in the new dynamic client registration parameter "authorization_data_types". + + +### Authorization Request + +The `authorization_details` request parameter will be used to specify +authorization requirements in all places where the "scope" parameter +is used for the same purpose, examples include: + +* Authorization requests as specified in [RFC6749], + +* Access token requests as specified in [RFC6749], if also used as + authorization requests, e.g. in the case of assertion grant types + [RFC7521], + +* Request objects as specified in [I-D.ietf-oauth-jwsreq], + +* Device Authorization Request as specified in [RFC8628], + +* Backchannel Authentication Requests as defined in [OpenID.CIBA]. + +### Token Response + +In addition to the token response parameters as defined in [RFC6749], +the authorization server MUST also return the authorization details +as granted by the resource owner and assigned to the respective +access token. + +## Implementation details + +SPI + +```` +public interface RarProcessorProvider extends Provider {} + +public interface RarProcessorProviderFactory extends ProviderFactory { } +```` +e.g. implementation in extension + +```` +public class Psd2RarProcessorProvider implements RarProcessorProvider {} + +public class Psd2RarProcessorProviderFactory implements RarProcessorProviderFactory { + + public static final String ID = "rar-psd2"; + public static final String SUPPORTED_DATA_TYPE = []; //Json array schema definition +} +```` + +* Support advertisement of supported authorization details types in OAuth server metadata + +```` +OIDCConfigurationRepresentation config = new OIDCConfigurationRepresentation(); +config.setAuthorizationDataTypesSupported( + getSupportedAuthorizationDataTypes(RarProcessorProvider.class) + +); +```` + +* Check if authorization data type or authorization details is not conforming to the respective type + definition when authorization_details is available in the authorization requests + +```` +rarProcessorProvider.isAuthorizationDetailsCompliant(authorizationDetails) +```` +After the user authenticate, rarProcessor should: + +* Determine how authorization details are shown to the user in the user consent +* Exchange with the resource server if necessary +* Enrich authorization details in the user consent process (e.g. add selected accounts or set expirations) +* show the consent page + +```` +rarProcessorProvider.prepareAuthorizationDetails() +```` + +When the user submits the consent + +* Merge requested and pre-existing authorization_details (e.g. in case of update) + +* store authorization_details within the grant + +```` +rarProcessorProvider.processAuthorizationDetails() +```` + +### Admin UI + +AS should give the possibility to activate and deactivate RAR through a checkbox by changing the value of `authorization_details_supported` + +AS should allow the possibility to select RarProcessor Implementation Module. + +Files/Classes/methods affected: + +## Tests +RAR should be properly covered by unit and integration tests. + +## Documentation +RAR usage should be properly documented. + +Affected documents: Securing Applications and Services Guide + +## Resources +* [draft-ietf-oauth-rar][1] + +[1]: https://tools.ietf.org/html/draft-ietf-oauth-rar-04 From ca436ce10cafda6dfc66542d46998d24b2081cc2 Mon Sep 17 00:00:00 2001 From: gmo Date: Fri, 11 Jun 2021 20:21:56 +0200 Subject: [PATCH 2/5] review --- design/rich-authorization-requests.md | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/design/rich-authorization-requests.md b/design/rich-authorization-requests.md index 2c53f28..0b6d9d2 100644 --- a/design/rich-authorization-requests.md +++ b/design/rich-authorization-requests.md @@ -53,28 +53,23 @@ However, there is some default configuration and behavior keycloak should implem ### Authorization Server Metadata -These parameters should be added to the .well-known/openid-configuration: +This parameter must be added to the .well-known/openid-configuration: -- **authorization_details_supported** +- **authorization_details_types_supported** -The AS advertises support for "authorization_details" using the -metadata parameter "authorization_details_supported" of type boolean. - - -- **authorization_data_types_supported** - -The authorization data types supported can be determined using the metadata parameter "authorization_data_types_supported", which is an JSON array. +The authorization data types supported can be determined using the metadata parameter "authorization_details_types_supported", which is an JSON array. ### Client Metadata -- **authorization_data_types** +- **authorization_details_types** -Clients announce the authorization data types they use in the new dynamic client registration parameter "authorization_data_types". +Clients announce the authorization data types they use in the new dynamic client registration parameter "authorization_details_types". ### Authorization Request -The `authorization_details` request parameter will be used to specify +As per spec, +The `authorization_details` request parameter CAN be used to specify authorization requirements in all places where the "scope" parameter is used for the same purpose, examples include: @@ -90,6 +85,8 @@ is used for the same purpose, examples include: * Backchannel Authentication Requests as defined in [OpenID.CIBA]. +we will use it first in Authorization requests. + ### Token Response In addition to the token response parameters as defined in [RFC6749], @@ -157,8 +154,6 @@ rarProcessorProvider.processAuthorizationDetails() ### Admin UI -AS should give the possibility to activate and deactivate RAR through a checkbox by changing the value of `authorization_details_supported` - AS should allow the possibility to select RarProcessor Implementation Module. Files/Classes/methods affected: From 55eb26000958385a7ee2da66bd0bff2215b6b743 Mon Sep 17 00:00:00 2001 From: gmo Date: Mon, 2 Aug 2021 11:48:33 +0200 Subject: [PATCH 3/5] link implementation --- design/rich-authorization-requests.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/design/rich-authorization-requests.md b/design/rich-authorization-requests.md index 0b6d9d2..b3b9a7a 100644 --- a/design/rich-authorization-requests.md +++ b/design/rich-authorization-requests.md @@ -2,6 +2,7 @@ * **Status**: Notes * **JIRA**: TBD +* **Implementation**: https://github.com/tnorimat/keycloak/pull/24 ## Motivation @@ -42,9 +43,9 @@ the payment authorization object: The type of data contained in authorization details is infinite and depends on the field (Payment, Health, Tax Data, etc...) -Therefore, it will be more scalable to add the processing of authorization details as SPI (e.g. `RarProcessor.Class`). Then, an extension can come with the specific implementation. +Therefore, it will be more scalable to add the processing of authorization details as SPI (e.g. `RarProcessor.Class`). Then, an extension will come with the specific implementation. -However, there is some default configuration and behavior keycloak should implement: +However, there is some default configuration and behavior which should be implemented: - Add parameters in Authorization Server Metadata - Add parameters in Client Metadata From 3aae0909d86b72be110689d6411f0abf5f2aca0c Mon Sep 17 00:00:00 2001 From: gmo Date: Thu, 5 Aug 2021 15:26:10 +0200 Subject: [PATCH 4/5] review --- design/rich-authorization-requests.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/design/rich-authorization-requests.md b/design/rich-authorization-requests.md index b3b9a7a..83855b8 100644 --- a/design/rich-authorization-requests.md +++ b/design/rich-authorization-requests.md @@ -43,6 +43,9 @@ the payment authorization object: The type of data contained in authorization details is infinite and depends on the field (Payment, Health, Tax Data, etc...) +RAR can be used in combination with PAR (Pushed Authorization +Request ), for large authentication_details for example. + Therefore, it will be more scalable to add the processing of authorization details as SPI (e.g. `RarProcessor.Class`). Then, an extension will come with the specific implementation. However, there is some default configuration and behavior which should be implemented: @@ -60,6 +63,11 @@ This parameter must be added to the .well-known/openid-configuration: The authorization data types supported can be determined using the metadata parameter "authorization_details_types_supported", which is an JSON array. +- **authorization_details_supported** + +The AS advertises support for "authorization_details". +should be `true` + ### Client Metadata - **authorization_details_types** @@ -159,6 +167,21 @@ AS should allow the possibility to select RarProcessor Implementation Module. Files/Classes/methods affected: +### Adapter + +Some adapters should be updated in order to support the new authorization_details + +Files/Classes/methods affected: + +* Keycloak adapter-core (org.keycloak.adapters.OAuthRequestAuthenticator#authenticate) + +* Keycloak JS Adapter (loginUrl creation with authorization_details parameter [PoC for Keycloak.js](https://gist.github.com/thomasdarimont/3e87944c31b6263f1849e35733a03500#file-index-html-L204)) + +* Access to authorization_details in tokenResponse see [keycloak.js](https://github.com/keycloak/keycloak/blob/b1d39aa136662d54deca10c97374f0932ce6316b/adapters/oidc/js/src/main/resources/keycloak.js#L675). + + + + ## Tests RAR should be properly covered by unit and integration tests. From a7172ec941f754b08ee8124f42d24fbf9d3306b1 Mon Sep 17 00:00:00 2001 From: gmo Date: Tue, 28 Sep 2021 13:02:42 +0200 Subject: [PATCH 5/5] review --- design/rich-authorization-requests.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/design/rich-authorization-requests.md b/design/rich-authorization-requests.md index 83855b8..7445627 100644 --- a/design/rich-authorization-requests.md +++ b/design/rich-authorization-requests.md @@ -63,6 +63,17 @@ This parameter must be added to the .well-known/openid-configuration: The authorization data types supported can be determined using the metadata parameter "authorization_details_types_supported", which is an JSON array. +Also authorization_details_types_supported will be an aggregated list of all types across all types of processor providers. Regarding collisions, we will add something like `getPriority` to the processor methods, this will allow that custom processor provider to be chosen for processing when dealing with the particular conflicting type. + +For example: Assume that there will be built-in provider DefaultProcessor, which will support types `my-type-1` and `my-type-2` with priority `1`. Then assume that administrator will deploy his own custom provider with higher priority (EG. `MyCustomProcessor`), which will support types `my-type-2` and `my-type-3` and will have higher priority. + +This will ensure that: + +authorization_details_types_supported may return all 3 types +The type `my-type-1` will be processed by default processor +The type `my-type-3` will be processed by MyCustomProcessor +The type `my-type-2` exists in both processors, but since `MyCustomProcessor` has higher priority, it will be chosen for processing this request. + - **authorization_details_supported** The AS advertises support for "authorization_details". @@ -163,7 +174,7 @@ rarProcessorProvider.processAuthorizationDetails() ### Admin UI -AS should allow the possibility to select RarProcessor Implementation Module. +Possibility to choose supported types of authorization_detail types for a client. Files/Classes/methods affected: @@ -193,4 +204,4 @@ Affected documents: Securing Applications and Services Guide ## Resources * [draft-ietf-oauth-rar][1] -[1]: https://tools.ietf.org/html/draft-ietf-oauth-rar-04 +[1]: https://tools.ietf.org/html/draft-ietf-oauth-rar-07