[VI-1012] updates identity postman documentation

products/identity/Products/identity_postman.md

@@ -1,38 +1,117 @@
 # VA.gov Identity Collection
 
-The VA.gov Identity team maintains a [Postman Collection](https://github.com/department-of-veterans-affairs/va.gov-team-sensitive/blob/master/teams/vsp/teams/Identity/Product%20Documentation/va_identity_postman.json) that can be used to test all of the different Sign-in Service (SiS) auth flows.
+The VA.gov Identity team maintains a [Postman Collection](https://github.com/department-of-veterans-affairs/va.gov-team-sensitive/blob/master/teams/vsp/teams/Identity/Documentation/Development/postman/collections/main/va.gov_identity.postman_collection.json) that can be used to test different Idenitity-relevant routes, including Sign-in Service (SiS).
 
-## VA Identity Collection Variables
+The Identity Postman collection is broken into three distinct sub-collections:
+- `vets-api`
+- Sign in Service
+- Mocked Authentication
 
-The variable values needed to connect to a SiS instance are managed within the `Variables` subtab in the `VA Identity` collection management:
+# VA Identity Collection Variables
+
+The variable values needed to change route parameters and other configs are managed within the `Variables` subtab in the `VA Identity` collection management:
 ![VA Identity Postman Variables view](https://github.com/department-of-veterans-affairs/va.gov-team/assets/20125855/af6bbe34-aba9-448c-bbe1-2f1de549f7ad)
 
-## Localhost authentication
+# `vets-api` Collection
+
+# Sign In Service Collection
+
+## PKCE Authentication
 
-The Identity Postman collection cannot perfectly imitate a web browser - in particular the initial authorization with a CSP must be performed in a web browser due to the necessity of completing various web forms. In order to use the Postman collection begin with the following steps:
+The Identity SiS collection cannot perfectly imitate a web browser - in particular the initial authorization with a CSP must be performed in a web browser due to the necessity of completing various web forms. In order to use the Postman collection, begin with the following steps:
 
 1. Make sure that your local instance of `vets-api` (localhost:3000) is running and `vets-website` (localhost:3001) is NOT, as the latter will automatically call the `/token` endpoint at the end of the callback process, consuming the auth_code that is needed for use in Postman.
 2. Navigate in your web browser to the `/authorize` endpoint generated by Postman. It is critical that the `code_challenge` is either the same as Postman's saved variable or generated from a `code_verifier` that you have access to in order for the later token request to work. You can also choose your preferred `client_id`, the most common being `vaweb` (default) & `vamobile`. In order to easily copy the generated Postman URL you can use the 'Documentation' view in the right sidebar:
     ![authorize_request](https://github.com/department-of-veterans-affairs/va.gov-team/assets/20125855/3c691624-8674-4a3b-934a-7a75b2141f95)
 
-    `http://localhost:3000/v0/sign_in/authorize?type=logingov&acr=ial2&client_id=vaweb&code_challenge=JNkFflCkxk1K6gQUf23P_5Ctl_T65_xkkOU_y-Cc2XI=&code_challenge_method=S256&state=c4addf6001661631d2524043ca31107e`
+    Example authorize request -  `http://localhost:3000/v0/sign_in/authorize?code_challenge_method=S256&type=logingov&acr=ial2&client_id=vaweb&code_challenge=JNkFflCkxk1K6gQUf23P_5Ctl_T65_xkkOU_y-Cc2XI=`
 3. Complete the CSP authentication and find the `callback` call that `vets-api` makes to `vets-website` at the end of the authentication process. This can either be done in your web browser or in Postman via the [Postman Interceptor](https://chrome.google.com/webstore/detail/postman-interceptor/aicmkgpgakddgnaphhhpliifpcfhicfo?hl=en) plugin:
     ![SiS vets-website callback](https://github.com/department-of-veterans-affairs/va.gov-team/assets/20125855/efc20692-5814-4291-8c1e-4dd7dbda096a)
 
-    `http://localhost:3001/auth/login/callback?code=0dc61ca6-6ccd-4dae-8fac-70dd590fe8c6&type=logingov&state=c4addf6001661631d2524043ca31107e`
-4. Copy the `code` URL parameter into your Postman SiS collection variables as the new `auth_code` and save the variables file. If you were using a newly generated `code_challenge` for the `/authorize` call you'll need to update the `code_verifier` variable as well.
+    Example request to `vets-website` callback - `http://localhost:3001/auth/login/callback?code=0dc61ca6-6ccd-4dae-8fac-70dd590fe8c6&type=logingov&state=c4addf6001661631d2524043ca31107e`
+4. Copy the `code` URL parameter into your Postman SiS collection variables as the new `sis_client-auth_code` variable and save the variables file. If you were using a newly generated `code_challenge` for the `/authorize` call you'll need to update the `code_verifier` variable as well.
 5. You should now be able to use Postman to make a `/token` call, passing the `auth_code` and receiving a set of tokens that Postman will save to make further calls. Postman will also automatically update tokens for `/refresh` calls and wipe them for successful `/logout`, `/revoke`, and `/revoke_all` calls.
 
-## Dev & Staging authentication
+## Private Key JWT Authentication
+
+## Service Account Auth (STS) Authentication
+
+This documentation provides instructions for configuring and using a Postman collection to authenticate using a JWT Bearer assertion with a private key. The token endpoint accepts the JWT assertion as a query parameter (`assertion`) along with the grant type `urn:ietf:params:oauth:grant-type:jwt-bearer`.
+
+Many of the concepts, necessary attributes, responses, etc. in this Postman guide are explained in more detail in the overall [STS auth guide](../auth_flows/service_account.md).
+
+### Prerequisites
+
+1. **Private Key**: Ensure you have the private key available for signing the JWT.
+2. **Service Account Config**: Ensure you have a service account config on the environment you are making the request to.
+    1. You will need these attributes to create your JWT assertion
+        - `iss` -> `ServiceAccountConfig.access_token_audience`
+        - `aud` -> The route you are making the request to (the token route) `https://staging-api.va.gov/v0/sign_in/token`
+        - `service_account_id` -> `ServiceAccountConfig.service_account_id`
+        - `sub` -> email of the user or some other identifier
+        - `scopes` -> `ServiceAccountConfig.scopes`
+
+### Step-by-Step Instructions
+
+#### 1. Import the Postman Collection
+
+1. Download the Identity [Postman Collection](https://github.com/department-of-veterans-affairs/va.gov-team-sensitive/blob/master/teams/vsp/teams/Identity/Documentation/Development/postman/collections/main/va.gov_identity.postman_collection.json)
+2. Open Postman and import the collection by clicking on `Import` and selecting the downloaded file.
+
+#### 2. Configure Collection Variables
+
+1. Click on the imported collection - `VA.gov Identity - Main`
+2. Navigate to the `Variables` tab.
+3. Add the following variables and their respective values based on your service account configuration:
+   - `sis_sts-host`: The environment you are making the request to
+   - `sis_sts-jwt_assertion_service_account_id`: `ServiceAccountConfig.service_account_id`
+   - `sis_sts-jwt_assertion_issuer`: `ServiceAccountConfig.access_token_audience`
+   - `sis_sts-jwt_assertion_audience`: The route you are making the request to (the token route) `https://staging-api.va.gov/v0/sign_in/token`
+   - `sis_sts-jwt_assertion_subject`: email of the user or some other identifier
+   - `sis_sts-jwt_assertion_scopes`: `ServiceAccountConfig.scopes`
+
+**NOTE:** `sis_sts-jwt_assertion_payload` and `sis_sts-access_token`//`vets_api-access_tokien` are autopopulated based on the inputs of the above variables.
+
+![postman_sts_variables](img/postman_sts_variables.png)
+
+#### 3. Set Up JWT Bearer Token Authentication
+
+1. In the collection, click the `POST token` request.
+2. Click on the `Authorization` tab.
+3. Ensure `Auth Type` is `JWT Bearer`
+4. Ensure `Algorithm` is `RS256`
+5. Add your `Private key` by either selecting the file or copy/pasting it into the box.
+6. Ensure `Payload` is set to `{{sis_sts-jwt_assertion_payload}}`. This will be auto populated based on your variable inputs.
+7. Under `Advanced configuration`:
+    1. Ensure `Query param name` is set to `assertion`
+    2. Ensure `JWT headers` is set to `{}`
+
+![postman_sts_auth](img/postman_sts_auth.png)
+
+#### 4. Make `token` request
+
+1. Make the `token` request by pressing `Send`
+2. If successful, you will see an `access_token` in the response.
+3. The `sis_sts-access_token` variable will be automatically set to the token in the response
+
+#### 5. Make `protected scoped route` request
+
+1. Open the `vets-api` collection's "STS Protected" subdirectory & make a copy of the MAP STS Token request, then populate the endpoint with your desired URL.
+2. The `vets_api-sts_access_token` from the previous request will automatically be added to the `Authorization` header
+3. Make the request to your scoped path
+4. You should receive a successful response
+
+
+### Dev & Staging Authentication
 
-Interacting with dev & staging SiS through Postman is largely the same as the process on localhost; you will still need to authenticate through an `/authorize` request with a `code_challenge` that you have the corresponding `code_verifier` to, then copy the `code` passed to the frontend `/callback` route into Postman to receive your tokens. In addition, the following changes will need to be made to the preceding workflow:
+Interacting with dev & staging SiS through Postman is largely the same as the process on localhost you will still need to authenticate through an `/authorize` request with a `code_challenge` that you have the corresponding `code_verifier` to, then copy the `code` passed to the frontend `/callback` route into Postman to receive your tokens. In addition, the following changes will need to be made to the preceding workflow:
 
-1. The `vets_api_env` variable must be set to `https://{dev|staging}-api.va.gov` - note the necessary `https` scheme.
+1. The `sis_client-host` variable must be set to `https://{dev|staging}-api.va.gov` - note the necessary `https` scheme.
 2. In order to prevent the vets-website frontend from calling the `/token` endpoint immediately and rendering the copied `code` useless you must prevent the request from sending in your browser's devtools: block `{dev|staging}-api.va.gov/v0/sign_in/token`
 
-## Mocked Authentication
+# Mocked Authentication Collection
 
-The Identity Postman collection can also interact with Sign in Service [mocked authentication](https://github.com/department-of-veterans-affairs/va.gov-team/tree/master/products/identity/Products/Mocked%20Authentication) service. The routes necessary for this are found under the `Sign In Service >> Mock Auth` directory. Unlike standard authentication which requires the web browser to perform a real login with the chosen credential service provider, mocked authentication can be performed entirely within Postman on localhost, development, and staging `vets-api` environments.
+The Identity Mocked Authentication collection can interact with Sign in Service [mocked authentication](https://github.com/department-of-veterans-affairs/va.gov-team/tree/master/products/identity/Products/Mocked%20Authentication) service. The routes necessary for this are found under the `Sign In Service >> Mock Auth` directory. Unlike standard authentication which requires the web browser to perform a real login with the chosen credential service provider, mocked authentication can be performed entirely within Postman on localhost, development, and staging `vets-api` environments.
 
 1. Call the `authorize state` route to generate the appropriate state. This call uses the `acr` and `csp_type` collection variables - set them for the CSP and ACR/LoA of the test user you wish to authenticate with. The returned state value is parsed from a 200 response and saved in the `mock_auth_state` collection variable.
 2. Call the `credential_list` route with the same `csp_type` to receive a list of the mocked credentials currently available on the requested `vets-api` instance. After selecting a mock credential copy the `encoded_credential` value for that user and save it in the `mock_encoded_credential` collection parameter.