> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loqate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On (SSO) for Your Loqate Account

> Connect your own identity provider to your Loqate Account so your team signs in with your company credentials, and let your IT administrators set it up themselves.

<Note>
  Single Sign-On is available to Enterprise customers only, and needs to be enabled on your Organisation before you can configure it. Please contact your account manager to have it activated. If you do not know who your account manager is, please contact the support team at [support@loqate.com](mailto:support@loqate.com).
</Note>

## What is Single Sign-On?

Single Sign-On (SSO) lets your users sign in to your Loqate Account using your own identity provider (IdP), such as Okta, Microsoft Entra ID or Google Workspace, instead of receiving a magic link or code by email.

Once SSO is active, anyone signing in with an email address on one of your verified domains is redirected to your identity provider to authenticate. Your IdP decides whether they get in, which means access to your Loqate Account follows the same rules as the rest of your business systems.

SSO is self-administered. Once your account manager has enabled it, your own IT administrators complete the whole setup from within your Loqate Account, so there's no need to raise a ticket with us or wait on our team to configure anything for you.

## Why use SSO?

* **Central control of access** : Users are granted and revoked access in your identity provider. When someone leaves your business and is disabled there, they lose access to your Loqate Account too.
* **Your own security policies** : Multi-factor authentication, conditional access, password rules and session policies are all enforced by your IdP.
* **A simpler sign-in** : Your team signs in with the credentials they already use every day.
* **Set up on your own schedule** : Your IT team configures, tests and activates the connection when it suits them.

<Note>
  SSO controls how users sign in to your Loqate Account. It does not change how your integrations authenticate. [Loqate's APIs](/api-reference/introduction/) continue to use your API keys. See [API Security](/loqate-basics/api-security) for how to secure those.
</Note>

## Before you begin

Make sure the following are in place before you start, as you'll need all of them to complete the setup in one sitting.

* **SSO enabled on your Organisation** : Your account manager arranges this. You won't see the options described below until it's done.
* **The Admin role** : Only users with the Admin role in your Organisation can set up or change an SSO connection. Members cannot. See [Managing Your Account](/loqate-basics/managing-account#organisation-roles) for more on roles.
* **Administrative access to your identity provider** : You'll need to be able to create and configure an application in your IdP.
* **The ability to publish DNS records** : You'll need to add a `TXT` record to the DNS for each domain you want to use, to prove you own it. If your DNS is managed by another team, involve them early, as this is usually the slowest part of the process.

## Terminology

Your Loqate **Account** has a corresponding **Organisation**, which groups your **users** together and lets a team of people access the same account. SSO is configured against your Organisation, and applies to every user who signs in with an email address on a verified domain.

If you're new to Organisations and user management, read [Managing Your Account](/loqate-basics/managing-account) first.

## Setting up your connection

### 1. Open the Security tab

Sign in to your Loqate Account, click your company name in the top-right corner of the account section and select **Your Team**. Then open the **Security** tab.

If you can't see the **Security** tab, either SSO hasn't been enabled on your Organisation yet, or you don't have the Admin role.

### 2. Claim and verify a domain

Start by telling us which email domains belong to your business, for example `yourcompany.com`. You can add more than one.

For each domain you add, we'll generate a DNS `TXT` record. Ask whoever manages your DNS to publish that record on the domain, then come back and verify it.

<Note>
  DNS changes can take anything from a few minutes to several hours to propagate. If verification fails on the first attempt, wait a while and try again before assuming something is wrong.
</Note>

You must have at least one verified domain before you can continue. Verification also stops anyone else claiming a domain that isn't theirs.

### 3. Choose your identity provider

Next, choose the provider you want to connect. The following are supported:

| Protocol | Provider                               |
| -------- | -------------------------------------- |
| SAML     | Okta Workforce                         |
| SAML     | Microsoft Entra ID (formerly Azure AD) |
| SAML     | Google Workspace                       |
| SAML     | Custom SAML Provider                   |
| OIDC     | OIDC Provider                          |

If your provider isn't listed by name but supports SAML 2.0 or OpenID Connect, use **Custom SAML Provider** or **OIDC Provider**.

<Warning>
  Switching an existing connection to a different provider removes the current connection, and you'll need to start the configuration again from the beginning. Choose the right provider before you invest time in configuring it.
</Warning>

### 4. Configure the connection

The details you exchange with your IdP depend on which protocol you're using.

<Tabs>
  <Tab title="SAML">
    Setting up a SAML connection involves swapping details in both directions: ours go into your IdP, and your IdP's come back to us.

    **In your identity provider**, create a new SAML application and enter the values we show you in the **Security** tab:

    * **Assertion Consumer Service (ACS) URL** : where your IdP sends its response after authenticating a user.
    * **Entity ID** : identifies your Loqate Account to your IdP. Some providers label this the audience or audience URI.

    Then configure the attribute statements your IdP sends to us:

    | Attribute   | Required | Description              |
    | ----------- | -------- | ------------------------ |
    | `mail`      | Yes      | The user's email address |
    | `firstName` | No       | The user's first name    |
    | `lastName`  | No       | The user's last name     |

    The `mail` attribute is essential. It's how we match the person signing in to your Organisation, and the domain of that address must be one you've verified. Mapping `firstName` and `lastName` is optional, but it makes your user list much easier to read.

    Finally, assign the users or groups in your IdP who should have access to your Loqate Account.

    **Back in the Security tab**, supply your IdP's details. Most providers publish a **Metadata URL**, which is the quickest and most reliable option, as it keeps things such as certificate rotations up to date automatically. If your provider doesn't offer one, you can enter the details manually instead:

    * **SSO URL** : your IdP's sign-in endpoint.
    * **Entity ID (Issuer)** : identifies your IdP to us.
    * **Signing certificate** : used to verify that responses genuinely came from your IdP.
  </Tab>

  <Tab title="OIDC">
    Setting up an OpenID Connect connection takes three steps.

    First, **register the redirect URI**. Copy the **Authorized redirect URI** shown in the **Security** tab and add it to the application you've created in your IdP. Your IdP will refuse the sign-in request if this doesn't match exactly.

    Second, **provide your IdP's endpoints**. If your provider exposes a **Discovery Endpoint** (often ending `/.well-known/openid-configuration`), enter that and we'll read the rest of the configuration from it. Otherwise, enter the endpoints manually:

    * **Authorization URL**
    * **Token URL**
    * **User Info URL**

    Third, **enter your credentials**: the **Client ID** and **Client Secret** from the application in your IdP. Treat the client secret like any other credential: don't share it outside your IT team, and store it somewhere secure.

    Make sure your IdP returns the following claims in the ID token:

    | Claim         | Required | Description                              |
    | ------------- | -------- | ---------------------------------------- |
    | `sub`         | Yes      | A stable, unique identifier for the user |
    | `email`       | Yes      | The user's email address                 |
    | `given_name`  | No       | The user's first name                    |
    | `family_name` | No       | The user's last name                     |

    As with SAML, the email address must be on a domain you've verified.
  </Tab>
</Tabs>

### 5. Test the connection

Before activating the connection, use the test sign-in in the **Security** tab to confirm the connection works from end to end.

The test runs against your live configuration but doesn't affect anyone else, so your team continues to sign in as normal while you're checking. If the test fails, the most common causes are a mismatched redirect URI or ACS URL, a missing email attribute or claim, or the test user not being assigned to the application in your IdP.

<Warning>
  We'd strongly recommend you don't skip this step.
</Warning>

### 6. Activate the connection

Once the connection is active, any user whose email address is on one of your verified domains must authenticate through your identity provider to reach your Loqate Account. They'll no longer receive a magic link or code by email.

<Warning>
  Make sure the users who need access are assigned to the application in your identity provider **before** you activate the connection. If they aren't, they'll be locked out of your Loqate Account until you assign them.
</Warning>

## Managing an active connection

Changes you make to an active connection take effect immediately, which means an incorrect value can stop your team signing in. You'll see a warning in the **Security** tab reminding you of this before you save.

If you need to make significant changes, such as rotating a client secret, moving to a new IdP application, or changing endpoints, it's worth planning them for a quieter period, and keeping a Loqate Admin available who can help if something goes wrong.

If you get locked out of your account, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/), who will be happy to help.

<h2>Frequently Asked Questions</h2>

<p className="text-muted" />

<AccordionGroup>
  <Accordion title="How do I get SSO enabled on my account?">
    Single Sign-On is available to Enterprise customers only. Please speak to your account manager, who will arrange for it to be enabled on your Organisation. If you're not sure who your account manager is, contact the support team at [support@loqate.com](mailto:support@loqate.com).

    Once it's enabled, you'll see a **Security** tab in the **Your Team** area, and you can complete the rest of the setup yourself.
  </Accordion>

  <Accordion title="Who in my business can set up SSO?">
    Only users with the **Admin** role in your Organisation. Members can sign in and use the platform, but cannot configure SSO. See [Managing Your Account](/loqate-basics/managing-account#organisation-roles) for more on roles.

    In practice you'll usually want an Admin and someone with access to both your identity provider and your DNS records. That might be the same person, or it might be two or three people working together.
  </Accordion>

  <Accordion title="Why do I need to verify my domain?">
    Verifying a domain proves that your business controls the email addresses you're claiming. Without it, someone could set up a connection that captured sign-ins for a domain that wasn't theirs.

    You verify a domain by publishing a `TXT` record we generate in that domain's DNS. You need at least one verified domain before you can configure a connection.
  </Accordion>

  <Accordion title="Can I use more than one domain?">
    Yes. Add and verify each domain you want to cover. This is useful if your business uses several email domains, or if you've acquired companies that still use their original domains.
  </Accordion>

  <Accordion title="What happens to users who aren't on a verified domain?">
    They continue to sign in as they do today, using their email address. SSO only applies to users whose email address is on one of your verified domains.

    This is worth bearing in mind if you have contractors or partners in your Organisation on external domains.
  </Accordion>

  <Accordion title="Does SSO change how my API keys work?">
    No. SSO governs how people sign in to your Loqate Account. Your integrations continue to authenticate with API keys exactly as before. To secure those, see [API Security](/loqate-basics/api-security).
  </Accordion>

  <Accordion title="Can I change identity provider later?">
    Yes, but switching an existing connection to a different provider removes the current connection and you'll need to configure the new one from scratch. Plan for a short window where your team may need to sign in another way, and test the new connection before activating it.
  </Accordion>

  <Accordion title="My test sign-in failed. What should I check?">
    Start with the details that have to match exactly between Loqate and your identity provider: the **Authorized redirect URI** for OIDC, or the **Assertion Consumer Service (ACS) URL** and **Entity ID** for SAML. A trailing slash or a copied-in space is enough to break it.

    Then check that your IdP is sending the user's email address (the `mail` attribute for SAML, or the `email` claim for OIDC), that the address is on a verified domain, and that the test user is assigned to the application in your IdP.

    If you're still stuck, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/).
  </Accordion>

  <Accordion title="Nobody can sign in since we activated the connection. What now?">
    The most likely cause is that your users haven't been assigned to the application in your identity provider. Check the assignments there first.

    If you can still reach the **Security** tab, you can deactivate the connection to restore email sign-in while you investigate. If you can't get in at all, please contact our [support team](https://www.loqate.com/en-gb/contact/customer-support/), who will be happy to help.
  </Accordion>
</AccordionGroup>