> ## Documentation Index > Fetch the complete documentation index at: https://docs.heygarth.ai/llms.txt > Use this file to discover all available pages before exploring further. # SSO with Amazon Cognito > Create the Amazon Cognito user pool and app client for G360 and collect their credentials. This page covers **Step 3** (creating the application) for Amazon Cognito. Everything else — entering credentials, testing, enabling SSO, access policy — is the same for all providers and is covered in [SSO Setup](https://docs.heygarth.ai/g360/sso-setup.md). > [!NOTE] > > **Copy the callback URL from G360 first.** Go to **Settings → SSO Settings**, select **Amazon Cognito**, and copy the read-only **Callback URL** from the Identity Provider section. You paste it into Cognito below. > [!WARNING] > > **Amazon Cognito cannot do SCIM provisioning.** Cognito has no outbound provisioning feature, so nothing in it can push user changes to G360. This is a Cognito platform limitation, not a setup gap. See [SCIM provisioning](#scim-is-not-available-with-amazon-cognito) below. G360 connects to a Cognito **user pool**. Cognito also has *identity pools*, which issue AWS credentials — G360 doesn't use them. ## The three settings that cause most failures > [accordion] The app client must have a client secret > > Cognito's **Single-page application** and **Mobile app** client types are public clients with no secret. G360 exchanges the sign-in code on its server, so it needs a **Traditional web application** client. A client's type can't be changed after it's created — if you picked the wrong type, create a new client. > [accordion] The app client must allow the openid, email and profile scopes > > G360 always requests all three scopes. If the app client doesn't allow every one of them, Cognito refuses the request with `invalid_scope` before anyone is asked to sign in. > [accordion] The user pool must have a domain > > Cognito's sign-in and token endpoints live on the pool's domain (`https://.auth..amazoncognito.com`), not on the issuer host. Without a domain, there is nowhere to send users to sign in. ## Create the user pool Console: [AWS Management Console](https://console.aws.amazon.com/cognito/), in the AWS region where you want to keep your users. Select the region from the region picker at the top right before you start. > [!TIP] > > If your organization already has a user pool, you don't need a new one. Skip to [Create the app client](#create-the-app-client) and add a client to the existing pool. Go to **Amazon Cognito → User pools** and click **Create user pool**. ![Amazon Cognito User pools page listing a user pool named G360 with its user pool ID, and the Create user pool button](https://mintcdn.com/na-f445b234/vw78sBVI5uSTqHyc/images/g360/sso/cognito-user-pools.png?fit=max\&auto=format\&n=vw78sBVI5uSTqHyc\&q=85\&s=14948ae17c33170ebe72e7a31283a00c) The User pools list. The User pool ID column shows the ID you use to build the issuer URL. The **Set up resources for your application** page opens. It creates the user pool, its domain and a first app client for G360 in one go. Fill it in section by section. ![Amazon Cognito Set up resources for your application page with the Define your application, Configure options and Add a return URL sections](https://mintcdn.com/na-f445b234/vw78sBVI5uSTqHyc/images/g360/sso/cognito-create-user-pool.png?fit=max\&auto=format\&n=vw78sBVI5uSTqHyc\&q=85\&s=7327b2b797c5f9a94920248682a01ae3) The Set up resources for your application page, where you create the user pool and its first app client. ### Define your application | Field | What to select or enter | | - | - | | **Application type** | **Traditional web application**. Don't choose **Single-page application (SPA)** or **Mobile app** — those create a client without a secret, and G360 needs one | | **Name your application** | Replace the generated name (for example *My web app - l2y3du*) with `G360` or any name you'll recognize | ### Configure options | Field | What to select or enter | | - | - | | **Options for sign-in identifiers** | Check **Email** only. Leave **Phone number** and **Username** unchecked | | **Want to set up social, SAML, or OIDC sign-in?** | Skip this link. You can add federated providers to the pool later | | **Self-registration** | Clear the **Enable self-registration** checkbox — it's checked by default. With it on, anyone on the internet can create an account in your pool. Leave it on only if you want people to sign themselves up | | **Required attributes for sign-up** | Recommended: select `given_name` and `family_name`, so every user has a first and last name for G360 to use. `email` is already required because it's the sign-in identifier | > [!WARNING] > > **Sign-in identifiers and required attributes can't be changed after the pool is created.** If you get them wrong, you have to create a new user pool. Check both before you continue. ### Add a return URL | Field | What to select or enter | | - | - | | **Return URL** | Paste the callback URL you copied from G360, including the trailing slash | Cognito accepts only HTTPS return URLs, except for `http://localhost`, `http://127.0.0.1` and `http://[::1]`. If your G360 instance is served over plain HTTP on any other host, Cognito won't accept the URL. Click **Create user directory**. Cognito creates the user pool, gives it a domain, and creates an app client for G360 with the settings above. On the **User pools** list, note the **User pool ID** — it looks like `us-east-1_AbC123xyz`. You use it to build the [issuer URL](#issuer-url). ## Create the app client The app client is the application that represents G360 inside the user pool. If you created a new user pool above, the wizard already created the app client. Skip to [Configure the app client](#configure-the-app-client). If you're adding G360 to an existing user pool, go to **User pools → (your pool) → Applications → App clients** and click **Create app client**. ![Amazon Cognito App clients and analytics page listing an app client named G360 Local with its client ID, and the Create app client button](https://mintcdn.com/na-f445b234/vw78sBVI5uSTqHyc/images/g360/sso/cognito-app-clients.png?fit=max\&auto=format\&n=vw78sBVI5uSTqHyc\&q=85\&s=5b1e2b01e9b6d1789ed95fc954438d0d) The App clients page for a user pool, with the Create app client button. The **Create app client** page opens. Fill it in section by section. ![Amazon Cognito Create app client page with application type, application name, return URL and the Automatically generate a new client secret toggle](https://mintcdn.com/na-f445b234/vw78sBVI5uSTqHyc/images/g360/sso/cognito-create-app-client.png?fit=max\&auto=format\&n=vw78sBVI5uSTqHyc\&q=85\&s=435061cfcda7d3d18d7ddc2916497765) The Create app client page, with the Define your application, Add a return URL and Client secret configuration sections. ### Define your application | Field | What to select or enter | | - | - | | **Application type** | **Traditional web application**. Don't choose **Single-page application (SPA)** or **Mobile app** — those create a client without a secret, and G360 needs one | | **Name your application** | Replace the generated name (for example *My web app - wffbky*) with `G360` or any name you'll recognize | ### Add a return URL | Field | What to select or enter | | - | - | | **Return URL** | Paste the callback URL you copied from G360, including the trailing slash | ### Client secret configuration | Field | What to select or enter | | - | - | | **Automatically generate a new client secret** | Leave it **on** so Cognito generates a strong secret for you. If you turn it off, you must enter your own custom secret instead | Click **Create app client**. ## Configure the app client Open the client from **App clients**. From **App client information**, copy: * **Client ID** — use the copy icon next to it. * **Client secret** — turn on **Show client secret**, or use the copy icon. If there is no **Client secret** field, the client was created as a public client. Create a new **Traditional web application** client. ![Amazon Cognito app client page showing the app client name, Client ID, masked Client secret with a Show client secret toggle, and tabs for Attribute permissions and Login pages](https://mintcdn.com/na-f445b234/vw78sBVI5uSTqHyc/images/g360/sso/cognito-app-client-info.png?fit=max\&auto=format\&n=vw78sBVI5uSTqHyc\&q=85\&s=e05726498c630047a197b10496ff98bf) App client information, showing the Client ID and the masked Client secret, with the Login pages and Attribute permissions tabs below. Then open the **Login pages** tab and click **Edit** on the managed login configuration: | Setting | Value | | - | - | | **Allowed callback URLs** | Exactly the callback URL from G360, including the trailing slash | | **Allowed sign-out URLs** | Leave empty. G360 doesn't sign users out of Cognito | | **Identity providers** | **Cognito user pool**, plus any federated providers you use | | **OAuth 2.0 grant types** | **Authorization code grant** only | | **OpenID Connect scopes** | **`openid`**, **`email`** and **`profile`** — all three | > [!NOTE] > > Cognito accepts only HTTPS callback URLs, except for `http://localhost`, `http://127.0.0.1` and `http://[::1]`. Under **Attribute permissions**, make sure the client can read `email`, `email_verified`, `given_name` and `family_name`. Read access to all standard attributes is the default. Without these, G360 can't identify the user or fill in their name. ## Make sure user emails are verified G360 uses a person's email address to link their first SSO sign-in to an existing G360 account, or to create a new one. A Cognito user pool can hold email addresses that nobody has verified, so **G360 refuses a first sign-in from a Cognito user whose email isn't verified.** The user sees a message saying their email address hasn't been verified. To avoid this: * **When you create users yourself**, go to **Users → Create user** and check **Mark email address as verified**. * **When users sign themselves up**, keep Cognito's email verification turned on so the address is verified during sign-up. * **When your pool federates another provider** (Google, a SAML provider, another OIDC provider), map that provider's `email` **and** `email_verified` attributes into the pool. A Cognito sign-in with no `email_verified` value at all is treated as unverified. > [!NOTE] > > This check applies only to a person's **first** SSO sign-in. Once their account is linked, G360 recognizes them by Cognito's permanent user ID (`sub`), not by email. New users created by an administrator start with a temporary password. Cognito asks them to choose a new password the first time they sign in, before sending them back to G360. That step is handled entirely by Cognito. ## Issuer URL Build the issuer URL from your region and user pool ID: ```text Issuer URL theme={null} https://cognito-idp..amazonaws.com/ ``` For example, `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_AbC123xyz`. You can enter it in G360 with or without `/.well-known/openid-configuration` at the end. > [!TIP] > > Before entering it in G360, add `/.well-known/openid-configuration` to the issuer URL and open it in a browser. You should see a JSON document whose `authorization_endpoint` and `token_endpoint` are on your pool's `amazoncognito.com` domain. If you get an error, the region or user pool ID is wrong. Cognito has no token endpoint authentication setting to change. It accepts **Client Secret Post**, which is what G360 uses. ## Next: enter the details in G360 You now have the **Client ID**, **Client Secret** and **Issuer URL**. Return to [Step 4 of the setup guide](https://docs.heygarth.ai/g360/sso-setup.md#step-4-enter-the-details-in-g360), select **Amazon Cognito** as the identity provider, then enter the values, test the connection, save, and turn on single sign-on. *** ## SCIM is not available with Amazon Cognito Cognito is an identity provider and a user directory, but it has no outbound provisioning feature. Nothing in Cognito calls G360 when a user is created, changed or disabled. **There is no configuration change, on either side, that enables it.** When the saved identity provider is Amazon Cognito, the **SCIM Provisioning** section in G360 says SCIM isn't supported instead of showing the token form. What to do instead: * Set **New-user provisioning** to **Create automatically on first sign-in** in the [Access Policy](https://docs.heygarth.ai/g360/sso-setup.md#access-policy), so accounts are created when people first sign in. * When someone leaves, disable them in Cognito **and** suspend them in G360 under **Administration → User & Team Management**. > [!WARNING] > > **Disabling or deleting a user in Cognito doesn't end a G360 session they already have.** It only blocks their next SSO sign-in. To cut off access immediately, suspend the user in G360. *** ## Provider-specific errors If Cognito's own page shows an error before you're redirected back to G360, the problem is on Cognito's side. | Message | Meaning | | - | - | | `invalid_scope` | The app client doesn't allow all of `openid`, `email` and `profile` | | `redirect_mismatch` | The callback URL doesn't match exactly, including the trailing slash | | *Login pages unavailable*, or a DNS error | The user pool has no domain | | `invalid_client` (from **Test Connection**) | Wrong client secret, or a public client with no secret | | **Test Connection** can't fetch the discovery document | Wrong region or user pool ID in the issuer URL | Errors that appear **after** you're back in G360: | Message | Meaning | | - | - | | *Your identity provider says the email address on your account has not been verified…* | The Cognito user's email isn't verified, or a federated provider's `email_verified` attribute isn't mapped. See [Make sure user emails are verified](#make-sure-user-emails-are-verified) | | *Your identity provider did not send an email address to G360…* | The `email` scope isn't allowed, or the app client can't read the `email` attribute | For other errors that appear after you're back in G360, see [Troubleshooting](https://docs.heygarth.ai/g360/sso-setup.md#troubleshooting). ### Known behavior * **Signing out of G360 doesn't sign you out of Cognito.** The next **Sign in with SSO** in the same browser goes straight through without asking for a password. Use a private window to sign in as a different user. * **Federated users have a `cognito:username` that isn't an email** (for example `google_1234…`). G360 reads the `email` attribute, so map the upstream provider's email into the pool. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.