[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,161 @@
+= Add the ability to specify that the OIDC Authentication Request should include request and request_uri parameters
+:author:            Prarthona Paul
+:email:             [email protected]
+: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 by encoding query parameters in a JWT. This can be achieved using one of two auth request parameters: `request` and `request_uri`, which are both optional. The current version of `elytron-oidc-client` does not allow the user to specify `request` or `request_uri`. Instead, all requests are sent in using the OAuth 2.0 request syntax. This RFE will add an attribute to the `elytron-oidc-client` subsystem called `request-object-required`, which can allow the user to specify if they will use either of the request parameters. 
+
+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]
+* https://issues.redhat.com/browse/ELY-2584[ELY-2584]
+
+=== 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
+
+* A new attribute named `request-object-required` will be added to the `secure-deployment` resource under the `elytron-oidc-client` subsystem. The value for this attribute will be a String with 3 acceptable values: 
+** none
+** request
+** request_uri
+
+** The 'request-object-required' attribute will specify if either `request` or the `request_uri` would be added to the auth request. This will be an optional attribute. The default value for this attribute will be set to `none`, indicating that neither request parameters are used and the query parameters are sent through the url.
+
+* According to the https://openid.net/specs/openid-connect-core-1_0.html#JWTRequests[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 by setting `request-object-required` to `none`. 
+
+* 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. The entire Request URI MUST NOT exceed 512 ASCII characters. 
+
+** The request string 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.
+
+** 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
+```
+
+** The base64-encoded SHA-256 hash `23GkurKxf5T0Y-mnPFCHqWOMiZi4VS138cQO_V7PZHAdM` will allow the provider to cache the token for future use. It is a hash of the contents of the Request Object.
+
+* 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.
+
+The `request` attribute is specified through the deployment configuration as follows: 
+```
+{
+    "client-id" : "myclient",
+    "provider-url" : "${env.OIDC_PROVIDER_URL:http://localhost:8080}/realms/myrealm",
+    "public-client" : "true",
+    "request-object-required" : "request",
+    "principal-attribute" : "preferred_username",
+    "ssl-required" : "EXTERNAL"
+}
+``` 
+The `request` attribute is specified through the `elytron-oidc-client` subsystem as follows: 
+```
+    /subsystem=elytron-oidc-client/secure-deployment:add(client_id=myclient, provider-url="http://localhost:8090/", request-object-required="request")
+```
+
+The request attribute is specified through the deployment configuration as follows: 
+```
+{
+    "client-id" : "myclient",
+    "provider-url" : "${env.OIDC_PROVIDER_URL:http://localhost:8080}/realms/myrealm",
+    "public-client" : "true",
+    "request-object-required" : "request_uri",
+    "principal-attribute" : "preferred_username",
+    "ssl-required" : "EXTERNAL"
+}
+```
+The `request` attribute is specified through the `elytron-oidc-client` subsystem as follows: 
+```
+    /subsystem=elytron-oidc-client/secure-deployment:add(client_id=myclient, provider-url="http://localhost:8090/", request-object-required="request_uri")
+``` 
+
+=== 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. 
+** Tests will be performed using signed, unsigned, encrypted and plaintext JWT requests, with the request specified both by value and by reference. 
+
+== Community Documentation
+Documentation for the new `request` and `request_uri` attributes 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].