How do I configure Okta SAML Single Sign-On for my customer portal?

by Marc Staine

Last updated: 11-Sep-2025

Summary

This article provides a step-by-step guide to configure Okta SAML Single Sign-On (SSO) for your customer portal. It addresses common setup issues, including clarifying the correct SSO URLs and ensuring all necessary identity provider (IdP) details are correctly mapped for a seamless and secure login experience.

Why This Matters

Implementing SAML SSO allows your users to log into the customer portal using their existing corporate credentials, eliminating the need for separate logins and improving security. A correct setup ensures a smooth authentication flow, preventing login failures and providing a consistent user experience. This guide will help you avoid common misconfigurations related to URLs and attribute mapping. 🔐

Solution / Step-by-Step Instructions

This guide walks you through configuring Okta as your Identity Provider (IdP) for SAML SSO with your customer portal. You will first set up the application in Okta and then transfer the necessary details to your customer portal's SAML configuration. 💻

Part 1: Configure the SAML Application in Okta

1. Log In to Okta Administrator Dashboard: Access your Okta admin account.
2. Navigate to Applications: Go to Applications > Applications.
3. Create App Integration: Click Create App Integration.
4. Select SAML 2.0: Choose SAML 2.0 and click Next.
5. General Settings:
   • App name: Enter a descriptive name like "Product Portal" or "Customer Support Portal".
   • (Optional) Add an app logo and configure visibility settings.
6. Configure SAML: This is a critical section for defining how Okta communicates with your customer portal.
   • Single sign on URL (ACS URL): Enter https://sso.supportbench.net/saml/auth ✅
   • Audience URI (SP Entity ID): Enter https://sso.supportbench.net/saml/auth (This should be the same as the Single Sign On URL).
   • Default Relay State: Leave blank.
   • Name ID format: Select EmailAddress.
   • Application username: Select Okta username or Email (whichever aligns with how your users' email addresses are provisioned in Okta).
   • Attribute Statements (Required for Username Mapping): Add the following attribute statements to ensure user data is correctly passed from Okta to your customer portal:
     • Name: email, Name format: Unspecified, Value: user.email
     • Name: user_id, Value: user.id
     • Name: mail, Value: user.email
     • Name: name, Value: user.firstName + " " + user.lastName
     • Name: given_name, Value: user.firstName
     • Name: family_name, Value: user.lastName
     • Name: upn, Value: user.login
7. Click Next.
8. Feedback: Select I'm an Okta customer adding an internal app or the relevant option.
9. Click Finish.
10. Get Okta's IdP Metadata: Once the app is created, go to the Sign On tab for your new "Product Portal" app in Okta.
    • Scroll down to the SAML Signing Certificates section.
    • Click the Identity Provider metadata link. This will open an XML file in your browser. Save this file or carefully copy the relevant information:
    • Identity Provider Single Sign-On URL: Copy this URL. This will be your "Login URL" in the customer portal.
    • Identity Provider Single Logout URL (if available): Copy this URL. This will be your "Logout URL" in the customer portal.
    • X.509 Certificate: Copy the entire content of the certificate, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
11. Assign Users/Groups: Go to the Assignments tab for your app and assign the individual users or groups who should have access to the customer portal via SAML.

Part 2: Configure Your Customer Portal

1. Log In to Your Product Administration: Access your product's admin interface.
2. Navigate to SAML Settings: Go to Configuration > Customer Portal.
3. Select Your Customer Portal: Choose the specific customer portal you wish to configure.
4. Go to the Security Tab: Click on the Security tab, then scroll down to the SAML section.
5. Populate SAML Fields: Use the information you copied from Okta's IdP metadata:
   • Login URL: Paste the "Identity Provider Single Sign-On URL" you copied from Okta.
   • Logout URL: Paste the "Identity Provider Single Logout URL" from Okta. If not provided or unsure, you may sometimes leave this blank or use the SSO URL as a fallback.
   • Certificate: Paste the entire X.509 Certificate content, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, into the Certificate field.
   • Username mapping: Select or confirm this is set to Email address.
6. Save Settings: Ensure you save all your changes in the customer portal. 💾

Best Practices / Tips

• 🔎 Verify All URLs: Double-check that the "Single sign on URL" and "Audience URI" in Okta, and the "Login URL" in your customer portal are exactly as specified. A single typo can cause a 404 error.
• 💡 Test Thoroughly: After configuration, test the SAML login process with a designated test user before rolling it out to all users.
• 🤓 Comprehensive Attribute Mapping: Use all recommended attribute statements in Okta to ensure all necessary user details (email, first name, last name, user ID) are passed to the customer portal, facilitating proper user creation or linking.
• 🔒 Security Tab for Portals: Remember that SAML configuration is managed within the security settings of each individual customer portal.

Troubleshooting / FAQs

Q: Why am I getting a 404 error or a "Page Not Found" when trying to log in via SAML? 🚨

A: This is typically caused by an incorrect URL. Ensure the "Single sign on URL" and "Audience URI" in your Okta application are precisely set to https://sso.supportbench.net/saml/auth. Also, verify that the "Login URL" in your customer portal matches the "Identity Provider Single Sign-On URL" from Okta's metadata. 📃

Q: My Okta configuration screen looks different from these instructions. What should I do?

A: Okta's interface can evolve. Ensure you are creating a SAML 2.0 application. If you encounter significant differences, refer to Okta's official documentation for creating a SAML app or contact Okta support for the most current steps. The core principles of setting URLs and attributes remain consistent. 📚

Q: Do I need to upload a separate "Signature Certificate"?

A: The X.509 Certificate you obtain from Okta's IdP metadata is typically used for both encryption and verifying the digital signatures of assertions sent by Okta. The "Certificate" field in your customer portal's SAML settings is where you should paste this X.509 certificate. No separate signature certificate should be required unless explicitly stated by the product. 📝

Q: My users are logging in, but their names or other details aren't mapping correctly.

A: Revisit the "Attribute Statements" section in your Okta SAML application. Ensure all the recommended attributes (email, user_id, name, etc.) are correctly defined with their corresponding user.attribute values. Also, confirm that "Username mapping" in your customer portal is set to Email address. 🔢