Skip to main content

SAML Service Provider Setup Guide for WWPass Management Portal

Table of Contents​

  1. Overview
  2. Prerequisites
  3. Creating a Service Provider
  4. Configuring Your Application (SP)
  5. Advanced Settings
  6. Testing the Integration
  7. Troubleshooting

Overview​

SAML (Security Assertion Markup Language) 2.0 is a standard for implementing Single Sign-On (SSO). The WWPass SAML service acts as the Identity Provider (IdP), providing secure passwordless authentication, while your application acts as the Service Provider (SP), which trusts WWPass authentication.

How It Works​

  1. User attempts to log into your application (SP)
  2. SP redirects user to WWPass SAML IdP
  3. User authenticates via WWPass (passwordless)
  4. WWPass SAML IdP sends a signed SAML assertion back to SP
  5. SP verifies the signature and grants access to the user

Prerequisites​

Before starting configuration, ensure you have:

  • An account in WWPass Management Portal
  • A Provider (application) created in the Providers section
  • Payment configured (active subscription required to activate SAML)
  • Access to SAML settings in your application (SP)
  • Your application supports SAML 2.0 SP

Recommendation: For production environments, configure a custom domain in the Domains section.

Creating a Service Provider​

Step 1: Navigate to SAML Integration Creation​

  1. Log into WWPass Management Portal
  2. Go to the Providers section
  3. Select the required Provider or create a new one
  4. Click "Add Integration" → "New SAML Integration"

Step 2: Choose Configuration Method​

There are two ways to create a SAML SP:

This is the easiest and most reliable method — all parameters are filled automatically.

  1. Get the metadata file from your application (SP):

    • Usually a URL like: https://your-app.com/saml/metadata
    • Or an XML file downloadable from SP admin panel

  2. Copy the XML file contents

  3. Paste the XML into the "SP Metadata XML" field

Example XML structure:

<?xml version="1.0"?>
<md:EntityDescriptor 
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" 
    entityID="https://your-app.com/saml/metadata">
  <md:SPSSODescriptor 
      AuthnRequestsSigned="false" 
      WantAssertionsSigned="true"
      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
            MIIDXTCCAkWgAwIBAgIJAKZ...
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    
    <md:KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
            MIIEFTCCAv2gAwIBAgIUZ9Q...
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
    
    <md:AssertionConsumerService 
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
        Location="https://your-app.com/saml/acs"
        index="0" 
        isDefault="true"/>
        
    <md:SingleLogoutService 
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
        Location="https://your-app.com/saml/slo"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>
  1. Click "Create SAML Integration"

What will be extracted from metadata:

  • Entity ID
  • Assertion Consumer Service URL (ACS URL)
  • Single Logout Service URL (SLS URL) — if specified
  • Signing certificates (SP signing certificates)
  • Encryption certificate (SP encryption certificate) — if specified

Method 2: Manual Entry​

If you don't have metadata XML, fill in the fields manually:

  1. Entity ID* (required)

    • Unique identifier for your SP
    • Usually a URL like: https://your-app.com/saml/metadata
    • Example: https://my-app.example.com/metadata

  2. Assertion Consumer Service URL (ACS URL)* (required)

    • URL where IdP will send SAML response after authentication
    • Example: https://my-app.example.com/saml/acs
    • Must support HTTP-POST binding

  3. Single Logout Service URL (SLS URL) (optional)

    • URL for handling Single Logout requests
    • Example: https://my-app.example.com/saml/slo

  4. Click "Create SAML Integration"

Important: Entity ID and ACS URL must match exactly with settings in your application (SP). Any mismatch will cause authentication errors.

Step 3: Payment Confirmation​

If you haven't configured subscription yet:

  • System will automatically redirect you to Stripe payment page
  • After completing payment, SAML SP will be created automatically

Configuring Your Application (SP)​

After creating SAML SP in WWPass Management Portal, you need to configure your application.

Step 1: Get IdP Parameters​

On your SAML SP page in the "IdP Configuration" section, you'll find:

ParameterValueDescription
IdP Metadata URLhttps://saml.wwpass.com/idp/metadataIdP metadata URL (recommended for auto-configuration)
IdP Entity IDhttps://saml.wwpass.comUnique identifier for WWPass SAML IdP
SSO Endpointhttps://saml.wwpass.com/saml/ssoURL for authentication initiation (HTTP-POST and HTTP-Redirect)
SLO Endpointhttps://saml.wwpass.com/saml/sloURL for Single Logout

Step 2: Configure Your Application (SP)​

Most SAML SPs support metadata import:

  1. In your application's SAML settings, find "Import IdP metadata" or "IdP Metadata URL" option
  2. Paste URL: https://saml.wwpass.com/idp/metadata
  3. Or download XML: click "Download Metadata XML" in WWPass Management Portal and upload to SP

Option B: Manual Configuration​

If automatic import is unavailable, enter parameters manually:

Basic parameters:

  • IdP Entity ID: https://saml.wwpass.com
  • SSO URL / Login URL: https://saml.wwpass.com/saml/sso
  • Logout URL: https://saml.wwpass.com/saml/slo
  • IdP Certificate: Download certificate by clicking "Download Certificate" in "IdP Certificate" section

Protocol settings:

  • Binding: HTTP-POST (preferred) or HTTP-Redirect
  • NameID Format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (or other configured in WWPass)
  • Sign Assertions: Enabled (WWPass always signs assertions)
  • Encrypt Assertions: Optional (configured in WWPass Management Portal)

Step 3: Download and Install IdP Certificate​

  1. In WWPass Management Portal, go to SAML SP page
  2. In "IdP Certificate" section, click "Download Certificate"
  3. Upload the downloaded .pem or .cer file to your application's SAML settings
  4. Ensure the certificate is used for signature verification of SAML assertions

Important: Without properly installed certificate, your application won't be able to verify SAML response signature and will deny access.

Step 4: Verify Name ID Format​

WWPass supports the following Name ID formats:

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (recommended)
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Ensure the format in your SP matches the setting in WWPass Management Portal (default: persistent).

Advanced Settings​

To configure additional parameters, click "Edit Settings" on the SAML SP page.

1. Required Attributes​

Select attributes that must be present in the user's WWPass profile:

  • email — Email address
  • name — Full name
  • given_name — First name
  • family_name — Last name
  • phone_number — Phone number
  • address — Address
  • birthdate — Date of birth
  • gender — Gender
  • company — Company name
  • title — Job title

Note: If a selected attribute is missing from the user, authentication will be rejected with a prompt to complete the profile.

2. Security: Signed Requests from SP​

If your SP can sign AuthnRequest (authentication requests):

Step 1: Enable Signature Verification​

  1. Check "Require signed requests from SP"
  2. In the "SP Signing Certificates" field, paste SP public certificates in PEM format

Example:

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKZ4c3Q...
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIUZ9Q...
-----END CERTIFICATE-----

Step 2: Configure Signature Policy​

  • Require AuthnRequest signature — Reject unsigned requests (403 Forbidden)
  • Sign Response wrapper — Sign not only Assertion but entire Response
    • Recommended for: Okta, Azure AD, ADFS in strict mode
    • Protects against signature wrapping attacks

Step 3: Choose Algorithms (Optional)​

Signature Algorithm:

  • RSA-SHA256 (recommended)
  • RSA-SHA512 (maximum security)
  • RSA-SHA1 (deprecated, not recommended, NIST deprecated 2013)

Digest Algorithm:

  • SHA-256 (recommended)
  • SHA-512 (maximum security)
  • SHA-1 (deprecated, not recommended)

Best Practice: Leave fields empty to automatically accept any secure algorithm (SHA-256 or SHA-512).

3. Assertion Encryption​

For maximum security, you can enable SAML assertion encryption:

  1. Check "Encrypt assertions"
  2. In the "SP Encryption Certificate" field, paste SP public encryption certificate (PEM)
  3. Ensure SP has the corresponding private key for decryption

When to use: If SAML Response is transmitted through untrusted channels or additional data protection is required.

4. Branding​

Customize the appearance of the WWPass authentication page:

  • Logo URL: Link to your company logo (displayed on login page)

    • Format: HTTPS URL
    • Recommended size: 200x50px, up to 1MB
    • Example: https://example.com/logo.svg

  • Background Color: Background color of authentication page

    • Format: HEX (e.g., #2E75E6)
    • Use your brand color palette

When show_consent is enabled (via Management API) or user explicitly requests attribute review:

Consent Flow:

  1. User authenticates via WWPass
  2. Consent screen is shown with:
    • SP name and logo
    • List of attributes to be shared
    • "Authorize" and "Review Attributes" buttons
  3. If user clicks "Review Attributes":
    • Redirected to /saml/attributes/edit
    • User can modify or provide missing attributes
    • System tracks user intent via internal session
  4. After review → consent is saved for this SP
  5. Subsequent logins skip consent screen (until revoked)

Configuration:

  • Set show_consent: true in SP configuration via Management API
  • Consent is stored per user (puid) + SP (sp_id) pair
  • User can revoke consent by clicking "Review Attributes" again
  • Revoked consent triggers attribute review on next login

Use Cases:

  • Privacy compliance: Allow users to see what data is shared
  • Data minimization: Let users opt out of sharing optional attributes
  • Transparency: Build trust by showing clear authorization flow

Note: Consent flow is optional and configured at SP level. If not enabled, users proceed directly to attribute collection (for missing required attributes) without explicit consent screen.

Testing the Integration​

Step 1: Test Authentication​

  1. Open your application (SP) in browser
  2. Click "Sign in with WWPass" or "Login via SAML" button
  3. You should be redirected to WWPass page
  4. Authenticate via WWPass (use WWPass Key or mobile app)
  5. After successful authentication, you'll be returned to your application

Step 2: Verify Transmitted Attributes​

Ensure your application receives and correctly processes SAML attributes:

Standard WWPass attributes:

<saml:Attribute Name="email">
  <saml:AttributeValue>user@example.com</saml:AttributeValue>
</saml:Attribute>

<saml:Attribute Name="name">
  <saml:AttributeValue>John Doe</saml:AttributeValue>
</saml:Attribute>

<saml:Attribute Name="given_name">
  <saml:AttributeValue>John</saml:AttributeValue>
</saml:Attribute>

<saml:Attribute Name="family_name">
  <saml:AttributeValue>Doe</saml:AttributeValue>
</saml:Attribute>

Step 2a: Understand Attribute Sources​

WWPass provides attributes from multiple sources:

SourceAttributesDescription
WWPass AuthenticationpuidAlways included after authentication (persistent user identifier)
WWPass Claims (SPFE) OR User Inputemail, name, given_name, family_name, phone_numberFirst retrieved from WWPass Claims container if available, otherwise collected via attribute editing form if required by SP
User Inputbirthdate, gender, address, company, titleCollected via attribute editing form if required by SP and not present

Claim Mapping: WWPass claims use 1:1 mapping to SAML attribute names (no transformation).

Note:

  • puid is always included in assertions
  • email is always included if available, regardless of NameID format
  • Other attributes are only included if listed in SP's attributes_required configuration AND present in user data

Step 3: Verify IdP Certificate​

IdP Certificate Management:

The WWPass SAML IdP uses automated certificate management via Key Manager. The IdP certificate is:

  • Automatically rotated before expiration
  • Always available at the metadata endpoint (/idp/metadata)
  • Valid for 90 days (typical duration)

To verify certificate validity:

  1. Download IdP metadata:

    curl https://saml.wwpass.com/idp/metadata > idp-metadata.xml

  2. Extract certificate from <ds:X509Certificate> element

  3. Check expiration date:

    openssl x509 -noout -dates -in cert.pem

Important: If you suspect certificate issues, download fresh metadata and update your SP configuration. The WWPass SAML IdP automatically updates certificates before expiration, so SPs should periodically refresh metadata or handle certificate rollovers gracefully.

Troubleshooting​

Issue 1: "Invalid SAML Response" or "Signature verification failed"​

Cause: SP cannot verify SAML response signature.

Solution:

  1. Ensure correct IdP certificate is loaded in SP
  2. Download certificate again: WWPass Management Portal → SAML SP → "Download Certificate"
  3. Check certificate format (should be PEM with -----BEGIN CERTIFICATE----- headers)
  4. Ensure certificate hasn't expired (check expiration in "IdP Certificate" section)

Issue 2: "Invalid ACS URL" or "Invalid Destination"​

Cause: Entity ID or ACS URL in WWPass Management Portal doesn't match SP settings.

Solution:

  1. Compare parameters:
    • In WWPass Management Portal: Entity ID and ACS URL on SAML SP page
    • In your SP: Entity ID and ACS URL in SAML settings
  2. They must match exactly (including http/https, trailing slash /)
  3. If change needed — click "Edit Settings" in WWPass Management Portal

Issue 3: "Required attribute missing" or "User profile incomplete"​

Cause: User hasn't filled required attributes (Required Attributes).

Solution:

  1. Ask user to complete WWPass profile
  2. Or remove requirement in WWPass Management Portal → Edit Settings → Required Attributes

Issue 4: "AuthnRequest signature validation failed"​

Cause: "Require signed requests from SP" option is enabled, but SP certificate not uploaded or incorrect.

Solution:

  1. Go to WWPass Management Portal → Edit Settings
  2. Paste correct SP signing certificates in "SP Signing Certificates" field
  3. Or disable signature verification (uncheck "Require signed requests from SP")

Issue 5: "NameID format not supported"​

Cause: SP requires different NameID format.

Solution:

  1. Go to WWPass Management Portal → Edit Settings → Name ID Format
  2. Select format supported by your SP:
    • persistent — unique permanent user ID (recommended)
    • transient — temporary ID (for single session)
    • emailAddress — email as NameID
  3. Save changes

Issue 6: SP doesn't receive user attributes​

Cause: SP incorrectly parses SAML AttributeStatement.

Solution:

  1. Check SP logs — attributes should be visible in SAML Response
  2. Ensure SP correctly extracts attributes from <saml:Attribute Name="..."> elements
  3. Check attribute mapping in SP settings (e.g., email → user.email)

Issue 7: "Certificate expired" or "Certificate not valid yet"​

Cause: IdP certificate has expired.

Solution:

  1. The WWPass SAML IdP automatically updates certificates via Key Manager
  2. Download new certificate: WWPass Management Portal → "Download Certificate"
  3. Upload new certificate to your SP
  4. If problem persists — contact WWPass support

Managing SAML SP​

Editing Settings​

  1. Go to SAML SP page
  2. Click "Edit Settings"
  3. Make changes
  4. Click "Save Settings"

Reset Configuration​

Warning: This will delete current SP and create a new one. All settings will be lost.

  1. Go to "Danger Zone" section
  2. Click "Reset"
  3. Confirm action

When to use: If configuration is seriously damaged and you need to start over.

Delete SAML Integration​

Warning: This will completely delete SAML SP. Users won't be able to log in via WWPass.

  1. Go to "Danger Zone" section
  2. Click "Disable SAML"
  3. Confirm action

Additional Resources​

Successful Integration Checklist​

  • Provider created and activated in WWPass Management Portal
  • SAML SP created with correct Entity ID and ACS URL
  • IdP certificate downloaded and uploaded to SP
  • IdP metadata imported to SP (or parameters entered manually)
  • Test authentication successful
  • User attributes transmitted correctly
  • (Optional) Branding configured (logo, color)
  • (Optional) AuthnRequest signature configured (if required)
  • (Optional) Assertion encryption configured (if required)

Congratulations! Your SAML integration is ready to use.

Users can now securely log into your application via WWPass without using passwords.