> ## 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](/en/identity/applications/applications-overview)
for the version model. Below is a field-by-field reference for every setting,
grouped exactly as the editor presents them.
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. |
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). |
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 |
**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. |
### 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. |
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.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.
`Subject` is reserved as the NameID and cannot be reused as a custom attribute
name.
| 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 session length written into the assertion. Must be between **10 and 2880** minutes; defaults to **480** (8 hours). |
## Certificates at a glance
A SAML app involves up to three certificates:
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.
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.
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
Publish your draft so it becomes the live configuration.
Assign the groups that should have the app. See
[Assigning access](/en/identity/applications/assigning-access).
Make the app active so assigned users can sign in.
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
Grant the app to users and groups, and shape app roles.
Create and remove accounts in the app automatically as access changes.
Configure an app that uses OpenID Connect instead of SAML.
Review protocols and the draft-to-current version model.