# Single Sign-On with Ping Identity
## Step 1 - Obtain the SAML Provider Details from Updraft
> Only Owner of an Updraft Organization is able to add an SSO Integration
1. Open your Account Settings as an Owner
2. Go to the Security Page
3. Click Add new SSO
4. Click **CUSTOM SSO**
5. You will see now your SAML configuration
1. Ensure the **ACS URL is set to**: `https://getupdraft.com/saml2_auth/acs/`
6. Store them
## Step 2 - Add a New App in Ping Identity
1. Login to your [Ping Identity Console](https://signon.pingidentity.com/davinci/policy/5447db4173e2cd3139ba8e633817677e/authorize?client_id=b91b7752f23e20d56c8623aca138ead8\&response_type=code\&scope=openid\&redirect_uri=https://www.pingidentity.com)
2. Click on **Applications.**
3. Then select the Application section and click on the blue circular **+** button at the top of the page.
4. Enter your Application Name, select **SAML Application**, and click the **Configure** button when available.
5. From the SAML Configuration, select **Manually Enter**, then enter your Single Sign On URL and Audience Restriction from Step 1.
6. Click the **Save** Button.
## Step 3 - Configure Ping Identity Single Sign-On with SAML
1. From the Applications page, locate and select the application you just created, then enable the toggle switch.
2. Select the application and go to the Attribute Mapping tab. Click the pencil icon to edit the mappings.
1. For the **saml\_subject** attribute, select **Email Address** from the PingOne Mappings drop-down and click **+ Add**.
2. Next, add **email** to the Attributes field, select **Email Address** from the drop-down, and click **+ Add**.
3. Next, add **frist\_name** to the Attributes field, select **Given Name** from the drop-down, and click **+ Add**.
4. Then, add **last\_name** to the Attributes field, choose **Family Name** from the drop-down, and click **+ Add**.
5. Then, add **username** to the Attributes field, choose **Email Address** from the drop-down, and click **+ Add**.
6. Finally, add **groups** to the Attributes field, select **Group Names** from the drop-down, and click **+ Add**.
3. Once configured, click the **Save** Button.
4. On the **Access** tab:
* If you want to restrict who can access the SSO app, create another user group in your Ping Identity console and assign it to the SSO app.
## Step 4 - Download the Metadata XML file from Ping Identity
1. Select the **Configuration** tab and click the pencil icon to edit the configuration. Choose the **Sign Assertion & Response** option, then click Save to apply your changes.
2. Once the configuration is complete, you will need to click on the **Download Metadata** button, as this will download the **Metadata XML** to complete the integration in Updraft.
## Step 5 `-` Upload the .xml metadata to your Updraft Organization
1. Click **Choose File** and select your **Metadata XML file**
2. Click **Save**
## Step 6 - verify the integration
After following all the above steps, log in to your Updraft account to verify that you are now able to sign in with your Custom SSO (Ping Identity).
If the integration was successful:
1. If you are opening your subdomain.getupdraft.com/login page you will see the **Login with Custom SSO Button**
2. When your assigned Users click on the Login with SSO Button they will be redirected to the Ping Identity login page
3. upon successful authentication with Ping Identity, your users will be logged into Updraft automatically and redirected to the dashboard page of Updraft
4. A new account for your uses will be created in Updraft after they logged-in the first time
5. Now you can assign projects and apps to your users.
If you encounter any issues, please refer back to the previous steps or reach out to the support team for assistance.
## Error handling
### **Required Attributes for Updraft SSO**
Updraft requires specific attributes to be included in the **SAML assertion** from your Identity Provider (IdP). If any of these attributes are missing or incorrectly mapped, authentication will fail.
| **Attribute Name** | **Required?** | **Expected Value** | **Description** |
| ------------------ | -------------------- | ------------------ | ------------------------------------------------------ |
| `saml_subject` | ✅ Required | Email Address | Used as the unique identifier for user authentication. |
| `email` | ✅ Required | Email Address | Must be present and **case-sensitive**. |
| `first_name` | ✅ Required | Given Name | The user's first name. |
| `last_name` | ✅ Required | Family Name | The user's last name. |
| `username` | ✅ Required | Email Address | Used for internal user management. |
| `groups` | ✅ Required (if used) | Group Names | Used for **role-based access control (RBAC)**. |
#### **🔍 Troubleshooting Missing Attributes**
* **Error:** *User is not found in Updraft*
* **Fix:** Ensure that the `email` and `saml_subject` attributes are correctly mapped in your IdP.
* **Error:** *SSO login succeeds, but user has no permissions*
* **Fix:** Check if the **`groups`** attribute is included in the SAML assertion and mapped correctly in Updraft.
### **Case Sensitivity for Email Addresses**
Updraft **treats email addresses as case-sensitive**. If the email address in the **SAML assertion does not match the case exactly as stored in Updraft**, authentication may fail.
#### **🔍 Common Case Sensitivity Issues**
| **Issue** | **Example** | **Fix** |
| ---------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- |
| Email in SAML does not match stored case | `John.Doe@company.com` ≠ `john.doe@company.com` | Ensure the **email attribute is consistently formatted** in the IdP. |
| User exists but cannot log in | `User Not Found` error despite correct email | Normalize email casing in the IdP **or update the stored email in Updraft**. |
#### **🔍 Recommended Fix**
* Configure **Ping Identity or other IdPs** to always send emails in **lowercase** to Updraft.
* Ensure that user records in Updraft **match the exact email case** as sent in SAML.
***
### **Assertion Consumer Service (ACS) URL Mismatch**
The **ACS URL** tells the IdP where to send the authentication response. If this URL is incorrect, SSO will fail.
#### **🔍 Fixing ACS URL Errors**
| **Error Message** | **Cause** | **Fix** |
| ---------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------- |
| `Invalid ACS URL` | The IdP is sending the SAML response to the wrong URL. | Ensure the **ACS URL is set to**: `https://getupdraft.com/saml2_auth/acs/` |
| `Audience Restriction Error` | The **SAML Audience does not match** what Updraft expects. | Ensure the `saml:Audience` value matches `https://getupdraft.com/`. |
***
###
