SSO Configuration Using SAML 2.0 for Enterprise Admins

This guide is designed to help enterprise administrators seamlessly integrate SSO with Poggio.

Overview

Welcome to our guide on configuring Single Sign-On (SSO) for your enterprise using SAML 2.0. This guide is designed to help enterprise administrators seamlessly integrate SSO with Poggio, enhancing security and simplifying the login process for your users. Follow this journey to get SSO up and running smoothly.

Step 1: Preparation

Understanding SAML 2.0

Before diving into the configuration, it's essential to understand what SAML 2.0 is. SAML (Security Assertion Markup Language) is a standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). In this setup, our SaaS product is the SP, and your enterprise's IdP will handle authentication.

Understanding the Poggio Enterprise Model

See Poggio Enterprise Model for more information on how Poggio offers advanced control and management for organizations using multiple workspaces.

Poggio offers several global enterprise controls that affect member access to the application. It’s recommend to begin with the default settings until the initial set of enterprise workspaces have been created.

Gather Required Information and Ensure Access

Ensure you have admin access to both your IdP and Poggio’s admin settings for your workspace.

You must contact Poggio support to assign an enterprise admin for your organization. The enterprise admin must already have a Poggio account, and should be someone with access to both IdP and DNS settings (e.g., an IT administrator.)

Step 2: Accessing the Enterprise Settings

1. Log in to Poggio

2. Navigate to Enterprise Settings:

   • Click your workspace name in the top left of the sidebar

   • Select 'Settings' in the menu

   • Select the 'Enterprise' tab

Step 3: Verifying Your Domain

Poggio must verify ownership of every email domain bound to a SAML configuration. Poggio uses DNS TXT record lookups to verify domain ownership. Add your domain in the enterprise settings page to generate your unique TXT record, then add the required entry to your domain’s DNS configuration. Poggio will automatically check for the record every 30 minutes until verified, though the enterprise admin may also trigger a verification check from the enterprise settings UI.

Step 4: Configuring SAML 2.0 Settings

Each SAML configuration is associated with exactly one verified domain, and one or more Poggio workspaces. The enterprise admin can add any Poggio workspace that they are a member of to their enterprise, and optionally assign each enterprise workspace a SAML configuration.

Assigning a SAML configuration to an enterprise workspace enables SSO via SAML 2.0 for that workspace. Furthermore, it requires members to sign in with SSO if the “enforce SSO login” setting is enabled at the enterprise level.

Adding Poggio as a Service Provider in Okta

Only SP-initiated login is supported at this time.

1. Access the admin console of your IdP.

2. Create a New SAML Application, using SAML 2.0.

   

   Example SAML application create form in IdP (Okta)
3. Configure General settings.

   • App Name: Poggio

   • App logo: Download logo image

   • App visibility: Ensure this is checked. Users will only be able to sign-in via SSO through the Poggio app itself.

     

     Example SAML general settings (Okta)
4. Configure SAML settings.

   • ACS (Assertion Consumer Service) URL: https://poggio.io/__/auth/handler

     • If applicable, check “Use this for recipient URL and destination URL”

   • Audience URI (SP Entity ID): poggio.io

     

     Example SAML application details form in IdP (Okta)
5. Configure additional application settings.

   • If your IdP allows, configure attributes to be sent to the SP. Common attributes include User ID, and Email.

   • Name ID format: EmailAddress

   • Application username: Email

   • Update application username on: Create and update

6. Go to the "Sign On" tab of the application and click on "More details"

   
7. Copy the "Issuer" value. This maps to the "Issuer URL" on the Poggio SAML form.

8. Copy the "Sign on URL". This maps to the "Sign on URL" on the Poggio SAML form.

9. Download the certificate and copy the contents. This maps to the "Public certificate" on the Poggio SAML form. (We current do not support the certificate format used by "Copy").

Adding Poggio as a Service Provider in OneLogin

1. Search for "Poggio" under the Applications tab.

   
2. (Optional) Set the description to "Poggio helps sellers effectively and efficiently build deeply researched account plans, tailored to their unique value props and updated in real time."

3. Ensure the "Visible in portal" is unchecked. We do not support IDP initiated login at the moment.

4. Ensure the SAML2.0 radio is checked.

   
5. Save the application.

6. Go to the SSO tab on the Poggio application.

7. Copy the "SAML 2.0 Endpoint (HTTP)". This maps to the "Sign on URL" on the Poggio SAML form.

8. Copy the "Issuer URL". This maps to the "Issuer URL" on the Poggio SAML form.

9. Click "View Details" on the X.509 Certificate and copy the certificate (starts with -----BEGIN CERTIFICATE-----). This maps to the "Public certificate" value on the Poggio SAML form.

Adding Identity Provider Details to Poggio

1. Select your verified domain. This must match the email domain of your IdP users.

2. In the 'Issuer URL' field, input the value provided by your IdP.

3. In the 'Sign on URL' field, input the SSO URL provided by your IdP. This is where authentication requests will be sent.

4. Paste the IdP Public Certificate. This enables Poggio to verify authenticity of authentication redirects from your IdP.

5. Select a default workspace for this SAML configuration. New SSO users matching this domain will be automatically added to the selected workspace.

SAML configuration modal in the Poggio enterprise settings page

Step 5: Testing the Configuration

Initiate SSO Login

1. Test SSO Login:

   • From the Poggio sign in page, click on the 'Continue with SSO' button.

   • You will be redirected to your IdP's login page.

2. Complete Authentication:

   • Enter your credentials on the IdP login page and authenticate.

3. Verify Access:

   • After successful authentication, you should be redirected back to Poggio and granted access.

Troubleshooting

Common Issues

1. Mismatched Entity IDs:

   • Ensure that the IdP Entity ID and SP Entity ID match exactly between the configurations on both sides.

2. Certificate Errors:

   • Verify that the IdP certificate is correctly entered in the proper format (PEM).

3. Incorrect URLs:

   • Double-check the IdP SSO URL and ACS URL for any typographical errors.

4. Attribute Mapping:

   • Ensure that the necessary attributes (e.g., User ID, Email) are being correctly sent from the IdP.

Conclusion

Congratulations! You have successfully configured SSO using SAML 2.0 for Poggio Enterprise. This setup enhances security and provides a seamless login experience for your users. If you encounter any issues or have questions, our support team is here to help. For further assistance, contact Poggio support.