# Setting up Amazon Quick on desktop for enterprise deployments
<a name="desktop-enterprise-setup"></a>


|  | 
| --- |
|    Applies to: Enterprise Edition and Standard Edition  | 


|  | 
| --- |
|    Intended audience:  System administrators  | 

To use Amazon Quick on desktop for enterprise deployments, administrators must configure enterprise single sign-on (SSO) so that users in the organization can sign in with their corporate credentials. This setup connects your organization's OpenID Connect (OIDC) compatible identity provider (IdP) to Amazon Quick.

**Note**  
If you are using a Free or Plus account, this section does not apply to you. Continue to [Getting started](getting-started-desktop.md).

The setup involves the following steps, in order:

1. Create an OIDC application in your IdP.

1. Create a Trusted Token Issuer (TTI) in IAM Identity Center (only required for accounts that use IAM Identity Center for authentication).

1. Configure the extension access in the Amazon Quick management console.

1. Distribute the desktop application to your users.

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.

## How enterprise sign-in works
<a name="desktop-enterprise-how-it-works"></a>

The Amazon Quick desktop application uses the OIDC protocol to authenticate users. When a user chooses **Enterprise login**, the application opens a browser window and redirects to your IdP's authorization endpoint. The application then exchanges the resulting authorization code for tokens using Proof Key for Code Exchange (PKCE).

Amazon Quick validates the token and maps the user to an identity in your account. For accounts that use IAM Identity Center, the TTI maps the `email` claim in the OIDC token to the `emails.value` attribute in the identity store. For accounts that use IAM federation, Amazon Quick maps the user by email directly. In both cases, the email address in your IdP must exactly match the email address of the user in Amazon Quick.

## Prerequisites
<a name="desktop-enterprise-prerequisites"></a>

Before you begin, verify that you have the following:
+ An AWS account with an active Amazon Quick subscription that uses IAM Identity Center or IAM federation for authentication. The Amazon Quick account's home region (identity region) must be US East (N. Virginia) (us-east-1).
+ Administrator access to your Amazon Quick account.
+ Access to your IdP with permissions to create OIDC application registrations.

**Important**  
The Amazon Quick account's home region (identity region) must be US East (N. Virginia) (us-east-1). All inference for the desktop application also uses this Region. While Amazon Quick on the web can be used in other Regions, the desktop application connects to us-east-1 for both authentication and inference.

## Step 1: Create an OIDC application in your identity provider
<a name="desktop-enterprise-step1"></a>

Register a public OIDC client application in your IdP. The Amazon Quick desktop application uses this client to authenticate users through the authorization code flow with PKCE. No client secret is required.

The desktop application requires refresh tokens to maintain long-lived sessions. How refresh tokens are configured depends on your IdP:
+ **Microsoft Entra ID** – The `offline_access` scope must be granted. Without it, users must re-authenticate frequently.
+ **Okta** – The Refresh Token grant type must be enabled on the application, and the `offline_access` scope must be granted.
+ **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.

Choose the instructions for your identity provider.

### Microsoft Entra ID
<a name="desktop-enterprise-entra-id"></a>

For detailed instructions, see [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in the Microsoft Entra documentation.

**To create the Entra ID app registration**

1. In the Azure portal, navigate to **Microsoft Entra ID → App registrations → New registration**.

1. Configure the following settings:    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/quick/latest/userguide/desktop-enterprise-setup.html)

1. Choose **Register**.

1. On the **Overview** page, note the **Application (client) ID** and **Directory (tenant) ID**. You need these values in later steps.

This is a public client registration. PKCE is enforced automatically by Entra ID for public clients.

**To configure API permissions**

1. In the app registration, navigate to **API permissions → Add a permission → Microsoft Graph → Delegated permissions**.

1. Add the following permissions: `openid`, `email`, `profile`, `offline_access`.

1. Choose **Add permissions**.

1. If your organization requires it, choose **Grant admin consent for [your organization]**.

**To configure authentication settings**

1. In the app registration, navigate to **Authentication**.

1. Under **Advanced settings**, set **Allow public client flows** to **Yes**.

1. Verify that `http://localhost:18080` is listed under **Mobile and desktop applications**.

1. Choose **Save**.

Your OIDC endpoints use the following format. Replace `<TENANT_ID>` with your Directory (tenant) ID.


| Field | Value | 
| --- | --- | 
| Issuer URL | https://login.microsoftonline.com/<TENANT\_ID>/v2.0 | 
| Authorization endpoint | https://login.microsoftonline.com/<TENANT\_ID>/oauth2/v2.0/authorize | 
| Token endpoint | https://login.microsoftonline.com/<TENANT\_ID>/oauth2/v2.0/token | 
| JWKS URI | https://login.microsoftonline.com/<TENANT\_ID>/discovery/v2.0/keys | 

### Okta
<a name="desktop-enterprise-okta"></a>

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.

**To create the Okta OIDC Native Application**

1. In the Okta Admin Console, navigate to **Applications → Applications → Create App Integration**.

1. Select **OIDC - OpenID Connect** as the sign-in method.

1. Select **Native Application** as the application type, then choose **Next**.

1. Configure the following settings:    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/quick/latest/userguide/desktop-enterprise-setup.html)

1. Choose **Save**.

1. On the **General** tab, note the **Client ID**.

PKCE (S256) is enforced automatically by Okta for native applications.

**To configure scopes**

1. In the Okta Admin Console, navigate to **Security → API → Authorization Servers** and select your authorization server (for example, **default**).

1. On the **Scopes** tab, verify that the following scopes are enabled: `openid`, `email`, `profile`, `offline_access`.

1. On the **Access Policies** tab, verify that the policy assigned to this application allows the `Authorization Code` and `Refresh Token` grant types.

**To verify authentication settings**

1. In the app integration, go to the **General** tab.

1. Under **General Settings**, confirm that the application type is **Native**, client authentication is **None** (public client), and PKCE is **Required**.

1. Under **LOGIN**, confirm that `http://localhost:18080` is listed as a redirect URI.

1. Choose **Save** if you made any changes.

Your OIDC endpoints use the following format. Replace `<OKTA_DOMAIN>` with your Okta domain (for example, `your-org.okta.com`).


| Field | Value | 
| --- | --- | 
| Issuer URL | https://<OKTA\_DOMAIN>/oauth2/default | 
| Authorization endpoint | https://<OKTA\_DOMAIN>/oauth2/default/v1/authorize | 
| Token endpoint | https://<OKTA\_DOMAIN>/oauth2/default/v1/token | 
| JWKS URI | https://<OKTA\_DOMAIN>/oauth2/default/v1/keys | 

### Ping Identity
<a name="desktop-enterprise-ping-identity"></a>

Choose the instructions for your Ping Identity product.

#### PingFederate
<a name="desktop-enterprise-pingfederate"></a>

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.

**To create the PingFederate OIDC client**

1. In the PingFederate administrative console, go to **Applications → OAuth → Clients**, and choose **Add Client**.

1. In the **Client ID** field, enter a unique identifier for this client.

1. In the **Name** field, enter `Amazon Quick Desktop`.

1. For **Client Authentication**, select **None**.

1. In the **Redirection URI** section, enter `http://localhost:18080` and choose **Add**.

1. In the **Allowed Grant Types** list, select **Authorization Code** and **Refresh Token**.

1. Select the **Require Proof Key for Code Exchange (PKCE)** checkbox.

1. Under **Common Scopes**, grant the following: `openid`, `email`, `profile`, `offline_access`.

1. Choose **Save**.

1. Note the **Client ID**. You need this value in later steps.

**To configure the OIDC policy**

1. In the PingFederate administrative console, go to **Applications → OAuth → OpenID Connect Policy Management**.

1. Select the OIDC policy associated with this client, or choose **Add Policy** to create one.

1. 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.

1. 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.

1. Choose **Save**.

Your OIDC endpoints use the following format. Replace `<PINGFEDERATE_HOST>` with your PingFederate server hostname.


| Field | Value | 
| --- | --- | 
| 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 | 

#### PingOne
<a name="desktop-enterprise-pingone"></a>

For detailed instructions, see [Editing an application – Native](https://docs.pingidentity.com/pingone/applications/p1_edit_application_native.html) in the Ping Identity documentation.

**To create the PingOne OIDC native application**

1. In the PingOne admin console, go to **Applications → Applications** and choose the **\+** icon.

1. Enter `Amazon Quick Desktop` as the application name.

1. In the **Application Type** section, select **Native**, then choose **Save**.

1. On the **Configuration** tab, choose **Edit** and configure the following settings:    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/quick/latest/userguide/desktop-enterprise-setup.html)

1. Choose **Save**.

1. On the **Resources** tab, add the following scopes: `openid`, `email`, `profile`, `offline_access`.

1. On the **Attribute Mappings** tab, verify that the `email` attribute is mapped to the user's email address.

1. Toggle the application to **Enabled**.

1. Note the **Client ID** and **Environment ID** from the **Configuration** tab.

**Note**  
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 `<ENV_ID>` with your PingOne environment ID.


| 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 | 

## Step 2: Create a Trusted Token Issuer in IAM Identity Center
<a name="desktop-enterprise-step2"></a>

**Note**  
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.

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.

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*.

**To create the TTI in the IAM Identity Center console**

1. Open the [AWS Identity and Access Management Identity Center console](https://console.aws.amazon.com/singlesignon).

1. Choose **Settings**.

1. On the **Settings** page, choose the **Authentication** tab.

1. Under **Trusted token issuers**, choose **Create trusted token issuer**.

1. On the **Set up an external IdP to issue trusted tokens** page, under **Trusted token issuer details**, configure the following:    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/quick/latest/userguide/desktop-enterprise-setup.html)

1. Under **Map attributes**, configure the attribute mapping that IAM Identity Center uses to look up users:    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/quick/latest/userguide/desktop-enterprise-setup.html)
**Important**  
The identity provider attribute must match a claim that your IdP includes in the token, and the IAM Identity Center attribute must uniquely identify the user in your identity store. The most common mapping is `email` → `emails.value`, but your organization may use a different attribute such as `sub` or a custom claim. The value in the token claim must exactly match the value of the corresponding attribute in IAM Identity Center.

1. Choose **Create trusted token issuer**.

1. Note the **Trusted token issuer ARN**. You need it in the next step.

Alternatively, to create the TTI with the AWS CLI, run the following command. Replace `<IDC_INSTANCE_ARN>` with your IAM Identity Center instance Amazon Resource Name (ARN) and `<ISSUER_URL>` with the issuer URL from Step 1.

```
aws sso-admin create-trusted-token-issuer \
  --instance-arn <IDC_INSTANCE_ARN> \
  --name "AmazonQuickDesktop" \
  --trusted-token-issuer-type OIDC_JWT \
  --trusted-token-issuer-configuration '{
    "OidcJwtConfiguration": {
      "IssuerUrl": "<ISSUER_URL>",
      "ClaimAttributePath": "email",
      "IdentityStoreAttributePath": "emails.value",
      "JwksRetrievalOption": "OPEN_ID_DISCOVERY"
    }
  }'
```

Note the `TrustedTokenIssuerArn` from the output. You need it in the next step.

The following table lists the issuer URL for each identity provider.


| Identity provider | Issuer URL | 
| --- | --- | 
| Microsoft Entra ID | https://login.microsoftonline.com/<TENANT\_ID>/v2.0 | 
| Okta | https://<OKTA\_DOMAIN>/oauth2/default | 
| PingFederate | https://<PINGFEDERATE\_HOST> | 
| PingOne | https://auth.pingone.com/<ENV\_ID>/as | 

## Step 3: Configure the extension access in the Amazon Quick management console
<a name="desktop-enterprise-step3"></a>

**To add the extension access**

1. Sign in to the Amazon Quick management console.

1. Under **Permissions**, choose **Extension access**.

1. Choose **Add extension access**.

1. (Optional) If your account uses IAM Identity Center, the **Trusted Token Issuer Setup** step appears. Enter the following:    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/quick/latest/userguide/desktop-enterprise-setup.html)

   This step does not appear for accounts that use IAM federation.

1. Select the **Desktop application for Quick** extension and choose **Next**.

1. Enter the Amazon Quick extension details:    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/quick/latest/userguide/desktop-enterprise-setup.html)

1. Choose **Add**.
**Important**  
Verify that all values are correct before choosing **Add**. The extension access configuration cannot be edited after creation. If any value is incorrect, you must delete the extension access and create a new one.

**To create the extension**

1. In the Amazon Quick console, in the left navigation under **Connect apps and data**, choose **Extensions**.

1. Choose **Add extension**.

1. Select the **Desktop application for Quick** extension access you previously created. Choose **Next**.

1. Choose **Create**.

## Step 4: Download and distribute the desktop application
<a name="desktop-enterprise-step4"></a>

After you configure enterprise sign-in, verify the setup by downloading and installing the desktop application yourself. Choose **Enterprise login** on the sign-in screen and authenticate with your corporate credentials to confirm the configuration is working. For download and installation steps, see [Getting started](getting-started-desktop.md).

If the sign-in fails, verify the values you entered in Step 3 against the OIDC endpoints from Step 1. If any value is incorrect, delete the extension access under **Permissions → Extension access**, and repeat Step 3 with the correct values.

After you verify the setup, direct your users to [Getting started](getting-started-desktop.md) for download, installation, and sign-in instructions.

## Troubleshooting
<a name="desktop-enterprise-troubleshooting"></a>

`redirect_mismatch` error  
Verify that the redirect URI in your IdP is exactly `http://localhost:18080` and is configured as a public client or native platform.

User not found after sign-in  
The email in the IdP token must exactly match the email of a user in IAM Identity Center. Verify that the user is provisioned and that the email addresses are identical in both systems.

Token validation failure  
Verify that the issuer URL in the TTI matches the issuer URL in your IdP's OIDC configuration exactly.

Consent or permission errors (Microsoft Entra ID)  
Grant admin consent for the required API permissions in the Azure portal. Navigate to the app registration's **API permissions** page and choose **Grant admin consent for [your organization]**.

Session expires frequently  
Verify that your IdP is configured to issue refresh tokens. For Microsoft Entra ID, the `offline_access` scope is required. For Okta, the Refresh Token grant type must be enabled and the `offline_access` scope must be granted. For Ping Identity, the Refresh Token grant type must be enabled and the `offline_access` scope must be granted. For PingFederate, also verify that **Return ID Token On Refresh Grant** is selected in the OIDC policy.

`invalid_scope` error (Okta)  
Verify that `offline_access` is enabled on your authorization server. Navigate to **Security → API → Authorization Servers → default → Scopes** and confirm the scope is present. Also verify that the access policy for the application allows the Refresh Token grant type.

Application not enabled (PingOne)  
If authentication fails immediately without reaching the PingOne login page, verify that the application toggle is set to **Enabled** in the PingOne admin console.

Missing email claim after refresh (PingFederate)  
Verify that the `email` claim is included in the OIDC policy **Attribute Contract** and mapped to the correct user attribute. The mapping must produce the `email` claim for both initial authentication and refresh token grants.