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

# SAML applications

> Reference for SAML application settings in Iru Identity: provider details, request and response handling, signing, attribute mapping, and session length.

A **SAML application** lets users sign in to a service that supports SAML
single sign-on, with Iru acting as the **identity provider (IdP)**. Iru gives the
service the provider-facing details it needs, signs the response and assertion it
sends, and maps your users' profile attributes into that assertion.

You edit a SAML app's configuration in a **draft** and then set it as the current
version. See [Applications overview](https://docs.iru.com/en/identity/applications/applications-overview.md)
for the version model. Below is a field-by-field reference for every setting,
grouped exactly as the editor presents them.

> [!NOTE]
>
> Most services need only a handful of these settings, typically the ACS URL,
> the Service Provider Entity ID, and the mapping. The defaults are chosen to work
> with common service providers; change the rest only when your service's
> documentation calls for it.

## Protocol details: what Iru gives the service provider

Open the application's **Protocol details** to copy the values your service
provider needs to trust Iru. These are generated by Iru.

| Detail | What it is |
| - | - |
| **Metadata URL** | A single document describing Iru's SAML settings for this app. Many services configure everything from this URL; you can also view or download the metadata file. |
| **IdP Entity ID** | Iru's identifier as the identity provider for this app. |
| **Single Sign On Service** | The URL the service provider sends authentication requests to (and where IdP-initiated sign-on begins). |
| **IdP Signing Certificate** | The certificate the service uses to verify that a response genuinely came from Iru. Its subject, expiry, and fingerprint are shown, and you can copy or download it. |

> [!TIP]
>
> If the service can import metadata, point it at the **Metadata URL** (or upload
> the downloaded file). It carries the entity ID, sign-on URL, and signing
> certificate together, so there is less to enter by hand.

## Provider details: what you tell Iru about the service

| Setting | What it does |
| - | - |
| **ACS URL** | The Assertion Consumer Service URL, the destination Iru sends the SAML response to. Required, and must be a valid `https` URL. |
| **Service Provider Entity ID** | The service provider's own identifier. Iru uses it as the default audience and (optionally) to validate the request issuer. |
| **Unsolicited authentication** | Whether the service supports **IdP-initiated** sign-on (the user starts from Iru). Set **Supported** if the service accepts a response it didn't request; otherwise set **Unsupported**. |
| **Alternative authentication URL** | Shown when unsolicited authentication is **Unsupported**: the URL Iru sends users to so the service can start the sign-in itself (service-provider-initiated). |

> [accordion] Request: how Iru handles authentication requests
>
> These settings govern the **AuthnRequest** that a service provider sends to start
> sign-on.
>
> ### Validate issuer
>
> How strictly Iru checks the **Issuer** in an incoming request.
>
> | Option | What it does |
> | - | - |
> | **Must match Service Provider Entity ID** | The request's issuer must equal the Service Provider Entity ID you entered above. |
> | **Must match custom value** | The issuer must equal a **Custom value** you specify (use this when the service's issuer differs from its entity ID). |
> | **Ignore** | Do not validate the issuer. |
>
> ### Authentication request restriction
>
> Controls **whether the request must be signed** and **which ACS URL** Iru replies
> to. "Follow" uses the ACS URL from the request; "pinned" always uses the ACS URL
> configured in **Provider details**.
>
> | Option | Request must be signed? | Response is sent to |
> | - | - | - |
> | **Any request and follow** | No | The ACS URL in the request |
> | **Any request and pinned** | No | The configured ACS URL |
> | **Signed request and follow** | Yes | The ACS URL in the request |
> | **Signed request and pinned** | Yes | The configured ACS URL |
>
> > [!WARNING]
> >
> > **Pinned** is the safer choice: it ignores any ACS URL supplied in the request,
> > so a tampered request cannot redirect a response elsewhere. Prefer **Signed
> > request and pinned** when the service supports signing its requests.
>
> When you choose a **Signed request** option, you also set how Iru verifies that
> signature:
>
> | Setting | What it does |
> | - | - |
> | **Allowed signing algorithms** | The request signature algorithms Iru will accept: any of `RSA-SHA1`, `RSA-SHA256`, `RSA-SHA384`, `RSA-SHA512`. Select the ones your service uses; avoid `RSA-SHA1` unless required. |
> | **Allowed digest algorithms** | The request digest algorithms Iru will accept: any of `SHA1`, `SHA256`, `SHA384`, `SHA512`. |
> | **Signing Certificate** | The certificate Iru uses to verify the service's signed requests. Upload the service provider's request-signing certificate. |

> [accordion] Response: how Iru builds and sends the assertion
>
> ### Delivery and identifiers
>
> | Setting | What it does |
> | - | - |
> | **HTTP Method** | How the SAML response is delivered: **HTTP-POST** (an auto-submitting form, the common choice) or **HTTP-REDIRECT**. |
> | **IdP Entity ID** | The issuer Iru declares in the response. Leave on **Use default** (shown in Protocol details), or choose **Specify custom** to declare a different **Custom IdP Entity ID**. |
> | **Audience** | Who the assertion is intended for. **Use default** sends the Service Provider Entity ID; choose **Specify custom** to send a different **Custom Audience**. |
> | **Recipient** | The recipient declared in the assertion. **Use default** uses the ACS URL (the destination); choose **Specify custom** to send a different **Custom Recipient**. |
> | **Fallback relay value** | The RelayState Iru uses when the service didn't supply one, typically where the user should land in the app. |
> | **Error action** | What happens when a sign-on can't complete: **Iru** shows an Iru error page, or **Protocol** returns the error to the service provider to handle. |
>
> ### Signing
>
> | Setting | What it does |
> | - | - |
> | **Signing method** | Which parts of the message Iru signs: **Response**, **Assertion**, or **Both - Response and Assertion**. Match what the service requires. |
> | **Signing algorithm** | The signature algorithm Iru signs with: `RSA-SHA1`, `RSA-SHA256`, `RSA-SHA384`, or `RSA-SHA512`. `RSA-SHA256` suits most services. |
> | **Digest algorithm** | The digest algorithm used in the signature: `SHA1`, `SHA256`, `SHA384`, or `SHA512`. |
>
> Iru signs with its own **IdP Signing Certificate** (the one shown in Protocol
> details), so there is no signing certificate to upload here.
>
> ### Encrypt assertions
>
> | Setting | What it does |
> | - | - |
> | **Encrypt assertions** | **Unencrypted** (default) or **Encrypted**. Turn on only if the service requires encrypted assertions. |
> | **Use the Request signing certificate** | When encrypting, reuse the service's request-signing certificate as the encryption certificate instead of uploading a separate one. (Requires a signing certificate to be configured in the **Request** section.) |
> | **Encryption Certificate** | The service provider's certificate Iru encrypts the assertion to, when you are not reusing the request-signing certificate. |
> | **Encryption algorithm** | The content-encryption algorithm: `AES-128-GCM`, `AES-192-GCM`, `AES-256-GCM`, `AES-128-CBC`, `AES-192-CBC`, or `AES-256-CBC`. Use what the service expects (a GCM option is a good default). |
> | **Key transport algorithm** | How the encryption key is protected: `RSA-OAEP` or `RSA-PKCS1-v1.5`. |
>
> ### Advanced
>
> | Setting | What it does |
> | - | - |
> | **Use namespace prefixes** | Adds explicit XML namespace prefixes (`saml2p`, `saml2`, `ds`, `xenc`) to the response. Enable it if the service's SAML parser requires prefixed elements. |

> [accordion] Mapping: the NameID and attributes Iru sends
>
> Open the application's **mapping** to control the identity in the assertion. It
> has two parts: the **Subject** (the NameID) and any additional **attributes**.
>
> ### Subject (NameID)
>
> The Subject is the primary identifier for the signed-in user. By default it is
> drawn from the user's `user.username`; you can change the value it draws from and
> choose a **NameID format**:
>
> | NameID format | Use when the service expects… |
> | - | - |
> | **Email** | An email address as the identifier. |
> | **Persistent** | A stable, opaque identifier that stays the same across sessions. |
> | **Transient** | A temporary identifier that may change each session. |
> | **Unspecified** | No particular format. |
>
> ### Attributes
>
> Add each attribute the service needs in the assertion. For every attribute you set:
>
> * A **Name:** the attribute name the service provider expects.
> * A **value:** the profile attribute or expression it draws from (for example,
>   `user.primaryEmail.email` or a combination of fields).
> * An **attribute name format:** **Unspecified**, **URI**, or **Basic**.
> * Whether it is **enabled**.
>
> A live **preview** renders the assertion that will be produced, so you can confirm
> its shape before publishing.
>
> > [!WARNING]
> >
> > `Subject` is reserved as the NameID and cannot be reused as a custom attribute
> > name.

> [accordion] Session management
>
> The application's default session length starts at **60 minutes** for apps
> you create without a template. When a user's roles set a session length, Iru
> uses the longest one instead. Iru uses the application default when none of
> the user's roles sets a length, or when the role assertion method is
> **None**. See [Roles](https://docs.iru.com/en/identity/applications/roles.md).
>
> | Setting | What it does |
> | - | - |
> | **Session Length Supported** | **Supported** populates the assertion's `notOnOrAfter` (session expiry) from the length below; **Unsupported** omits it. |
> | **Default session length (minutes)** | The application default written into the assertion. Defaults to **60**. Valid on the app as **10** to **2880** minutes. |

## Certificates at a glance

A SAML app involves up to three certificates:

> [accordion] IdP signing certificate (Iru's own)
>
> Iru signs the response and/or assertion with its own certificate, shown in
> **Protocol details**. The service uses it to confirm the message came from Iru
> and was not altered. Nothing to upload.

> [accordion] Request signing certificate (the service's)
>
> Upload the service provider's certificate so Iru can verify the **signed
> authentication requests** it sends. Configured in the **Request** section, and
> only needed when you require signed requests.

> [accordion] Encryption certificate (the service's)
>
> The service provider's certificate Iru **encrypts the assertion** to, used only
> when **Encrypt assertions** is on. You can reuse the request-signing
> certificate instead of uploading a separate one.

## Publish, assign, and activate

**1. Set the draft as current**

Publish your draft so it becomes the live configuration.

**2. Assign access**

Assign the groups that should have the app. See
[Assigning access](https://docs.iru.com/en/identity/applications/assigning-access.md).

**3. Activate**

Make the app active so assigned users can sign in.

**4. Test the sign-on**

Sign in as a test user from the app dashboard to confirm the experience,
and use the mapping **preview** to check the assertion.

## Where to go next

> [card] [Assigning access](https://docs.iru.com/en/identity/applications/assigning-access.md)
>
> Grant the app to users and groups, and shape app roles.

> [card] [Provisioning](https://docs.iru.com/en/identity/applications/provisioning.md)
>
> Create and remove accounts in the app automatically as access changes.

> [card] [OIDC applications](https://docs.iru.com/en/identity/applications/oidc-applications.md)
>
> Configure an app that uses OpenID Connect instead of SAML.

> [card] [Applications overview](https://docs.iru.com/en/identity/applications/applications-overview.md)
>
> Review protocols and the draft-to-current version model.

### Related Articles

> [card] [Applications overview](https://docs.iru.com/en/identity/applications/applications-overview.md)
>
> Connect the services your users sign in to: how Iru acts as their identity provider over SAML or OIDC, and how you add and version an app.

> [card] [Roles](https://docs.iru.com/en/identity/applications/roles.md)
>
> Create roles for an application in Iru Identity, assign them to groups, and set session length per role.

> [card] [Assigning access](https://docs.iru.com/en/identity/applications/assigning-access.md)
>
> Grant an application to groups in Iru Identity, review effective users, and choose whether assigned users see the app on their dashboard.

> [card] [Provisioning](https://docs.iru.com/en/identity/applications/provisioning.md)
>
> Automatically create, update, and remove accounts in your apps with SCIM as access changes, plus group-linked provisioning, manual syncs, and history.


## Related topics

- [Applications overview](https://docs.iru.com/en/identity/applications/applications-overview.md)
- [Application mapping](https://docs.iru.com/en/identity/applications/application-mapping.md)
- [Application templates](https://docs.iru.com/en/identity/applications/application-templates.md)
