AWS quick medium security documentation change
Summary
Updated identity provider support from Google Workspace to Ping Identity (PingFederate/PingOne). Added detailed configuration steps for PingFederate including OIDC policy requirements. Enhanced Okta/PingOne setup instructions. Added security-critical notes about refresh token configuration and attribute mapping.
Security assessment
Added PingFederate-specific requirement for 'Return ID Token On Refresh Grant' to prevent stale claims after refresh. Emphasized email claim mapping requirements for PingFederate to ensure proper authentication. Added warnings about irreversible configuration errors in extension access setup. Strengthened refresh token troubleshooting for all IdPs.
Diff
diff --git a/quick/latest/userguide/desktop-enterprise-setup.md b/quick/latest/userguide/desktop-enterprise-setup.md index 864e960da..cc57b8e2b 100644 --- a//quick/latest/userguide/desktop-enterprise-setup.md +++ b//quick/latest/userguide/desktop-enterprise-setup.md @@ -36 +36 @@ The setup involves the following steps, in order: -This guide provides IdP-specific instructions for Microsoft Entra ID, Okta, PingOne, and Google Workspace. See instructions for your specific identity provider below. +This guide provides IdP-specific instructions for Microsoft Entra ID, Okta, and Ping Identity (PingFederate and PingOne). See instructions for your specific identity provider below. @@ -71,3 +71 @@ The desktop application requires refresh tokens to maintain long-lived sessions. - * **PingOne** – The Refresh Token grant type must be enabled. The `offline_access` scope is optional but recommended. - - * **Google Workspace** – Refresh tokens are returned automatically for desktop applications. No additional configuration is required. + * **Ping Identity** – The Refresh Token grant type must be enabled, and the `offline_access` scope must be granted. For PingFederate, the **Return ID Token On Refresh Grant** setting must also be enabled in the OIDC policy. @@ -81,0 +80,2 @@ Choose the instructions for your identity provider. +For detailed instructions, see [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in the Microsoft Entra documentation. + @@ -140,0 +141,2 @@ JWKS URI | `https://login.microsoftonline.com/<TENANT_ID>/discovery/v2.0/keys` +For detailed instructions, see [Create OpenID Connect app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) in the Okta documentation. + @@ -169 +171 @@ PKCE (S256) is enforced automatically by Okta for native applications. - 1. In the app integration, go to the **Okta API Scopes** tab. + 1. In the Okta Admin Console, navigate to **Security → API → Authorization Servers** and select your authorization server (for example, **default**). @@ -171 +173 @@ PKCE (S256) is enforced automatically by Okta for native applications. - 2. Grant the following scopes: `openid`, `email`, `profile`, `offline_access`. + 2. On the **Scopes** tab, verify that the following scopes are enabled: `openid`, `email`, `profile`, `offline_access`. @@ -172,0 +175 @@ PKCE (S256) is enforced automatically by Okta for native applications. + 3. On the **Access Policies** tab, verify that the policy assigned to this application allows the `Authorization Code` and `Refresh Token` grant types. @@ -176,3 +178,0 @@ PKCE (S256) is enforced automatically by Okta for native applications. -###### Note - -If you are using a custom authorization server, verify that these scopes are also enabled under **Security → API → Authorization Servers → default → Scopes**. @@ -202 +202 @@ JWKS URI | `https://<OKTA_DOMAIN>/oauth2/default/v1/keys` -### PingOne +### Ping Identity @@ -204 +204 @@ JWKS URI | `https://<OKTA_DOMAIN>/oauth2/default/v1/keys` -###### To create the PingOne OIDC Native Application +Choose the instructions for your Ping Identity product. @@ -206 +206 @@ JWKS URI | `https://<OKTA_DOMAIN>/oauth2/default/v1/keys` - 1. In the PingOne Admin Console, navigate to **Applications → Applications → +** (Add Application). +#### PingFederate @@ -208 +208 @@ JWKS URI | `https://<OKTA_DOMAIN>/oauth2/default/v1/keys` - 2. Enter `Amazon Quick Desktop` as the application name. +For detailed instructions, see [Setting up an OIDC application in PingFederate](https://docs.pingidentity.com/solution-guides/customer_use_cases/htg_oidc_app_setup_pf.html) in the Ping Identity documentation. @@ -210 +210 @@ JWKS URI | `https://<OKTA_DOMAIN>/oauth2/default/v1/keys` - 3. Select **OIDC Native App** as the application type, then choose **Save**. +###### To create the PingFederate OIDC client @@ -212 +212 @@ JWKS URI | `https://<OKTA_DOMAIN>/oauth2/default/v1/keys` - 4. On the **Configuration** tab, choose **Edit** and configure the following settings: + 1. In the PingFederate administrative console, go to **Applications → OAuth → Clients** , and choose **Add Client**. @@ -214,7 +214 @@ JWKS URI | `https://<OKTA_DOMAIN>/oauth2/default/v1/keys` -Setting | Value ----|--- -Response Type | Code -Grant Types | Authorization Code and Refresh Token -PKCE Enforcement | S256 -Redirect URIs | `http://localhost:18080` -Token Endpoint Authentication Method | None + 2. In the **Client ID** field, enter a unique identifier for this client. @@ -222 +216 @@ Token Endpoint Authentication Method | None - 5. Choose **Save**. + 3. In the **Name** field, enter `Amazon Quick Desktop`. @@ -224 +218 @@ Token Endpoint Authentication Method | None - 6. On the **Resources** tab, add the following scopes: `openid`, `email`, `profile`. + 4. For **Client Authentication** , select **None**. @@ -226 +220 @@ Token Endpoint Authentication Method | None - 7. Toggle the application to **Enabled**. + 5. In the **Redirection URI** section, enter `http://localhost:18080` and choose **Add**. @@ -228 +222 @@ Token Endpoint Authentication Method | None - 8. Note the **Client ID** and **Environment ID** from the **Configuration** tab. + 6. In the **Allowed Grant Types** list, select **Authorization Code** and **Refresh Token**. @@ -229,0 +224 @@ Token Endpoint Authentication Method | None + 7. Select the **Require Proof Key for Code Exchange (PKCE)** checkbox. @@ -230,0 +226 @@ Token Endpoint Authentication Method | None + 8. Under **Common Scopes** , grant the following: `openid`, `email`, `profile`, `offline_access`. @@ -231,0 +228 @@ Token Endpoint Authentication Method | None + 9. Choose **Save**. @@ -233 +230 @@ Token Endpoint Authentication Method | None -###### To verify authentication settings + 10. Note the **Client ID**. You need this value in later steps. @@ -235 +231,0 @@ Token Endpoint Authentication Method | None - 1. In the PingOne Admin Console, navigate to **Applications → Applications** and select the Amazon Quick Desktop application. @@ -237 +232,0 @@ Token Endpoint Authentication Method | None - 2. On the **Configuration** tab, confirm that the Response Type is **Code** , Grant Types include **Authorization Code** and **Refresh Token** , PKCE Enforcement is **S256** , and Token Endpoint Authentication Method is **None**. @@ -239 +233,0 @@ Token Endpoint Authentication Method | None - 3. Confirm that `http://localhost:18080` is listed as a redirect URI. @@ -241 +235 @@ Token Endpoint Authentication Method | None - 4. Confirm that the application toggle is set to **Enabled**. +###### To configure the OIDC policy @@ -242,0 +237 @@ Token Endpoint Authentication Method | None + 1. In the PingFederate administrative console, go to **Applications → OAuth → OpenID Connect Policy Management**. @@ -243,0 +239 @@ Token Endpoint Authentication Method | None + 2. Select the OIDC policy associated with this client, or choose **Add Policy** to create one. @@ -244,0 +241,5 @@ Token Endpoint Authentication Method | None + 3. Select the **Return ID Token On Refresh Grant** checkbox. This ensures that the desktop application receives a fresh ID token with current claims when refreshing the session. + + 4. Under **Attribute Contract** , verify that the `email` claim is included and mapped to the corresponding user attribute in your authentication source. The `email` claim must be present in tokens issued during both initial authentication and refresh token grants. + + 5. Choose **Save**. @@ -246 +246,0 @@ Token Endpoint Authentication Method | None -Your OIDC endpoints use the following format. Replace `<ENV_ID>` with your PingOne environment ID. @@ -248 +247,0 @@ Your OIDC endpoints use the following format. Replace `<ENV_ID>` with your PingO -###### Note @@ -250 +249,2 @@ Your OIDC endpoints use the following format. Replace `<ENV_ID>` with your PingO -The PingOne domain varies by region. The examples below use `.com`. Replace the domain with the one for your environment (for example, `.ca`, `.eu`, or `.asia`). + +Your OIDC endpoints use the following format. Replace `<PINGFEDERATE_HOST>` with your PingFederate server hostname. @@ -254,4 +254,4 @@ Field | Value -Issuer URL | `https://auth.pingone.com/<ENV_ID>/as` -Authorization endpoint | `https://auth.pingone.com/<ENV_ID>/as/authorize` -Token endpoint | `https://auth.pingone.com/<ENV_ID>/as/token` -JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` +Issuer URL | `https://<PINGFEDERATE_HOST>` +Authorization endpoint | `https://<PINGFEDERATE_HOST>/as/authorization.oauth2` +Token endpoint | `https://<PINGFEDERATE_HOST>/as/token.oauth2` +JWKS URI | `https://<PINGFEDERATE_HOST>/pf/JWKS` @@ -259 +259 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` -### Google Workspace +#### PingOne @@ -261 +261 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` -###### To create the Google OAuth 2.0 Desktop client +For detailed instructions, see [Editing an application – Native](https://docs.pingidentity.com/pingone/applications/p1_edit_application_native.html) in the Ping Identity documentation. @@ -263 +263 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` - 1. In the Google Cloud Console, navigate to **APIs & Services → Credentials → Create credentials → OAuth client ID**. +###### To create the PingOne OIDC native application @@ -265 +265 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` - 2. Select **Desktop app** as the application type. + 1. In the PingOne admin console, go to **Applications → Applications** and choose the **+** icon. @@ -267 +267 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` - 3. Set the name to `Amazon Quick Desktop`. + 2. Enter `Amazon Quick Desktop` as the application name. @@ -269 +269 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` - 4. Choose **Create**. + 3. In the **Application Type** section, select **Native** , then choose **Save**. @@ -271 +271 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` - 5. Note the **Client ID** from the confirmation dialog. + 4. On the **Configuration** tab, choose **Edit** and configure the following settings: @@ -272,0 +273,7 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` +Setting | Value +---|--- +Response Type | Code +Grant Type | Authorization Code and Refresh Token +PKCE Enforcement | S256 +Redirect URIs | `http://localhost:18080` +Token Endpoint Authentication Method | None @@ -273,0 +281 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` + 5. Choose **Save**. @@ -274,0 +283 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` + 6. On the **Resources** tab, add the following scopes: `openid`, `email`, `profile`, `offline_access`. @@ -276 +285 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` -###### Note + 7. On the **Attribute Mappings** tab, verify that the `email` attribute is mapped to the user's email address. @@ -278 +287 @@ JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` -Google issues a client secret for desktop apps, but it is not treated as confidential for installed applications. The desktop app uses the authorization code flow with PKCE — the client secret is optional in the token exchange. + 8. Toggle the application to **Enabled**. @@ -280 +289 @@ Google issues a client secret for desktop apps, but it is not treated as confide -###### To configure the OAuth consent screen + 9. Note the **Client ID** and **Environment ID** from the **Configuration** tab. @@ -282 +290,0 @@ Google issues a client secret for desktop apps, but it is not treated as confide - 1. In the Google Cloud Console, navigate to **APIs & Services → OAuth consent screen**. @@ -284 +291,0 @@ Google issues a client secret for desktop apps, but it is not treated as confide - 2. Select **Internal** as the user type. This restricts authentication to users within your Google Workspace organization. @@ -286 +292,0 @@ Google issues a client secret for desktop apps, but it is not treated as confide - 3. Configure the following settings: @@ -288,5 +294 @@ Google issues a client secret for desktop apps, but it is not treated as confide -Setting | Value ----|--- -App name | `Amazon Quick Desktop` -User support email | Your admin or support email -Authorized domains | Your organization's domain +###### Note @@ -294 +296 @@ Authorized domains | Your organization's domain - 4. Under **Scopes** , add the following: `openid`, `email`, `profile`. +The PingOne domain varies by region. The examples below use `.com`. Replace the domain with the one for your environment (for example, `.ca`, `.eu`, or `.asia`). @@ -296 +298 @@ Authorized domains | Your organization's domain - 5. Choose **Save and Continue**. +Your OIDC endpoints use the following format. Replace `<ENV_ID>` with your PingOne environment ID. @@ -297,0 +300,6 @@ Authorized domains | Your organization's domain +Field | Value +---|--- +Issuer URL | `https://auth.pingone.com/<ENV_ID>/as` +Authorization endpoint | `https://auth.pingone.com/<ENV_ID>/as/authorize` +Token endpoint | `https://auth.pingone.com/<ENV_ID>/as/token` +JWKS URI | `https://auth.pingone.com/<ENV_ID>/as/jwks` @@ -298,0 +307 @@ Authorized domains | Your organization's domain +## Step 2: Create a Trusted Token Issuer in IAM Identity Center @@ -299,0 +309 @@ Authorized domains | Your organization's domain +###### Note @@ -301 +311 @@ Authorized domains | Your organization's domain -###### To verify authentication settings +This step is only required if your Amazon Quick account uses AWS Identity and Access Management Identity Center for authentication. If your account uses IAM federation, skip this step and proceed to Step 3. @@ -303 +313 @@ Authorized domains | Your organization's domain - 1. Navigate to **APIs & Services → Credentials**. +The TTI tells IAM Identity Center to trust tokens from your IdP and how to map them to IAM Identity Center users. You can create the TTI in the AWS Identity and Access Management Identity Center console or with the AWS CLI. @@ -305 +315 @@ Authorized domains | Your organization's domain - 2. Select the **Amazon Quick Desktop** OAuth client. +For more information, see [Setting up a trusted token issuer](https://docs.aws.amazon.com/singlesignon/latest/userguide/setuptrustedtokenissuer.html) in the _AWS Identity and Access Management Identity Center User Guide_. @@ -307 +317 @@ Authorized domains | Your organization's domain - 3. Confirm that the application type is **Desktop app** and that the Client ID is present. +###### To create the TTI in the IAM Identity Center console @@ -309 +319 @@ Authorized domains | Your organization's domain - 4. Under **Authorized redirect URIs** , confirm that `http://localhost:18080` is listed. If it is missing, add it manually.