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

# External Identity Providers

> Learn how to bring your own identity provider into your Fiskil environment

If you already have an Identity Provider (IdP) and it supports OpenID Connect (OIDC) then you can integrate
it with Fiskil to provide the same, robust authentication standards as you do in other applications.

<Note>
  It is optional to configure an external Identity Provider. Fiskil can use a [built-in](/docs/build/end-user-authentication#authentication) authentication experience
  facilitated by your resource server.
</Note>

Integrating an IdP with Fiskil means the [Customer Search](/docs/build/end-user-authentication#post-/auth/v1/customer/search)
step is managed by your IdP. You don't need to build a Customer Search endpoint on your resource
server. This saves you time and ensures a consistent authentication experience for your users.

<Warning>
  If you operate within a regulated open data ecosystem such as CDR, be sure to confirm your IdP can comply with
  the authentication standards of the ecosystem.
</Warning>

## Connecting Your IdP to Fiskil

Setting up your IdP with Fiskil involves adding Fiskil as an OIDC client for your IdP.

### Add Fiskil as a client with your IdP

1. Set the redirect URLs for Fiskil to `https://<your-data-provider-domain>/idp/auth/login` and `https://<your-data-provider-domain>/idp/auth/consent`
   * You can get your data provider domain from the [Domains](https://console.fiskil.com/data-holder/settings/domains) settings menu in the Fiskil console
   * You may want to wait until you've configured a custom domain before adding your IdP so you don't need to repeat the process when the data provider domain changes
2. Record the client ID and client secret created for Fiskil
3. Note the base URL of your IdP's OpenID Connect service

<Note>
  When adding Fiskil as a client to your IdP, refer to the documentation for your IdP's OpenID
  Connect Service.
</Note>

### Add your IdP in the Fiskil Console

1. Navigate to the Identity Provider settings menu in the [Fiskil Console](https://console.fiskil.com/data-holder/settings/external-idp)
2. Click "Edit"
3. Provide the Client ID, Client Secret, and Base URL from step 1
4. Click "Save".

<Note>
  Fiskil depends on the OpenID Discovery document served by your IdP. If you get an error message about your "OpenID Connect Discovery endpoint",
  confirm that there is a `/.well-known/openid-configuration` endpoint on the base URL that you provided.
</Note>

### Test

Test an authorization flow using our testing tools. Refer to the [Testing](/docs/testing) documentation for your integration type for more details on how
to complete a test authorization.

## Limitations

* Fiskil only works with OpenID Connect for federated identity. Your IdP must support it.
* The ID Token returned by your IdP must contain a `sub` claim that is **unique** and **stable** for the authenticated user. It must not change between consents.
* The `sub` claim in the ID token must work as an ID to look up user data for the authenticated user. It will be used as the `{customerId}` path parameter in requests to your resource server.
* If your IdP is behind a firewall you'll need to allow access from Fiskil's Data Provider IP addresses. You can get these in the Data Provider [Resource Server settings](https://console.fiskil.com/data-holder/settings/resource-server)

If you have any questions about whether we can support your IdP please reach out to us and we can discuss this with you.