> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/setup/configuring-saml-authentication.md).

# Configuring SAML authentication

A **SAML configuration** connects an external identity provider to AILIX so portal sign-in delegates to your corporate SSO. AILIX accepts standard SAML 2.0; the dialog accepts either manual entry or metadata-XML upload. Once a configuration is active and at least one mapping is in place, an additional sign-in button appears on the portal login page.

### Adding a SAML configuration

#### Add a SAML configuration

**Before you start**

* Identity-provider-side metadata: either a metadata XML file (download from your IdP's metadata endpoint) or the equivalent fields by hand (IdP entity ID, signing certificate, single-sign-on URL).
* The X.509 signing certificate from the IdP. AILIX accepts the certificate body with or without the `-----BEGIN CERTIFICATE-----` markers, so paste whichever form your IdP exports.
* A Service Provider Entity ID, the SP-side identifier you and the IdP agree on. AILIX presents it in SAML requests; the IdP matches it to your registered application.
* Login-button text that appears on the AILIX login page next to the email-and-password form. Pick something users recognise, such as *Sign in with Acme SSO*.
* The `authentication.create` permission.

To add a SAML configuration:

1. From the left sidebar, choose **Setup** → **Authentication** → **Add Configuration**. The portal opens the **Add SAML Configuration** modal.
2. Pick **Manual Entry** or **Upload Metadata** at the top of the dialog. Metadata upload is faster because it pre-populates the entity ID and certificate.
3. Enter **Configuration Name** (operator-facing label, required) and **Login Button Text** (appears on the login page, required).
4. Enter **Identity Provider Entity ID** (the IdP-side URI, required) and paste the **X.509 Certificate** (required).
5. Enter **Service Provider Entity ID** (the AILIX-side URI, required; it must match the IdP-side configuration).
6. Open **Mappings** and bind at least one IdP attribute to an AILIX user attribute. Without a mapping, SAML responses arrive but cannot be associated with users.
7. Click **Save Configuration**.

![Figure 18-1. The Add SAML Configuration dialog.](/files/pVao4XoiKTCluSZFWokK)

The numbered callouts in Figure 18-1 are:

1. **Manual Entry** and **Upload Metadata.** IdP-detail entry mode.
2. **Configuration Name.** Internal label. Required.
3. **Login Button Text.** Login-page button label. Required.
4. **Identity Provider Entity ID.** IdP-side URI. Required.
5. **X.509 Certificate.** IdP signing certificate. Required.
6. **Service Provider Entity ID.** AILIX-side URI. Must match the IdP side. Required.
7. **Cancel** and **Save Configuration.** Modal actions.

**Verify**

1. The modal closes and the configuration appears in the **Authentication** list.
2. The configuration's **Mappings** count reads greater than zero. Zero mappings means the configuration is saved but inactive.
3. In an incognito window, the AILIX login page now shows the IdP button (with your **Login Button Text**) alongside the email-and-password form.
4. Clicking the IdP button bounces to the IdP, signs in, and returns the user as authenticated.

{% hint style="success" %}
**Result:** The SAML configuration is active and users can sign in via SSO.
{% endhint %}

{% hint style="danger" %}
**Caution:** A configuration with zero mappings is saved but non-functional. SAML responses arrive at AILIX, but with no attribute mapping the response cannot be tied to a user, and sign-in fails silently from the user's perspective. Always complete **Mappings** before announcing SSO availability.
{% endhint %}

{% hint style="info" %}
**Note:** AILIX's identity-provider integration here is SAML only. This dialog does not configure OIDC or OAuth; other authentication standards live elsewhere or with your AILIX administrator.
{% endhint %}

Related tasks:

* [Inviting and managing users](/api-gateway/setup/inviting-and-managing-users.md#inviting-and-managing-users): provision the users SAML responses will land on, or rely on JIT provisioning if your mappings include it.
* [Working with groups](/api-gateway/setup/working-with-groups.md#working-with-groups): group SSO-arriving users for role assignment.
* [Defining roles and permissions](/api-gateway/setup/defining-roles-and-permissions.md#defining-roles-and-permissions): ensure the groups carry roles so SSO arrivals have permissions on first sign-in.

### Reading the authentication configurations list

#### Browse authentication configurations

To browse:

1. From the left sidebar, choose **Setup** → **Authentication**.
2. Read the configurations table.

![Figure 18-2. The Authentication list.](/files/iM2b397jxGKwguRWH7tO)

**Verify**

1. The URL is `<your-helix-portal-domain>/organization/authentication`.
2. **Add Configuration** is visible at the top right.
3. The **Mappings** count tile reflects the total mappings across configurations.

{% hint style="success" %}
**Result:** A SAML connections inventory, ready to confirm at a glance which are fully configured.
{% endhint %}

Related tasks:

* [Add a SAML configuration](#add-a-saml-configuration): author a new identity-provider connection.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digitalapi.ai/api-gateway/setup/configuring-saml-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.