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

# Custom OIDC

> Connect any OpenID Connect identity provider to Iru Identity for federated sign-in by registering Iru as a client and mapping claims to user attributes.

When your identity provider speaks the **OpenID Connect (OIDC)** standard but is
not covered by a ready-made template, connect it as a **custom OIDC** connection.
Iru registers as a **client** of your provider: your provider authenticates the
person and returns identity details to Iru, which Iru uses to start the session
and match the person to an Iru user.

<Warning>
  Custom OIDC connections are **coming soon**. Google Workspace, Microsoft Entra
  ID, and custom SAML connections are available today.
</Warning>

<Info>
  Most organizations that use Iru Identity as their identity provider have people
  sign in directly with a passkey or the Iru Access app. Connect an OIDC provider
  when you use Iru Identity as an authentication layer into the Iru platform
  rather than your primary identity provider, or to ease a migration onto Iru
  Identity. See [Federated Authentication](/en/identity/connections/connections-overview).
</Info>

<Note>
  You need administrator access to your Iru tenant, and administrator access to
  your OIDC identity provider, to complete this connection.
</Note>

## Before you begin

<Steps>
  <Step title="Register Iru as an application with your provider">
    In your OIDC provider, create an application (client) for Iru - typically a
    **web** or **confidential** client that uses the authorization code flow. You
    will get a **client ID** and a **client secret** to enter into Iru. The exact
    steps live in your provider's console; follow its current documentation.
  </Step>

  <Step title="Add Iru's redirect URI">
    Your provider needs to know where to send the person back after they sign in.
    Copy the **redirect URI** that Iru shows for this connection and add it to the
    list of allowed redirect URIs on your provider's application.
  </Step>

  <Step title="Confirm the scopes you need">
    Iru requests the standard OpenID Connect **scopes** - `openid`, `profile`, and
    `email` - so your provider returns the person's basic profile and email. Make
    sure your provider is configured to release the claim you plan to match on.
  </Step>

  <Step title="Make sure your people exist in Iru">
    Sign-in through a connection resolves to an existing Iru user. Add or import
    your people first - see [Importing users](/en/identity/directory/importing-users)
    or [Directory Sync](/en/identity/directory/directory-sync).
  </Step>
</Steps>

## Connect an OIDC provider

<Steps>
  <Step title="Add the connection" icon="plus">
    In **Access → Authentication**, add an **authentication method** and choose **OIDC**.
  </Step>

  <Step title="Enter your client details" icon="pen">
    Provide the **client ID** and **client secret** from the application you
    registered with your provider, along with the details Iru needs to reach your
    provider's sign-in endpoints.
  </Step>

  <Step title="Choose the user identifier claim" icon="fingerprint">
    Tell Iru which **claim** in your provider's response identifies the person -
    for example, the subject, email, or preferred username claim. This is the
    value Iru reads to recognize who signed in.
  </Step>

  <Step title="Set user matching" icon="user-check">
    Choose which Iru user value to match that claim against - UPN, username,
    external ID, or a custom attribute. Pick a value that is unique and stable
    for every person. See [user matching](/en/identity/connections/connections-overview#what-you-configure-on-every-identity-provider-connection).
  </Step>

  <Step title="Choose what the connection is used for" icon="list-check">
    Select the connection's **use cases** - **end-user sign-in**, **device
    enrollment**, or both.
  </Step>

  <Step title="Restrict to your domains" icon="at">
    If you want only people in specific email domains to use this connection,
    enable **domain restrictions** and add those domains.
  </Step>

  <Step title="Save and test" icon="circle-check">
    Save the connection, then sign in as a test user to confirm the hand-off:
    your provider authenticates the person, returns the identifying claim, and
    Iru matches them to the right user.
  </Step>
</Steps>

<Tip>
  The **user identifier claim** and your **user matching** choice work together:
  the claim is the value your provider sends, and matching decides which Iru user
  field it must equal. Choose a claim that your provider populates for everyone
  and that lines up with the Iru value you match on.
</Tip>

## How sign-in works once connected

When someone signs in, Iru hands the sign-in off to your OIDC provider. The
provider authenticates the person and returns identity claims, Iru matches them
to an Iru user, and the session continues - then Iru evaluates the app's
[authentication policy](/en/identity/authentication/authentication-policies)
before granting access. For the full picture, see
[System architecture](/en/identity/getting-started/system-architecture).

## Related

<CardGroup cols={2}>
  <Card title="Federated Authentication" icon="plug" href="/en/identity/connections/connections-overview">
    Use cases, domain restrictions, and user matching, explained in one place.
  </Card>

  <Card title="Custom SAML" icon="shield-halved" href="/en/identity/connections/custom-saml">
    Connect an identity provider that uses SAML instead of OpenID Connect.
  </Card>

  <Card title="Google Workspace" icon="google" href="/en/identity/connections/google-workspace">
    Connect Google Workspace with its ready-made template.
  </Card>

  <Card title="Microsoft Entra ID" icon="microsoft" href="/en/identity/connections/microsoft-entra-id">
    Connect Microsoft Entra ID with its ready-made template.
  </Card>
</CardGroup>