Configure enterprise single sign-on (SSO) for Amazon Quick on desktop using OpenID Connect (OIDC) and AWS IAM Identity Center, so your users sign in with their corporate credentials.
Checked against official AWS documentation on 17 Oct 2026. The desktop app is generally available on macOS and Windows (since 9 Sep 2026).
Amazon Quick Desktop enterprise sign-in requires an OIDC provider. The AWS-documented path is your existing IdP (Microsoft Entra ID, Google Workspace, Okta, or Ping Identity). The Amazon Cognito path is a field workaround.
Your organization already has an OIDC-compatible identity provider. AWS publishes setup guides for Microsoft Entra ID, Google Workspace, Okta, and Ping Identity (PingFederate and PingOne). This is the documented path — pick your identity provider to jump to its setup steps:
Google Workspace: see the Google Workspace note in Step 1.
Or review the overview first (the AWS guide has four steps: IdP app, extension access, extension, distribute):
Register a public OIDC client (authorization code with PKCE).
Not one of the four steps in the AWS desktop guide. Only if your design needs it (the Cognito workaround creates one).
Register the OIDC endpoints in the Amazon Quick administration console, then create the extension.
Test Continue with SSO and roll out to users.
offline_access scope, which the Cognito + IAM Identity Center sign-in path does not accept, so a small proxy removes that scope before the request reaches the identity provider. Test it in your own account before you rely on it.Use this path when you don't have an existing IdP: Amazon Quick with local users (no IAM Identity Center), or IAM Identity Center managing users directly with no external OIDC provider. You deploy Amazon Cognito as the OIDC provider using a sample CDK stack.
offline_access from the /authorize request — so the Authorization Endpoint must point to the proxy, not the Cognito hosted UI. Cognito does not use the offline_access scope to control refresh tokens; it returns a refresh token for the authorization code grant (Cognito token endpoint).The proxy has a single job: intercept the /authorize request, strip the unsupported offline_access scope (and optionally force identity_provider=IdentityCenter), then send the user on to Cognito. There are two ways to implement it — pick based on how much logic you need and how you plan to protect it.
The Authorization Endpoint points to a CloudFront path. A CloudFront Function on viewer-request rewrites the query string and returns the 302 at the edge — the Cognito origin is never contacted for /authorize.
AuthEndpoint = CloudFront URL · edge · no cold start
The Authorization Endpoint points to an API Gateway HTTP API. Each request invokes a Lambda that rewrites the query string and returns a 302 to the Cognito hosted UI. This is what the ready-made CDK stack deploys.
AuthEndpoint = API Gateway URL · full runtime · regional
| Dimension | Option 1 — API Gateway + Lambda | Option 2 — CloudFront Function |
|---|---|---|
| Where code runs | Regional (one Region) | Edge (global PoPs) |
| Latency | Lambda cold start + regional round trip | Sub-millisecond, no cold start |
Origin contacted for /authorize | Yes — request reaches the endpoint | No — 302 returned at the edge |
| Host-header / origin-request-policy | Must be handled | Not a concern (origin not used) |
| Moving parts | API Gateway + Lambda + IAM role | One CloudFront distribution + one JS function |
| Compute limits | Full runtime — call AWS APIs, crypto, async | Very limited: ≤10 KB code, ~1 ms CPU, no network calls, JS subset (cloudfront-js-2.0) |
| Logging | Full CloudWatch Logs | Limited |
| Cost per request | Lambda + API Gateway requests | Lower — CloudFront Function ~$0.10 / million |
| Best for | Logic beyond a simple rewrite (lookups, calling other APIs) | A pure 302 query-string rewrite (this exact use case) |
/authorize is proxied — Token, JWKS and Issuer endpoints point to Cognito directly (the token exchange is a POST and must reach Cognito).offline_access — Cognito issues them from the app client's refresh-token expiration, independent of the scope.identity_provider=IdentityCenter to the Cognito authorization request. If this design uses a Trusted Token Issuer, it is for trusted identity propagation and token exchange, not for routing the sign-in.| Option 1 (API Gateway HTTP API) | Option 2 (CloudFront) | |
|---|---|---|
| Attach WAF directly? | No — HTTP API unsupported | Yes — on the distribution |
| Web ACL scope / Region | Need a REST API (REGIONAL) or front it with CloudFront | CLOUDFRONT scope — create in us-east-1 |
| Evaluation order | WAF → API Gateway → Lambda | WAF runs before the CloudFront Function |
Options for the HTTP-API path: front it with CloudFront and attach WAF there; switch to a REST API to use WAF and resource policies; or keep the HTTP API and use IAM authorization, a JWT/Lambda authorizer, and throttling (HTTP APIs do not support resource policies).
AWSManagedRulesCommonRuleSet, AWSManagedRulesAmazonIpReputationList, plus a rate-based rule.offline_access scopeAWS account with an active Amazon Quick subscription (Enterprise account; home Region must be one where the desktop app is available); Node.js 18+, AWS CDK CLI, Python 3.12+ with boto3, and configured AWS credentials; the desktop application installed.
API Gateway HTTP APIs do not support resource policies. To restrict the authorize endpoint by source IP, front the HTTP API with CloudFront and AWS WAF, or switch to a REST API and use AWS WAF or a resource policy.
Retrieve stack outputs:
Copy users into the Cognito User Pool (the script reads the pool ID and temporary password from the stack and prompts before creating each user).
In the Amazon Quick administration console, choose Manage account → Permissions → Extension access and enter the stack outputs. Then, in the Amazon Quick console left navigation, choose Extensions (under More if you don't see it) and create the extension.
| Field | Stack output |
|---|---|
| Trusted Token Issuer ARN (IDC only) | TtiArn |
| Aud claim | ClientId |
| Issuer URL | IssuerUrl |
| Authorization Endpoint | AuthEndpoint (API Gateway) |
| Token Endpoint | TokenEndpoint |
| JWKS URI | JwksUri |
| Client ID | ClientId |
Launch the desktop app and choose Continue with SSO. Sign in with your username or email and the temporary password — you'll be prompted to set a new password on first login.
sync_users.py script is a manual stop-gap. For production, use an organization-approved provisioning process and test the full user lifecycle end to end.| Issue | Cause / fix |
|---|---|
redirect_mismatch | Callback URL must be http://localhost:18080 (the stack sets this automatically). |
invalid_scope | Authorization Endpoint must point to the API Gateway (AuthEndpoint), not the Cognito hosted UI. |
| User not found | The email in Cognito must exactly match the user's email in Amazon Quick. |
| Stale config after changes | Clear cached profiles in ~/.quickwork/ (see below). |
~/.quickwork cache (team observation): AWS documents ~/.quickwork/ (macOS) and %USERPROFILE%\.quickwork\ (Windows) as the folder for local settings. The team found the OIDC config cached in ~/.quickwork/profiles.json, surviving reinstalls. After reconfiguring extension access, remove the cached enterprise profile entry so the app picks up the new values.This Cognito approach is a field workaround for environments without an IdP and is not an AWS-documented setup. For deployments with an existing IdP, use the I have an IdP tab. For a fully deployed CloudFront-based variant, see Reference deployment — Cognito + Identity Center via CloudFront below. See also the public enterprise setup guide.
Applies to: Enterprise Edition (if you use a Free or Plus account, this setup does not apply) · Intended audience: System administrators. Source: AWS Documentation
The Amazon Quick desktop application uses the OIDC protocol to authenticate users. When a user chooses Continue with SSO, a browser window opens to Amazon Quick, which identifies your configured identity provider and redirects to your IdP's authorization endpoint. To identify the IdP, the browser needs an active Amazon Quick web session; if there is none, the browser asks the user to sign in to Amazon Quick first. The app then exchanges the 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 — the email in your IdP must exactly match the user's email in Amazon Quick.
User chooses Continue with SSO in the desktop app.
Browser opens your IdP authorization endpoint.
Code is exchanged for tokens (no client secret).
Quick validates the token and matches the email.
RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512). HMAC (HS256/HS384/HS512) and unsigned tokens are rejected.
Verify the following before you begin.
| Requirement | Detail |
|---|---|
| AWS account & subscription | An AWS account with an active Amazon Quick subscription (Enterprise account). The home region (identity region) must be a supported Region where the desktop app is available (see the Region note above). |
| Administrator access | Administrator access to your Amazon Quick account. |
| IdP permissions | Access to your identity provider with permissions to create OIDC application registrations. |
| Network access | In restricted networks, allow the required Amazon Quick and identity provider domains. See Network access and required domains. |
| IAM Identity Center (optional) | The AWS desktop guide does not include a Trusted Token Issuer (TTI) step. The Cognito workaround on this page creates one. See Identity Center below. |
Register a public OIDC client (authorization code flow with PKCE, no client secret — except Google Workspace, see below). Grant offline_access (Entra ID, Okta, Ping) so the IdP issues refresh tokens; without it, users must re-authenticate frequently.
Redirect URI: http://localhost:18080
Client type: Public / Native (no secret)
Grant types: Authorization Code + Refresh Token
PKCE: Required (S256)
Scopes: openid email profile offline_access
Entra ID: grant offline_access.
Okta: enable Refresh Token grant + offline_access.
Ping: enable Refresh Token grant + offline_access. For PingFederate also enable Return ID Token On Refresh Grant.
Google Workspace: no extra scope; Quick adds access_type=offline automatically.
openid, email, profile. Endpoints: Issuer https://accounts.google.com; Authorization https://accounts.google.com/o/oauth2/v2/auth; Token https://oauth2.googleapis.com/token?client_secret=<CLIENT_SECRET> (the client secret is appended as a query parameter); JWKS https://www.googleapis.com/oauth2/v3/certs. Full steps: Google Workspace guide.
Azure portal → Microsoft Entra ID → App registrations → New registration. Name: Amazon Quick Desktop; Supported account types: Single tenant; Redirect URI platform: Public client/native (mobile & desktop); Redirect URI: http://localhost:18080. Choose Register.
On the Overview page, note the Application (client) ID and Directory (tenant) ID.
Add Microsoft Graph → Delegated permissions: openid, email, profile, offline_access. Grant admin consent if required.
Under Advanced settings, leave Allow public client flows set to No. Verify http://localhost:18080 is listed under Mobile and desktop applications. Save. (Entra ID enforces PKCE automatically for public clients.)
Token configuration → Add optional claim → token type ID → email. Each user must also have the Mail attribute filled in their Entra ID profile; the UPN alone is not enough.
The Issuer URL must include /v2.0 (do not use the Authority URL from the Endpoints panel). If your app has custom signing keys from claims mapping, append ?appid=<CLIENT_ID> to the JWKS URI.
| Field | Value (replace <TENANT_ID>) |
|---|---|
| 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 Admin Console → Applications → Applications → Create App Integration. Sign-in method: OIDC - OpenID Connect; Application type: Native Application.
Name: Amazon Quick Desktop; Grant type: Authorization Code + Refresh Token; Sign-in redirect URI: http://localhost:18080; assign to the appropriate users/groups. Save and note the Client ID.
On the General tab confirm: application type Native, client authentication None (public client), PKCE Required, and http://localhost:18080 under LOGIN. Quick requests openid, profile, email, offline_access at sign-in.
| Field | Value (replace <OKTA_DOMAIN>, e.g. your-org.okta.com — not the -admin subdomain) |
|---|---|
| Issuer URL | https://<OKTA_DOMAIN> |
| Authorization endpoint | https://<OKTA_DOMAIN>/oauth2/v1/authorize |
| Token endpoint | https://<OKTA_DOMAIN>/oauth2/v1/token |
| JWKS URI | https://<OKTA_DOMAIN>/oauth2/v1/keys |
Applications → OAuth → Clients → Add Client. Enter a unique Client ID; Name: Amazon Quick Desktop; Client Authentication: None; Redirection URI: http://localhost:18080.
Allowed Grant Types: Authorization Code + Refresh Token; select Require PKCE; grant scopes openid, email, profile, offline_access. Save and note the Client ID.
Applications → OAuth → OpenID Connect Policy Management. Select Return ID Token On Refresh Grant, and verify the email claim is in the Attribute Contract and mapped for both initial auth and refresh grants.
| Field | Value (replace <PINGFEDERATE_HOST>) |
|---|---|
| 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 admin console → Applications → +. Name: Amazon Quick Desktop; Application Type: Native. Save.
Response Type: Code; Grant Type: Authorization Code + Refresh Token; PKCE Enforcement: S256; Redirect URIs: http://localhost:18080; Token Endpoint Authentication Method: None. Save.
Resources tab (separate from the Configuration tab): add openid, email, profile, offline_access — PingOne grants only openid by default, and skipping this causes "User info request failed (HTTP 401)". Attribute Mappings: map email to the user's email. Toggle the app to Enabled. Note the Client ID and Environment ID. For JWKS use /as/jwks, not /.well-known/jwks.json.
| Field | Value (replace <ENV_ID>; domain varies by region) |
|---|---|
| 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 |
Not part of the AWS desktop setup guide, which has four steps (IdP app, extension access, extension, distribute) for every identity type, including IAM Identity Center. The Cognito workaround on this page creates a TTI; add one only if your design needs it. A Trusted Token Issuer (TTI) lets IAM Identity Center trust OIDC tokens from an external issuer (trusted identity propagation). Source: AWS Documentation
In the IAM Identity Center console, choose Settings, then the Authentication tab. Under Trusted token issuers, choose Create trusted token issuer.
For Issuer URL, specify the IdP's OIDC discovery URL up until and without .well-known/openid-configuration. It must match the iss claim in the issued tokens. The discovery endpoint must be reachable on ports 80 and 443 only.
Under Map attributes, choose an Identity provider attribute (a claim in the token, e.g. email) and the corresponding IAM Identity Center attribute used to look up a single user in the Identity Center directory.
Enter a Trusted token issuer name, then choose Create trusted token issuer. Notify the application administrator so they can select it and configure token exchange (including the Aud claim value for the receiving AWS service).
Register the OIDC endpoints from Step 1 so the desktop application can authenticate. Both parts are required.
Sign in to the Amazon Quick administration console and choose Manage account → under Permissions, Extension access → Add extension access. Under Select Service, select Amazon Quick (Desktop application for Quick) and choose Next.
Fill in the fields from the table below with values from Step 1, then choose Add.
In the Amazon Quick console left navigation, choose Extensions (choose More if you don't see it) → Add extension. Select the Desktop application for Quick extension access you created, choose Next, then Create. Without this step users see "Enterprise sign-in for Quick Desktop has not been configured for this account." It is a one-time, account-level action.
| Field | Value |
|---|---|
| Name | A name for this extension access (for example, QuickDesktop-access); alphanumeric characters and hyphens only, no spaces |
| Description | (Optional) A description |
| Issuer URL | The exact OIDC issuer URL from Step 1, including any required path suffix |
| Authorization Endpoint | The OIDC authorization endpoint from Step 1 |
| Token Endpoint | The OIDC token endpoint from Step 1 |
| JWKS URI | The JSON Web Key Set URI from Step 1 |
| Client ID | The OIDC client identifier from Step 1 |
Confirm the configuration, then roll out to your users.
In the Amazon Quick console choose Extensions, select the Quick Desktop extension, open the more options menu (...) and choose Download for Windows or Download for Mac. Install the app, choose Continue with SSO on the sign-in screen, optionally select your AWS Region (or Dynamic), and authenticate with your corporate credentials.
If sign-in fails, verify the Step 3 values against the Step 1 endpoints. If a value is wrong, delete the extension access under Permissions → Extension access and repeat Step 3.
Direct your users to the installation guide. Users choose Continue with SSO; no per-user configuration is required. For silent fleet installs see Managed deployment configuration (single-user Windows silent install: .\Amazon-Quick-Setup.exe /S).
offline_access scope, which this Cognito + IAM Identity Center path does not accept, so the CloudFront Function removes it before the request reaches the identity provider. For the documented path, use your IdP's AWS guide (Entra ID, Google Workspace, Okta, Ping Identity).A tested variant of the Cognito path. Instead of an API Gateway + Lambda proxy, a single CloudFront Function returns a 302 at the edge — it strips offline_access and forces federation through IAM Identity Center. The origin is never hit for /authorize, so there are no Host-header or origin-request-policy concerns. All identifying values below are masked.
Authorize requests are rewritten at the CloudFront edge; Token / JWKS / Issuer go straight to Cognito.
quick-desktop-authz-strip (runtime cloudfront-js-2.0, associated on viewer-request, stage LIVE).us-east-1_XXXXXXXXX with hosted-UI domain and a public PKCE app client (no secret; authorization-code + PKCE; callback http://localhost:18080; allowed scopes openid email profile — offline_access is intentionally not an allowed scope).IdentityCenter (SAML) — Cognito federates up to IAM Identity Center as the upstream IdP.OIDC_JWT) that trusts the Cognito issuer + the Amazon Quick (quicksight) application.offline_access + force IdC)| Field | Value |
|---|---|
| Authorization Endpoint | https://dXXXXXXXXXXXXX.cloudfront.net/oauth2/authorize — CloudFront |
| Token Endpoint | https://us-east-1XXXXXXXXX.auth.us-east-1.amazoncognito.com/oauth2/token — Cognito (direct) |
| Issuer URL | https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX — Cognito (direct) |
| JWKS URI | .../us-east-1_XXXXXXXXX/.well-known/jwks.json — Cognito (direct) |
| Aud claim / Client ID | <PUBLIC_CLIENT_ID> |
→ offline_access removed, IAM Identity Center federation forced, and code_challenge (PKCE) preserved.
FunctionGeneratedResponse), so the Cognito origin is never contacted for /authorize — no Host-header rewriting, no origin-request-policy needed, sub-millisecond, and no Lambda cold start.offline_access: Cognito does not use the offline_access scope to control refresh tokens; it returns one for the authorization code grant, and you set the lifetime with the app client's refresh-token validity (Cognito token endpoint). Stripping the scope avoids invalid_scope without shortening sessions.identity_provider=IdentityCenter routes every sign-in through IAM Identity Center (no direct local Cognito users). Add a separate path if you need a break-glass local admin.us-east-1) and an AWS WAF Web ACL to the distribution. The default *.cloudfront.net domain is fine for testing.Common issues and resolutions (from the AWS troubleshooting guide). Tip: you can export application logs from the sign-in screen.
| Symptom | Resolution |
|---|---|
redirect_mismatch error | Verify the redirect URI in your IdP is exactly http://localhost:18080 and configured as a public client / native platform. |
| User not found after sign-in | The token must contain the email claim (Entra ID: add the email optional claim and fill the user's Mail attribute) and it must exactly match a provisioned Amazon Quick user. Email matching is case-sensitive. |
| Token validation failure | Verify the issuer URL in the extension access matches the IdP's OIDC issuer exactly, and that the IdP signs ID tokens with a supported asymmetric algorithm (not HMAC). |
| Invalid issuer (Entra ID) | The Issuer URL must include /v2.0. Delete the extension access and recreate it with the correct value. |
| Enterprise sign-in not configured for this account | The extension access exists but the extension was not created. Create it on the Extensions page (Step 3). |
| User info request failed (HTTP 504) | Transient backend timeout. Sign in to Amazon Quick in the web browser first, then retry desktop sign-in; check network access to the required domains. |
| Access blocked: app not verified (Google Workspace) | Set the OAuth consent screen User type to Internal. |
| Consent / permission errors (Entra ID) | Grant admin consent for the required API permissions in the Azure portal (app registration → API permissions). |
| Session expires frequently | Ensure the IdP issues refresh tokens: Entra ID needs offline_access; Okta and Ping need the Refresh Token grant and offline_access; Google is handled automatically. For PingFederate, also enable Return ID Token On Refresh Grant. |
| User info request failed (HTTP 401) (PingOne) | Add email, profile, offline_access on the application's Resources tab. |
| Token validation failure with PingOne JWKS | Use the /as/jwks path, not /.well-known/jwks.json. |
| Application not enabled (PingOne) | If auth fails before reaching the login page, verify the application toggle is set to Enabled. |
| Missing email claim after refresh (PingFederate) | Verify the email claim is in the OIDC policy Attribute Contract and mapped for both initial auth and refresh grants. |
Official AWS documentation used on this page.
Setting up Amazon Quick on desktop for enterprise deployments
Troubleshooting enterprise sign-in
Getting started (desktop)
Security, privacy, and architecture
Desktop app GA (What's New, Sep 2026)
Cognito token endpoint (offline_access)
API Gateway: REST vs HTTP APIs
AWS WAF protected resources
CloudFront quotas (Functions)
CloudFront pay-as-you-go pricing