--- title: Set up an SSO connection description: >- Create a SAML enterprise connection, exchange service-provider and identity-provider configuration, map attributes, activate the connection, and test the sign-in. sidebar: order: 1 --- This guide walks through creating an **enterprise connection**, exchanging SAML configuration with your identity provider, and activating it so people can sign in with SSO. Once active, anyone whose email matches the connection's [email domains](/docs/fuxam-web/settings/single-sign-on/manage-email-domains) is routed to your provider automatically. :::info You need the **Update settings** permission. All SSO configuration lives in **Settings → Subdomain SSO**. ::: ## Before you begin Have these ready from your identity provider (IdP): - Access to your IdP admin console (Microsoft Entra ID, Okta, Google Workspace, OneLogin, or any SAML 2.0 provider). - Either your IdP's **metadata URL** or its **metadata XML file**, *or* the individual values: the **IdP entity ID (issuer)** and the **IdP SSO URL (sign-in URL)**, plus the **signing certificate**. - The list of **email domains** your organization uses (for example, `university.edu`). You can add these during or after setup — see [Manage email domains](/docs/fuxam-web/settings/single-sign-on/manage-email-domains). ## Open SSO settings 1. From your dashboard, open **Settings** (the gear icon or Settings link in the navigation). 2. In the Settings sidebar, select **Subdomain SSO**. The page has two areas: a section for **forcing SSO on your institution subdomain**, and the **SSO connections** list where you create and manage enterprise connections. ## Create a connection 1. In the **SSO connections** section, select **Add connection**. 2. Choose your **provider** from the list (for example, Microsoft Entra ID, Okta, or Google Workspace). If your provider is not listed, choose the **custom SAML** option — the setup works the same way with any SAML 2.0 IdP. 3. Enter a **name** for the connection so you can recognize it later (for example, "Staff — Entra ID"). 4. Optionally add one or more **email domains** now. You can also do this later. Enter a domain and press Enter to add it as a badge; use the × on a badge to remove it. 5. Create the connection. It opens the connection setup page and starts as **inactive** — it will not route real sign-ins until you finish configuration and activate it. ## Exchange configuration with your identity provider SAML setup is a two-way exchange: Fuxam (the **service provider**) gives your IdP some values, and your IdP gives Fuxam some values back. ### 1. Give Fuxam's details to your IdP On the connection setup page, the **Service provider (SP) configuration** section shows the values your IdP needs, such as the **ACS (reply) URL** and the **SP entity ID / audience**. Copy each value into the corresponding field when you create the Fuxam application in your IdP admin console. :::tip Use the copy buttons next to each value rather than retyping. A single mistyped character in the ACS URL is the most common cause of a failed first sign-in. ::: ### 2. Give your IdP's details to Fuxam Back on the connection setup page, open the **Identity provider (IdP) setup** section and provide your IdP's configuration one of two ways: - **Metadata (recommended)** — paste your IdP's metadata URL or upload its metadata XML file. Fuxam reads the entity ID, sign-in URL, and certificate from it. - **Manual entry** — enter the **IdP entity ID**, **IdP SSO URL**, and **certificate** by hand if your provider does not offer metadata. ### 3. Map attributes Confirm the **attribute mapping** so Fuxam can read each person's email (and name) from the SAML response. The setup guide lists the expected attributes; most providers match the defaults, but adjust them if your IdP sends attributes under different names. 1. Review the attribute mapping table on the setup page. 2. Ensure the **email** attribute maps to the claim your IdP sends the user's email address in. Adjust the name and other attributes if needed. 3. Save your changes. ## Activate the connection When SP details are in your IdP, IdP details are in Fuxam, and attribute mapping is confirmed, turn the connection on. 1. On the connection setup page, enable the **Active** toggle. 2. If Fuxam reports the connection is incomplete, revisit the IdP setup and attribute mapping — activation is blocked until required fields are present. An active connection shows an **Active** status badge in the connections list; inactive connections are labeled accordingly. ## Test the sign-in Before rolling out, confirm the round trip works. 1. On the connection setup page, use the **Copy test URL** button to get the connection's test sign-in link. 2. Open the link (ideally in a private window) and sign in with an account whose email is on one of the connection's domains. 3. Confirm you are redirected to your identity provider and returned to Fuxam signed in. ## Optional: force SSO on your subdomain If your institution uses a dedicated Fuxam subdomain, you can send everyone who visits it straight to SSO by default. Enable **Force subdomain SSO** in the subdomain section at the top of the **Subdomain SSO** page. This requires your institution subdomain to be configured first. :::note Forcing subdomain SSO changes the default sign-in path for that subdomain. Keep at least one administrator able to sign in another way until you have confirmed SSO works, so you are never locked out. ::: ## Additional options per connection Each connection has a few switches on its setup page: | Option | What it does | |---|---| | **Active** | Turns the connection on or off. Only active connections route sign-ins. | | **Allow subdomains** | Also matches sub-domains of your listed email domains (for example, `mail.university.edu` as well as `university.edu`). | | **Auto-sync new users** | Automatically adds a new member's email domain to this connection as people join — see [Manage email domains](/docs/fuxam-web/settings/single-sign-on/manage-email-domains). | ## Rename or delete a connection - **Rename / edit domains** — open the connection from the list, change the name or domains, and save. - **Delete** — use the delete action on the connection row and confirm. Deleting a connection stops routing its domains to your IdP; affected people fall back to Fuxam password sign-in. Any auto-sync setting for that connection is cleared automatically on delete. ## Troubleshooting | Symptom | Likely cause | What to check | |---|---|---| | Activation is blocked | Required IdP fields or attribute mapping missing | Complete the IdP setup and attribute mapping, then toggle **Active** again | | Sign-in fails after redirect to IdP | ACS URL or SP entity ID mismatched in the IdP app | Recopy the SP values from the setup page into your IdP | | User lands on password sign-in instead of SSO | Their email domain is not on the connection, or the connection is inactive | Add the domain (see [Manage email domains](/docs/fuxam-web/settings/single-sign-on/manage-email-domains)) and confirm the connection is active | | SSO works for `university.edu` but not `mail.university.edu` | Sub-domains not allowed | Enable **Allow subdomains** on the connection | ## Related pages **[Manage email domains](/docs/fuxam-web/settings/single-sign-on/manage-email-domains)** Add, remove, sync, and auto-sync the domains that route users to this connection. **[Single sign-on (SSO)](/docs/fuxam-web/settings/single-sign-on)** How SSO, connections, and domains fit together. **[Roles and permissions](/docs/fuxam-web/base/user-management/roles-and-permissions)** Grant the Update settings access needed to manage SSO.