---
title: SSO / SAML
description: Set up Single Sign-On via SAML so your users authenticate with your company's own identity provider instead of individual Unico credentials.
canonical: https://developer.unico.io/dual-api/developers/api-reference/sso-saml
locale: en
generated_by: markdown-export
---

Single Sign-On (SSO) lets the people in your organization log in to Unico's products using the
same corporate credentials they already use internally, instead of a separate Unico username and
password.

:::note[This is not the server-to-server flow]
This page covers **human login** via your company's identity provider. If you're looking for
back-end, machine-to-machine authentication for API calls, see [Authentication](./authentication)
instead.
:::

Authentication management stays under your company's control, directly in your own identity and
access management system — there's no need to open a support request with Unico to create or
disable individual user logins.

SSO is implemented through **SAML** (Security Assertion Markup Language), a standard protocol for
securely exchanging authentication and authorization data between an Identity Provider and a
Service Provider.

### SAML components

| Component | Role |
|---|---|
| **Identity Provider (IdP)** | The service that authenticates the user — your corporate directory (e.g. Active Directory) or an external identity service (e.g. Okta, Microsoft Entra ID). |
| **Service Provider (SP)** | The application the user is trying to reach. In this case, Unico's authentication platform, which authenticates and authorizes users across Unico's product portals. |
| **Assertions** | The XML messages that carry authentication and authorization data between the IdP and the SP. |
| **SAML Metadata** | An XML document describing how the IdP and the SP should communicate securely (endpoints, certificates). |

:::info
SAML handles **authentication** only — confirming who the user is. It does not control what the
user is authorized to access inside Unico's products; access still needs to be granted by your
Unico project team.
:::

### Integration steps

#### 1. Register the Service Provider (SP) in your IdP

Your IdP needs two values to register Unico as a Service Provider: the **Entity ID** (a unique
identifier for the SP) and the **ACS URL** (Assertion Consumer Service URL) — the endpoint that
receives the SAML assertions.

| Environment | Entity ID | ACS URL |
|---|---|---|
| **Production** | `https://identity.acesso.io` | `https://identity.acesso.io/auth/saml/callback` |
| **UAT** | `https://identityhomolog.acesso.io` | `https://identityhomolog.acesso.io/auth/saml/callback` |

#### 2. Map user attributes

Configure your IdP to send the following claims in the SAML assertion. These map your users'
attributes (name, email, username) between your IdP and Unico.

| Attribute | Value | Required |
|---|---|---|
| `email` | User's email address | Yes |
| `user_name` | Username | Yes |
| `given_name` | First name | Yes |
| `family_name` | Last name | Yes |
| `phone_number` | Phone number | No |

#### 3. Obtain your IdP's metadata

Your IdP typically provides an XML file with its own configuration — its public certificate,
authentication endpoint URLs, and related settings. Send this file to your Unico support contact
to complete the integration on Unico's side.

**Example SAML metadata for an SP**

```xml
<EntityDescriptor entityID="https://your-sp.example.com/"
  xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
  <SPSSODescriptor
      AuthnRequestsSigned="true"
      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
        <X509Data>
          <X509Certificate>YourSigningCertificate</X509Certificate>
        </X509Data>
      </KeyInfo>
    </KeyDescriptor>
    <AssertionConsumerService
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
        Location="https://your-sp.example.com/acs"
        index="1"/>
  </SPSSODescriptor>
</EntityDescriptor>
```

### First access

Once the SP is registered and configured in your IdP, users can authenticate directly at:

| Environment | Login URL |
|---|---|
| **Production** | [`https://identity.acesso.io`](https://identity.acesso.io) |
| **UAT** | [`https://identityhomolog.acesso.io`](https://identityhomolog.acesso.io) |

After entering their company and user information on the login screen, the user is redirected to
your IdP for authentication. On success, they're redirected back to the configured callback URL
and their account is created in Unico's authentication platform.

### Configuration by identity provider

### Microsoft Entra ID

## Create an Enterprise Application

1. In **Microsoft Entra ID**, go to **Enterprise Applications** and select **New application**.
2. Choose **Create your own application**, then **Integrate any other application you don't find
   in the gallery (Non-gallery)**.
3. Name the application after the Unico product being configured (e.g. "Unico IDCloud") and click
   **Create**.

## Configure Single Sign-On

1. In the application's **Manage** menu, open **Single sign-on** and select **SAML**.
2. Edit **Basic SAML Configuration** and fill in the **Identifier (Entity ID)** and **Reply URL
   (Assertion Consumer Service URL)** with the values from [step 1](#1-register-the-service-provider-sp-in-your-idp)
   above, for the environment you're configuring.
3. Edit the **Attributes & Claims** section to match the attribute table from
   [step 2](#2-map-user-attributes). For every claim you edit, clear the **Namespace** field — it
   must be empty.

The final claims should look like this:

| Claim name | Type | Value |
|---|---|---|
| Unique User Identifier (Name ID) | SAML | `user.userprincipalname` (`nameid-format:emailAddress`) |
| `email` | SAML | `user.mail` |
| `family_name` | SAML | `user.surname` |
| `given_name` | SAML | `user.givenname` |
| `user_name` | SAML | `user.mail` |

### What's next

- [Authentication](./authentication) — the separate OAuth2 flow used for server-to-server API calls
- [Environments](./environments) — sandbox vs production hosts