> For the complete documentation index, see [llms.txt](https://docs.iadvize.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iadvize.dev/use-cases/administration/users/saml-sso-authentication-implementation-guide.md). # SAML SSO Authentication — Implementation Guide ### Why use SAML SSO? SAML 2.0 is one of the most widely adopted SSO protocols in the enterprise. It is worth setting up for two reasons: * **Security** — your users authenticate to iAdvize (and your other tools) from a single centralized account. You control authentication and access policies from one place. * **Deployment at scale** — you can onboard hundreds or thousands of users without creating and maintaining an individual password for each one. Authentication relies on your existing directory (domain controller / Active Directory / user database). ### How it works iAdvize acts as the **Service Provider (SP)** and delegates authentication to your **Identity Provider (IdP)** — for example Okta, Microsoft Entra ID, or AD FS. * A user opens iAdvize, gets redirected to your IdP, authenticates there, and is redirected back to iAdvize, signed in. * The flow is **SP-initiated only**. IdP-initiated SSO is not supported, for security reasons. * iAdvize matches your users to iAdvize accounts using their **email address**. > iAdvize integrates as a Service Provider only. It cannot serve as the Identity Provider for your other applications, nor issue SAML assertions to third-party services — bring your own IdP to authenticate against. ### Prerequisites * **Create your iAdvize users first.** iAdvize uses the email address as a unique key, so each email must be unique and must match exactly the email exposed by your IdP. See [how to create or edit a user](https://help.iadvize.com/hc/en-gb/articles/203433397). * **Provision your users in your IdP / directory** (domain controller, Active Directory, or database) beforehand. * There is no auto-provisioning. Users must exist on both sides (you can create iAdvize users in bulk through the [GraphQL API](https://docs.iadvize.dev/technologies/graphql-api/authentication)). ### Getting started To enable SAML SSO, get in touch with your Customer Success Manager. A Technical Project Manager will then guide you through the configuration. ### Implementation steps #### 1. Provide your IdP information to iAdvize | Item | Details | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **X.509 signing certificate** | Your IdP public key, encoded in PEM or CER format (see formatting note below). | | **Sign-in URL** | The URL where your users authenticate against your IdP. | | **Email exposed as Name ID or SAML attribute** | iAdvize maps your users by email. Expose it in the `NameID`, or in a standard attribute such as `email` / `emailAddress` if your IdP does not put the email in `NameID`. | | **Email domain** *(optional)* | The domain of your operators' email addresses. Required only if you want SSO to trigger automatically from the iAdvize login page or use the mobile app (see "Connecting a user"). | The easiest way to share the first three is to send the **metadata file** generated by your IdP — it already contains the sign-in URL and the X.509 certificate. #### 2. iAdvize Service Provider configuration If your IdP requires SP details to create the connection on your side, use the following values. Replace `{CID}` with your iAdvize client ID. | Setting | Value | | ---------------------------------------- | ------------------------------------------------------------------ | | **Entity ID / Audience URI** | `urn:auth0:iadvize:saml-ha-{CID}` | | **Assertion Consumer Service (ACS) URL** | `https://auth.iadvize.com/login/callback?connection=saml-ha-{CID}` | | **iAdvize SP metadata** | `https://auth.iadvize.com/samlp/metadata?connection=saml-ha-{CID}` | #### 3. Certificate format The X.509 certificate must be in valid PEM format: * Wrap the Base64 content with `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`. * Lines of 64 characters maximum. * Save as `.pem` in UTF-8, without a BOM. You can validate the certificate locally with `openssl x509 -in your-cert.pem -noout -text` before sending it. > X.509 certificates expire (typically every 1 to 3 years). Track the expiry date: an expired certificate breaks authentication with no warning. Send your renewed certificate to your iAdvize contact ahead of the expiry date. ### Connecting a user There are two ways to sign in. If you are not sure which fits your use case, discuss it with your Customer Success Manager and the Technical Project Manager on the project. #### Option A — Direct link (recommended) Sign a user straight into iAdvize through a dedicated link: ``` https://ha.iadvize.com/admin/login?connectionId=saml-ha-{CID} ``` When a user opens this link, they are redirected to your IdP and signed in to iAdvize. If they already have an active IdP session, the redirect is immediate. This is the preferred option: it simplifies onboarding and requires no change in your environment. It is especially useful when a single email domain is shared across several iAdvize accounts, where automatic domain-based routing is not possible. > The direct link cannot be used on the mobile apps. #### Option B — iAdvize login page Users sign in from the standard login page at [https://ha.iadvize.com](https://ha.iadvize.com/). The **domain** of the email they enter routes them to the IdP configured for that domain, and they are redirected to authenticate. This requires the optional email domain (step 1) to be configured. **It is the only SAML option on the mobile apps.** ### Current limitations * **No SSO logout** — signing out of iAdvize does not sign the user out of the IdP. * **No auto-provisioning** — users are not created automatically from SAML assertions. Create them manually or through the [GraphQL API](https://docs.iadvize.dev/technologies/graphql-api/authentication). * **SP-initiated only** — IdP-initiated SSO is not supported, for security reasons. * **One email domain per connection** — each iAdvize account (CID) maps to a single email domain for automatic routing. If a domain is shared across several accounts, use the direct link (Option A). --- # 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: ``` GET https://docs.iadvize.dev/use-cases/administration/users/saml-sso-authentication-implementation-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.