diff --git a/elytron/WFLY-17143-request-uri-parameters.adoc b/elytron/WFLY-17143-request-uri-parameters.adoc new file mode 100644 index 000000000..46de30ff1 --- /dev/null +++ b/elytron/WFLY-17143-request-uri-parameters.adoc @@ -0,0 +1,138 @@ += Add the ability to specify that the OIDC Authentication Request should include request and request_uri parameters +:author: Prarthona Paul +:email: prpaul@redhat.com +:toc: left +:icons: font +:idprefix: +:idseparator: - + +== Overview + +OpenID Connect is an authentication mechanism that builds on OAuth 2.0 and allows a user to login to a web application using credentials established by an OpenID provider. Authentication requests sent using OpenID Connect can be signed and optionally encrypted. This can be achieved using 2 auth request parameters: `request` and `request_uri`, which are both optional. + +According to the https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests[OpenID docs], requests using these parameters are represented as JWTs, which are respectively passed by value or by reference. Depending on the OpenID Provider, support for `request` may or may not be available. + +== Issue Metadata + +=== Issue + +* https://issues.redhat.com/browse/WFLY-17143[WFLY-17143] + +=== Related Issues + +* https://issues.redhat.com/browse/EAP7-1974[EAP7-1974] +* [INSERT ELY ISSUE] + +=== Dev Contacts + +* mailto:{email}[{author}] + +=== QE Contacts + +=== Testing By +* [x] Engineering + +* [ ] QE + +=== Affected Projects or Components + +* WildFly +* WildFly Elytron + +=== Other Interested Projects + +N/A + +=== Relevant Installation Types +* [x] Traditional standalone server (unzipped or provisioned by Galleon) + +* [x] Managed domain + +* [x] OpenShift s2i + +* [x] Bootable jar + +== Requirements + +=== Hard Requirements + +* Two new attributes named `request` and `request-uri` will be added to the `secure-deployment` resource under the `elytron-oidc-client` subsystem, which will be used to specify either the `request` or the `request_uri`, which are both JWTs. + +* According to the https://issues.redhat.com/browse/EAP7-1974[OIDC specs], only one of the two parameters can be specified at a time. If `request` is added, then `request_uri` MUST NOT be used in the same request. However, the user can choose to specify neither. + +* The `request` and `request_uri` parameters MUST NOT be included in Request Objects. + +* The Request Object MAY be signed or unsigned(plaintext) and can be specified by value or by reference. + * By value: The `request` parameter is added to the query and its value is the Request Object itself. + * Example of `request` string: + +``` + y9Lqv4fCp6Ei-u2-ZCKq83YvbFEk6JMs_pSj76eMkddWRuWX2aBKGHAtKlE5P + 7_vn__PCKZWePt3vGkB6ePgzAFu08NmKemwE5bQI0e6kIChtt_6KzT5OaaXDF + I6qCLJmk51Cc4VYFaxgqevMncYrzaW_50mZ1yGSFIQzLYP8bijAHGVjdEFgZa + ZEN9lsn_GdWLaJpHrB3ROlS50E45wxrlg9xMncVb8qDPuXZarvghLL0HzOuYR + adBJVoWZowDNTpKpk2RklZ7QaBO7XDv3uR7s_sf2g-bAjSYxYUGsqkNA9b3xV + W53am_UZZ3tZbFTIh557JICWKHlWj5uzeJXaw +``` + + * This can be added to the auth request by adding the whole string: + +``` + https://idsvr.example.com/oauth/v2/oauth-authorize? + &client_id=client-one + &response_type=code + &scope=openid + &request=y9Lqv4fCp6Ei-u2-ZCKq83YvbFEk6JMs... +``` + + * By reference: This is useful when the `request` string is too large and a number of other https://openid.net/specs/openid-connect-core-1_0.html#RequestUriRationale[reasons]. In this case, the Request Object is passed as a reference parameter string using the `request_uri` parameter. The value references the Request Object, which the Provider can use to download the Request Object itself. + + * An example `request_uri` is as follows: + +``` + https://client.example.org/request.jwt#GkurKxf5T0Y-mnPFCHqWOMiZi4VS138cQO_V7PZHAdM +``` + + * When included in the auth request, the request_uri would be specified as: + +``` + https://server.example.com/authorize? + response_type=code%20id_token + &client_id=s6BhdRkqt3 + &request_uri=https%3A%2F%2Fclient.example.org%2Frequest.jwt + %23GkurKxf5T0Y-mnPFCHqWOMiZi4VS138cQO_V7PZHAdM + &state=af0ifjsldkj&nonce=n-0S6_WzA2Mj + &scope=openid +``` + +* According to the OpenID docs, if the same parameter exists both in the Request Object and the OAuth Authorization Request parameters, the parameter in the Request Object is used. + +* The feature must deal with cases where the OpenId Provider does not support request parameters by recognizing `request_not_supported` error and dealing with it accordingly. + +* It should be possible to specify that these parameters should be included in the Authentication Request via deployment configuration using the `oidc.json` file inside the `WEB-INF` directory of the web application and `elytron-oidc-client` subsystem configuration. + +=== Nice-to-Have Requirements + +N/A + +=== Non-Requirements + +N/A + +== Backwards Compatibility + +N/A + +=== Default Configuration + +By default, neither `request` or `request_uri` would be specified. + +== Test Plan + +* WildFly Elytron Tests: Test cases implemented for functionality. +* WildFly Testsuite: Test cases will be added to check for subsystem parsing. + * Additional integration tests will be added to test the full functionality of the `elytron-oidc-subsystem` when `request` and `request_uri` are configured. + * + +== Community Documentation +Documentation for the new scope option will be added to https://github.com/wildfly/wildfly/blob/main/docs/src/main/asciidoc/_admin-guide/subsystem-configuration/Elytron_OIDC_Client.adoc[Elytron OpenID Connect Client Subsystem Configuration].