Single Sign-On (SSO)

​

Overview

Single Sign-On (SSO) allows organizations to manage authentication and authorization of their members for external applications, such as Portal’s Admin Dashboard, using an identity provider (IdP) like Okta, Azure AD, or Google Workspace. With SSO enabled, your organization’s members can access the Portal Admin Dashboard using their existing corporate credentials, eliminating the need for separate Portal accounts. This provides a seamless authentication experience while maintaining centralized control over access. Portal supports two primary web SSO protocols:

• OIDC (OpenID Connect): A modern authentication protocol built on OAuth 2.0
• SAML2 (Security Assertion Markup Language 2.0): An XML-based protocol for exchanging authentication and authorization data

​

How SSO Works

Once SSO is configured for your organization, the authentication flow works as follows:

1. Member Access: When a member attempts to access the Admin Dashboard, they are prompted to provide a unique slug associated with your organization’s SSO configuration.
2. IdP Redirect: After entering the slug, the member is redirected to your organization’s identity provider (IdP) for authentication.
3. Authentication: The member authenticates using their corporate credentials through the IdP.
4. Dashboard Access: Upon successful authentication at the IdP, the member is redirected back to the Portal Admin Dashboard and granted access.

This process ensures that authentication is handled by your organization’s IdP, giving you centralized control over who can access the Portal Admin Dashboard.

​

Configuration Steps

To begin configuring SSO, first access the Single Sign-On section:

1. Log into your Portal Admin Dashboard.
2. Navigate to the Settings page.
3. Locate the “Single Sign-On” section.

Choose either OIDC or SAML2 based on your organization’s identity provider capabilities. You only need to configure one protocol.

​

OIDC Configuration Steps

To set up OIDC Single Sign-On:

1. In the Single Sign-On section, click Configure OIDC.
2. A modal titled “Configure OIDC Single Sign-On Connection” will appear.

The modal displays information you’ll need to configure in your identity provider, and fields for information you’ll need to provide from your identity provider: Information from Portal (to configure in your IdP):

• Redirect URL: The callback URL that your IdP will use to redirect users back to Portal after authentication.

Information from your IdP (to enter in Portal):

• Client ID: The OAuth client identifier from your IdP
• Client Secret: The OAuth client secret from your IdP
• Issuer URL: The OIDC issuer URL from your IdP (typically in the format https://your-idp-domain.com)

​

Configure Your Identity Provider

1. Log into your identity provider’s admin console.
2. Create a new OIDC Application and choose Web Application for Application Type.
3. Configure the following in your IdP:
   • Redirect URI / Callback URL: Paste the Redirect URL you copied from Portal
   • Note the Client ID and Client Secret that your IdP generates
   • Note your IdP’s Issuer URL
4. From your IdP, copy the following:
   • Client ID: The OAuth client identifier from your IdP
   • Client Secret: The OAuth client secret from your IdP
   • Issuer URL: The OIDC issuer URL from your IdP
5. Return to the Portal modal and enter the Client ID, Client Secret, and Issuer URL.
6. Click “Configure” to save your OIDC SSO settings.

​

SAML2 Configuration Steps

To set up SAML2 Single Sign-On:

1. In the Single Sign-On section, click Configure SAML2.
2. A modal titled “Configure SAML Single Sign-On Connection” will appear.

The modal displays information you’ll need to configure in your identity provider, and fields for information you’ll need to provide from your identity provider: Information from Portal (to configure in your IdP):

• Single Sign-On (SSO) / ACS URL: The Assertion Consumer Service URL where your IdP should send SAML responses.
• Audience URI / Entity Id: The Entity ID that identifies Portal as the Service Provider. This is typically the same URL as the ACS URL.
• Name ID Format: The format for the user identifier. Portal uses “Email Address” as the Name ID format.

Information from your IdP (to enter in Portal):

• IdP SSO URL: The Single Sign-On URL from your IdP where users will be redirected for authentication
• IdP Entity Id: The Entity ID that identifies your identity provider
• x509 Certificate: The X.509 certificate from your IdP used to verify SAML assertions

​

Configure Your Identity Provider

1. Log into your identity provider’s admin console.
2. Create a new SAML Application.
3. Configure the following in your IdP:
   • Single sign-on URL / ACS URL: Paste the SSO / ACS URL you copied from Portal
   • Audience URI / SP Entity ID: Paste the Audience URI / Entity Id you copied from Portal
   • Name ID format: Set to “Email Address” (or “Unspecified” if your IdP supports it and will send email addresses)
   • Recipient URL and Destination URL: Typically the same as the Single sign-on URL (some IdPs have a checkbox to use the same value)
4. From your IdP, copy the following:
   • IdP SSO URL: The Single Sign-On URL from your IdP
   • IdP Entity Id: The Entity ID from your IdP
   • x509 Certificate: The X.509 certificate (usually found in the SAML settings or metadata)
5. Return to the Portal modal and enter the IdP SSO URL, IdP Entity Id, and x509 Certificate.
6. Click “Configure” to save your SAML2 SSO settings.

​

Understanding Your SSO Configuration

After configuring SSO, the Single Sign-On section will display:

• Status: Shows whether SSO is Enabled or Disabled
• Slug: A unique identifier for your SSO connection (e.g., david-example-okta-sso). This is the slug that members will use to access the dashboard via SSO.
• Reconfigure Button: Allows you to update your SSO configuration at any time

​

Common Identity Provider Setup Examples

​

Okta

For OIDC with Okta:

1. In Okta Admin Console, go to Applications > Applications > Create App Integration.
2. Select OIDC - OpenID Connect as the sign-in method.
3. Choose Web Application as the application type.
4. Configure:
   • Sign-in redirect URIs: Add the Redirect URL from Portal
   • Sign-out redirect URIs: (Optional) Add a sign-out URL if needed
5. After creating the app, note the Client ID and Client Secret.
6. The Issuer URL is typically: https://your-domain.okta.com or https://your-domain.okta.com/oauth2/default

For SAML2 with Okta:

1. In Okta Admin Console, go to Applications > Applications > Create App Integration.
2. Select SAML 2.0 as the sign-in method.
3. In the “2 Configure SAML” step, configure the following:
   • Single sign-on URL: Paste the SSO / ACS URL from Portal
   • Check the box “Use this for Recipient URL and Destination URL” (if available)
   • Audience URI (SP Entity ID): Paste the Audience URI / Entity Id from Portal
   • Name ID format: Select “Unspecified” (Okta will send email addresses when configured)
   • Application username: Typically set to “Okta username” or “Email”
4. After saving, go to the “Sign On” tab to find:
   • IdP SSO URL: Copy the “Identity Provider Single Sign-On URL”
   • IdP Entity Id: Copy the “Identity Provider Issuer” (Entity ID)
   • x509 Certificate: Copy the certificate from the “X.509 Certificate” section
5. Enter these values in the Portal SAML configuration modal.

​

Azure AD (Microsoft Entra ID)

For OIDC with Azure AD:

1. In Azure Portal, go to Azure Active Directory > App registrations > New registration.
2. Configure:
   • Redirect URI: Add the Redirect URL from Portal (select “Web” platform)
3. After registration, note the Application (client) ID.
4. Go to Certificates & secrets to create a new client secret.
5. The Issuer URL format is: https://login.microsoftonline.com/{tenant-id}/v2.0

For SAML2 with Azure AD:

1. In Azure Portal, go to Enterprise applications > New application.
2. Choose Non-gallery application or integrate a SAML application.
3. Configure the SAML settings with the ACS URL and Entity ID provided by Portal.

​

Google Workspace

For OIDC with Google Workspace:

1. Go to Google Cloud Console.
2. Navigate to APIs & Services > Credentials > Create Credentials > OAuth client ID.
3. Configure:
   • Application type: Web application
   • Authorized redirect URIs: Add the Redirect URL from Portal
4. Note the Client ID and Client Secret.
5. The Issuer URL is: https://accounts.google.com

​

Troubleshooting

​

Common Issues

Issue: Redirect URL mismatch

• Solution: Ensure the Redirect URL in your IdP exactly matches the one provided by Portal. Check for trailing slashes, HTTP vs HTTPS, and any extra characters.

Issue: Invalid Client ID or Client Secret

• Solution: Verify that you’ve copied the Client ID and Client Secret correctly from your IdP. Some IdPs require you to view the secret immediately after creation.

Issue: Invalid Issuer URL

• Solution: Confirm the Issuer URL format with your IdP documentation. Some IdPs use different issuer URLs for different environments (e.g., sandbox vs. production).

Issue: Members cannot access dashboard after SSO setup

• Solution:
  • Verify that SSO status shows as “Enabled”
  • Confirm members are using the correct slug
  • Check that the IdP configuration is complete and active
  • Ensure members have the necessary permissions in your IdP

Issue: SAML2 configuration errors

• Solution:
  • Verify the X.509 certificate is valid and not expired
  • Ensure the Entity ID matches between Portal and your IdP
  • Check that the ACS URL is correctly configured in your IdP
  • Review SAML response logs in your IdP for specific error messages

​

Support

Congratulations! 🎉 You’ve successfully configured Single Sign-On for your organization. Your members can now access the Portal Admin Dashboard using their corporate credentials through your identity provider. If you have any questions or need assistance with SSO configuration, please reach out to our support team via Slack.