Merge pull request #325 from 0xSiO/master

QPPAUTH-3507 Review & update external user-facing OAuth documentation (Part 2)

Author: davidberry-sb

oauth_sample/.prettierrc.json

@@ -1 +1 @@
-nodejs 22.2.0
+nodejs 22.14.0

oauth_sample/.tool-versions

@@ -1,29 +1,18 @@
 # QPP OAuth Sample Client
 
-Node.js client application to demonstrate OpenID Connect + OAuth 2.0 integration with [QPP](https://qpp.cms.gov).
-
-Supports both the [authorization code flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1) and the [authorization code flow with PKCE](https://tools.ietf.org/html/rfc7636).
-For your application, you will only need to support **one** of these flows.
-
-## Requirements
-
-This application has been tested on Node.js v22.2.0.
+Example client application to demonstrate [OAuth 2.0](https://www.oauth.com/) + [OpenID Connect](https://openid.net/developers/how-connect-works/) integration with [QPP](https://qpp.cms.gov).
 
 ## Getting started
 
 ### Installation
 
-Install the dependencies:
-
-```bash
-npm ci
-```
+This application has been tested on Node.js v22. Install dependencies by running `npm ci`.
 
 ### Setup
 
 First, ensure you've created a QPP Developer Preview account and registered a new OAuth application by following the instructions on [this page](https://cmsgov.github.io/qpp-submissions-docs/getting-started-with-oauth).
 
-Many of the fields required for registration may contain arbitrary "dummy" values (like `privacyPolicyURI` or `tosURI`), but the following *must* be configured correctly in order to use the sample client:
+Many of the fields required for registration may contain arbitrary "dummy" values (like `privacyPolicyURI` or `tosURI`), but the following **must** be configured correctly in order to use the sample client:
 * `redirectURIs` - *must* contain the absolute URL to the `/logged_in` endpoint for your development server
     * e.g. `http://localhost:3000/logged_in`
 * `logoutURIs` - *must* contain the absolute URL to the `/logged_out` endpoint for your development server
@@ -32,9 +21,9 @@ Many of the fields required for registration may contain arbitrary "dummy" value
     * `web` applications are typical web apps with a backend server. They will receive both a client ID and a client secret.
     * `native` applications are client-side apps (e.g. mobile/desktop apps). They will receive only a client ID, since a client secret cannot be stored safely.
 
-After registering the application, copy `.example.env` to `.env` and use the returned client information to populate the following values in `.env`:
-* `CLIENT_ID` - Registered client id. Always required.
-* `CLIENT_SECRET` - Registered client secret. Required for applications of type `web`, which can securely store a secret on the backend. For `native` applications, leave this blank and be sure to use the [PKCE flow](https://tools.ietf.org/html/rfc7636) for authorization (see the `/login-pkce` endpoint below).
+After registering the application, copy `.example.env` to `.env` and use your new client information to populate the following values in `.env`:
+* `CLIENT_ID` - Registered client ID. Always required.
+* `CLIENT_SECRET` - Registered client secret. Required for applications of type `web`, which can securely store a secret on the backend. For `native` applications, leave this blank.
 * `LOGIN_REDIRECT_URL` - The registered post-login redirect URL (i.e. the value you chose to put in `redirectURIs`)
 * `LOGOUT_REDIRECT_URL` - The registered post-logout redirect URL (i.e. the value you chose to put in `logoutURIs`)
 
@@ -57,18 +46,16 @@ Serves as a basic homepage for the application. Contains information about the c
 
 #### `/login`
 
-Begins the [authorization code flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1). Only applicable for applications of type `web`. For `native` applications, see `/login-pkce`.
-
-#### `/login-pkce`
+Begins the [OAuth 2.0 authorization code flow](https://www.oauth.com/oauth2-servers/pkce/authorization-request/). Note that, for additional security, the [Proof Key for Code Exchange](https://www.oauth.com/oauth2-servers/pkce/) extension is used regardless of the application type.
 
-Begins the [authorization code flow with PKCE](https://tools.ietf.org/html/rfc7636). Only applicable for applications of type `native`. For `web` applications, see `/login`.
+If you are testing your application in the QPP Developer Preview environment, please reserve scenarios beforehand using the [My Test Data](https://preview.qpp.cms.gov/user/test-data) section in the Developer Preview UI or the [QPP Synthetic Test Data API](https://preview.qpp.cms.gov/api/synthetic-data/docs/index.html).
 
 #### `/logged_in`
 
 Post-login redirect endpoint to receive the authorization code. This endpoint fetches tokens from the authorization server and sets the following cookies:
-- `qpp_access_token` - the access token, used to authorize against QPP APIs like the [the Auth service API](https://preview.qpp.cms.gov/api/auth/docs) or the [submissions API](https://preview.qpp.cms.gov/api/submissions/public/docs/). The access token must be sent in the `Authorization` header in the format `Bearer <access_token>`. Your application should not attempt to parse the contents of this token.
+- `qpp_access_token` - the access token, used to authorize against QPP APIs like the [the Auth service API](https://preview.qpp.cms.gov/api/auth/docs) or the [submissions API](https://preview.qpp.cms.gov/api/submissions/public/docs/). The access token must be sent in the `Authorization` header in the format `Bearer <access_token>`. Your application **should not** attempt to parse the contents of this token.
 - `qpp_refresh_token` - the refresh token, used to request a new access token from the authorization server
-- `qpp_id_token` - the ID token, issued to your application as proof that the user is authenticated. Your application should parse/verify the contents of this token and use it to customize your UI if applicable.
+- `qpp_id_token` - the [ID token](https://www.oauth.com/oauth2-servers/openid-connect/id-tokens/), issued to your application as proof that the user is authenticated. Your application should parse/verify the contents of this token and use it to customize your UI if applicable.
 
 #### `/verify`
 
@@ -80,7 +67,7 @@ Uses the refresh token to request new tokens from the authorization server.
 
 #### `/logout`
 
-Revokes all tokens and signs the user out of CMS IDM.
+[Revokes all tokens](https://oauth.net/2/token-revocation/) and [ends the user's session](https://openid.net/specs/openid-connect-rpinitiated-1_0.html).
 
 #### `/logged_out`