diff --git a/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/img/postman_sts_auth.png b/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/img/postman_sts_auth.png deleted file mode 100644 index 0bc800ef83f..00000000000 Binary files a/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/img/postman_sts_auth.png and /dev/null differ diff --git a/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/img/postman_sts_variables.png b/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/img/postman_sts_variables.png deleted file mode 100644 index ee476b2ed69..00000000000 Binary files a/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/img/postman_sts_variables.png and /dev/null differ diff --git a/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/postman.md b/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/postman.md deleted file mode 100644 index 5c1f2cfd2fe..00000000000 --- a/products/identity/Products/Sign-In Service/Engineering Docs/Authentication Types/Service Account Auth (STS)/postman/postman.md +++ /dev/null @@ -1,70 +0,0 @@ -# Service Account Auth (STS) Postman Collection - -## Overview - -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`. - -The collection is available for download here: [VA.gov Identity - Service Account Auth (STS)](https://github.com/department-of-veterans-affairs/va.gov-team-sensitive/blob/f1c9526e8c04de099832441cd1778bba8a66e213/teams/vsp/teams/Identity/Product%20Documentation/Sign%20In%20Service/postman_collections/Service_Account_Auth.postman_collection.json) - -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 Postman collection [VA.gov Identity - Service Account Auth (STS)](https://github.com/department-of-veterans-affairs/va.gov-team-sensitive/blob/f1c9526e8c04de099832441cd1778bba8a66e213/teams/vsp/teams/Identity/Product%20Documentation/Sign%20In%20Service/postman_collections/Service_Account_Auth.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 - Service Account Auth (STS)` -3. Navigate to the `Variables` tab. -4. Add the following variables and their respective values based on your service account configuration: - - `vets_api_host`: The environment you are making the request to - - `sts_jwt_assertion_service_account_id`: `ServiceAccountConfig.service_account_id` - - `sts_jwt_assertion_issuer`: `ServiceAccountConfig.access_token_audience` - - `sts_jwt_assertion_audience`: The route you are making the request to (the token route) `https://staging-api.va.gov/v0/sign_in/token` - - `sts_jwt_assertion_subject`: email of the user or some other identifier - - `sts_jwt_assertion_scopes`: `ServiceAccountConfig.scopes` - -**NOTE:** `sts_jwt_assertion_payload` and `sts_access_token` 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. -4. Ensure `Payload` is set to `{{sts_jwt_assertion_payload}}`. This will be auto populated based on your variable inputs. -5. 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 `sts_access_token` variable will be automatically set to the token in the response - -### 5. Make `protected scoped route` request - -1. Set the `sts_access_token_scoped_route` to the route in your scopes you want to query -2. The `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 diff --git a/products/identity/Products/identity_postman.md b/products/identity/Products/identity_postman.md index c37ef3d3967..b334727c0e0 100644 --- a/products/identity/Products/identity_postman.md +++ b/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.