> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.ggcircuit.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Configuring SAML SSO for ggLeap

## Configuring SAML SSO for ggLeap

This article outlines the steps to configure SAML Single Sign-On (SSO) for ggLeap, allowing users to log in using their existing credentials from a SAML Identity Provider (IdP).

**Prerequisites:**
* You have access to the ggLeap Admin portal.
* You have a SAML IdP configured (e.g., Shibboleth, Azure AD, Google Workspace).
* You have the Metadata URL for your SAML IdP.

**Steps:**

1. **Navigate to the** [**Add-ons Page**](https://admin.ggleap.com/settings/add-ons):
* Log in to your ggLeap Admin portal.
* Go to **Settings** > **Add-ons**

2. **Access the SAML SSO Add-on:**
* Locate and click on the **Saml SSO** add-on.

![](https://storage.crisp.chat/users/helpdesk/website/-/a/f/d/6/afd6941e8bc7d800/image-20250310-183816_1t4jqal.png)

3. **Configure InCommon Federation Participant (if applicable):**
* If the toggle switch labeled "YOUR INSTITUTION is an Incommon Federation Participant" is enabled, **turn it off unless you are an Incommon Federation Participant.**

![](https://storage.crisp.chat/users/helpdesk/website/-/a/f/d/6/afd6941e8bc7d800/image-20250310-184007_b7xwv2.png)

4. **Enter your IdP Metadata URL:**
* In the field that was previously labeled "InCommon Entity ID", **enter the Metadata URL for your SAML Identity Provider**.

![](https://storage.crisp.chat/users/helpdesk/website/-/a/f/d/6/afd6941e8bc7d800/image-20250310-184042_d7udal.png)

5. **Enter SSO Configuration ID (if required):**
* If your setup requires a specific SSO Configuration ID (e.g., for multi-tenant Azure AD configurations), enter it in the "SSO Configuration ID" field.
* **Note:** For most standard setups, this field can be left blank.

![](https://storage.crisp.chat/users/helpdesk/website/-/a/f/d/6/afd6941e8bc7d800/image-20250310-184100_d9akin.png)

6. **Save your settings:**
* Click the **Save** button.

**On your Identity Provider (IdP):**
* You will need to configure your SAML IdP to trust ggLeap as a Service Provider (SP).
* Use the following Metadata URL for ggLeap:

```
  https://sp.ggleap.com
```

**Important Considerations:**
* **Metadata URL:** Ensure you are using the correct Metadata URL from your IdP. This is crucial for establishing the trust relationship.
* **SSO Configuration ID:** Only use this if you have a specific requirement, such as multi-tenant setups. Consult your IT department or ggLeap support if you are unsure.
* **IdP Configuration:** The specific configuration steps on your IdP will vary depending on the platform you are using. Refer to your IdP's documentation for detailed instructions.
* **Testing:** After configuring both ggLeap and your IdP, use the "Test Connection" button in the ggLeap SAML SSO settings to verify the connection.


# SAML Single Sign-On (SSO) FAQ
Use this guide to understand how our application handles metadata synchronization, security certificate transitions, and multi-certificate configurations.

## 1. How often is the metadata refreshed?
We maintain high synchronization with the **InCommon MDQ aggregate endpoint** to ensure your identity provider (IdP) settings are always current.
* **Polling Frequency:** Every 10 minutes using conditional HEAD requests.
* **Immediate Updates:** When the ETag indicates the aggregate has changed, we immediately download and re-import the metadata.
* **Caching Policy:** Parsed metadata is cached for **7 days**. Any IdP entries older than that are automatically refreshed on the next poll.

|| In practice, new or updated InCommon metadata is picked up within approximately 10 minutes of publication.

## 2. Do you support SAML key rollover with multiple certificates?
**Yes.** We fully support standard SAML key rollover to prevent service downtime during certificate migrations.

When an IdP publishes both its old and new signing certificates in its metadata during a rollover window, **both certificates are honored simultaneously**.

| Signatures produced with either key will validate successfully throughout the transition.

No manual coordination or configuration change is required on our side; the rollover is driven entirely by the IdP's published metadata.

## 3. How does the application handle metadata with multiple certificates?
Our application strictly adheres to the SAML 2.0 metadata specification when processing `<KeyDescriptor>` elements.
* **Data Preservation:** All `<KeyDescriptor>` elements published in an IdP's EntityDescriptor are preserved during import.
* **Validation Logic:** At assertion-validation time, every certificate marked for signing use is considered a valid signer.
* **Success Criteria:** An assertion is accepted if its signature verifies against **any** of the provided certificates.

This applies to the following KeyDescriptor entries:
1. `use="signing"`
2. `use="encryption"`
3. Unspecified-use entries

### Technical Summary
| **Feature** | **Specification** |
| Refresh Interval | 10 Minutes |
| Protocol | MDQ with ETags |
| Key Rollover | Fully Supported |
| Multi-Cert Logic | Validates against any match |
| Compliance | SAML 2.0 Standard |

||| **Warning:** Ensure your metadata remains reachable at the designated endpoint to prevent synchronization failures.