[WFLY-17143] Add the ability to specify that the OIDC Authentication …

…Request should include request and request_uri parameters

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].