> ## 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 SAML

> Connect any SAML 2.0 identity provider to Iru Identity for federated sign-in, with Iru acting as the service provider and mapping assertions to user attributes.

When your identity provider speaks the **SAML** standard but is not covered by a
ready-made template, connect it as a **custom SAML** connection. In this setup
Iru acts as the **service provider (SP)**: your provider authenticates the
person, then sends Iru a signed SAML response that Iru trusts to start the
session.

<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 a SAML 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 SAML identity provider, to complete this connection. Setting up SAML means
  exchanging a few values in both directions - this page walks through both
  sides.
</Note>

## How the trust is established

```mermaid theme={null}
sequenceDiagram
  participant Admin as You
  participant Iru as Iru (service provider)
  participant Idp as Your SAML provider

  Iru-->>Admin: Provide SP metadata, entity ID, and ACS URL
  Admin->>Idp: Register Iru as a service provider
  Idp-->>Admin: Provide entity ID, sign-in URL, signing certificate
  Admin->>Iru: Enter the provider's details and upload its certificate
  Note over Iru,Idp: Trust established - sign-in can be tested
```

Iru and your provider each need to trust the other. Iru gives you the details
your provider needs to recognize Iru, and your provider gives you the details Iru
needs to verify its responses.

## Before you begin

<Steps>
  <Step title="Gather Iru's service provider details">
    From the connection in Iru, collect the values your provider will ask for -
    Iru's **SP metadata**, its **entity ID**, and its **ACS URL** (the address
    where your provider sends its SAML response). Many providers can import this
    in one step from the metadata.
  </Step>

  <Step title="Gather your provider's details">
    From your SAML provider, collect its **entity ID**, its **single sign-on
    URL**, and its **signing certificate** (the certificate Iru uses to verify
    the provider's signed responses).
  </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 a SAML provider

<Steps>
  <Step title="Add the connection" icon="plus">
    In **Access → Authentication**, add an **authentication method** and choose **SAML**.
    Iru generates its service provider details for this connection.
  </Step>

  <Step title="Register Iru with your provider" icon="upload">
    In your SAML provider, create a new application (relying party) for Iru and
    supply Iru's **entity ID** and **ACS URL**, or import Iru's **SP metadata** if
    your provider supports it. Configure the provider to release the **NameID** and
    any **attributes** you intend to match on. The exact relying-party screens live
    in your provider's console; follow its current documentation.
  </Step>

  <Step title="Enter your provider's details in Iru" icon="pen">
    Back in Iru, enter your provider's **entity ID** and **single sign-on URL**,
    then upload your provider's **signing certificate** so Iru can verify the
    SAML responses it receives.
  </Step>

  <Step title="Set user matching" icon="user-check">
    Tell Iru which value in the SAML response identifies the person - the
    **Subject** (NameID) or a named **attribute** the provider sends - and which
    Iru user value to match it against (UPN, username, external ID, or a custom
    attribute). 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 round trip:
    Iru sends the request, your provider authenticates the person, and Iru
    matches them to the right user.
  </Step>
</Steps>

<Tip>
  Iru can also present a **request-signing certificate** so your provider can
  verify that sign-in requests genuinely came from Iru. If your provider expects
  signed requests, share Iru's request-signing certificate from the connection
  and enable signed requests on the provider side.
</Tip>

## Keeping the connection healthy

<AccordionGroup>
  <Accordion title="Certificates expire" icon="certificate">
    The signing certificate you upload from your provider has an expiry date.
    When your provider rotates its certificate, upload the new one in Iru so
    sign-in keeps working. Plan the swap before the old certificate expires.
  </Accordion>

  <Accordion title="Sign-in lands on the wrong person - or no one" icon="user-xmark">
    This almost always traces back to **user matching**. Confirm the value your
    provider sends (the Subject or attribute) is present and unique for everyone,
    and that it matches the Iru user value you selected.
  </Accordion>
</AccordionGroup>

## 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 OIDC" icon="key" href="/en/identity/connections/custom-oidc">
    Connect an identity provider that uses OpenID Connect instead of SAML.
  </Card>

  <Card title="System architecture" icon="sitemap" href="/en/identity/getting-started/system-architecture">
    See how federated sign-in fits into the wider identity layer.
  </Card>

  <Card title="Sign-in experience" icon="arrow-right-to-bracket" href="/en/identity/authentication/sign-in-experience">
    Shape what people see when they sign in.
  </Card>
</CardGroup>