> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/docs/onboarding/bring-your-own-idp.md).

# Bring Your Own IdP

Let your customers sign in to an EQUS Wallet with the account they already have with you.

You keep your own login system and your own list of users. The wallet doesn't create accounts - a Holder signs in with the same account they use for everything else of yours. The wallet asks your identity provider to confirm who they are, and then issues its own token for use inside the wallet.

No passwords and no user database reach the platform. Only two claims arrive at sign-in, the user ID and email, and the password is typed on your login page, never ours. 

<figure><picture><source srcset="https://701364325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaucIkpW1i4WOAQC06fj%2Fuploads%2FpEUM1UL9NxnmxyPVuOhM%2FEQUS_Wallet_Sign_In_dark.svg?alt=media&amp;token=4baec340-4022-4bb0-ac7f-906ea63a560f" media="(prefers-color-scheme: dark)"><img src="https://701364325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaucIkpW1i4WOAQC06fj%2Fuploads%2Fvl8fF8grlbbVoj8y5P8v%2FEQUS_Wallet_Sign_In_light.svg?alt=media&amp;token=8a358c00-debb-49af-8c8a-c1e87fb19826" alt=""></picture><figcaption></figcaption></figure>

### Why it matters 💡

Connecting your IdP is what makes a Holder *one of your users* as far as the platform is concerned. That affects two things.

**Signing in to an EQUS Wallet.** Your Holders sign in to the Mobile Wallet with the account they already have with you, and to the [Web Wallet](/docs/wallets/web-wallet.md) too once it's enabled for your Tenant.

**Issuance.** It unlocks the two most seamless issuance journeys:

* [**Auto-issuance**](/docs/issuance/flow-1/auto-issuance.md) - the Offer arrives in the Holder's wallet unprompted.
* [**`pull` tx\_code delivery**](/docs/issuance/flow-1/trigger-by-user-for-equs-wallet-pull-tx_code-delivery.md) - the wallet fetches the `tx_code` itself, so nothing is sent and nothing is typed.

Both rely on matching `userId`. The `sub` your IdP reports at sign-in has to be the same identifier you send when you create the Offer - that match is the whole mechanism. The same applies on [Flow 3](/docs/issuance/flow-3.md). Without it, those journeys aren't available to that Holder, and the `tx_code` has to travel out of band instead.

Presentation doesn't depend on it. Any wallet that holds a credential can present it, and verification checks the credential, not who the Holder is signed in as.

### Requirements 📋

Your login system must support **OpenID Connect** - Google Workspace, Microsoft Entra, Okta and Keycloak all do - and must return two claims in the ID token:

<table><thead><tr><th width="200">Claim</th><th>What it is</th></tr></thead><tbody><tr><td><code>sub</code></td><td>The user ID. This is the <code>userId</code> you use when creating an Offer</td></tr><tr><td><code>email</code></td><td>The Holder's email address</td></tr></tbody></table>

You set this up yourself in the Operator Portal, so you'll need portal access first. See [Registration](/docs/onboarding/registration.md).

### Connect your IdP in the Operator Portal 🔗

The connection is set up under **Settings → External IdP**. It takes a couple of round trips between [the portal](https://portal.us.equs.ai/) and your IdP's admin console, so keep both open.

<figure><img src="https://701364325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaucIkpW1i4WOAQC06fj%2Fuploads%2FlYIUqtm3zAIxS4h9jMxU%2Fimage.png?alt=media&amp;token=b5594443-3622-4b8f-baeb-f41f92b84ae7" alt=""><figcaption></figcaption></figure>

#### 1. Register a client in your IdP

Your IdP won't accept sign-in requests from an application it doesn't know, so register a client for the platform in your IdP's admin console:

| Setting             | Value                                             |
| ------------------- | ------------------------------------------------- |
| Client type         | Confidential, with client authentication enabled  |
| Grant type          | Authorization Code                                |
| Scopes              | `openid`, `email`, `profile`                      |
| Valid redirect URIs | The sign-in and sign-out URIs shown in the portal |

Registering the client gives you a **client ID** and a **client secret**.

#### 2. Enter your IdP details and connect

Back in the portal, fill in:

* **Discovery URL** - your IdP's configuration document, the standard link ending in `/.well-known/openid-configuration`. It supplies every other technical URL automatically.
* **Client ID** and **Client secret** from the client you registered. The secret is stored securely and isn't shown again after you save.

Select **Connect**. The platform checks the details and sets up its side of the connection automatically, so there's nothing to send to EQUS. If something is wrong, such as a discovery URL that can't be reached or a client secret that's rejected, the portal shows the reason and the connection isn't switched on.

Once connected, your Holders can sign in to the EQUS Mobile Wallet with their account from your IdP. The [Web Wallet](/docs/wallets/web-wallet.md) uses the same connection once it's enabled for your Tenant; it's off by default.

### Manage the connection 🛠️

After you connect, the tab shows your discovery URL, your client ID and a masked client secret. From there you can:

* **Rotate** the client secret, entering a new one without going through the whole form.
* **Edit** the connection. The platform sets it up again with the new details, and keeps the previous working configuration where possible if that fails.
* **Delete** the connection.

{% hint style="danger" %}
**Deleting the connection stops your Holders from signing in with their accounts from your IdP.**
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.toolkit.equs.ai/docs/onboarding/bring-your-own-idp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.