Single Sign-On (SSO) Integration Guide for Organizations

Introduction

What is SSO (Single Sign-On)?

Single Sign-On (SSO) is an authentication process that allows users to access multiple applications with one set of credentials. With SSO, organizations can streamline the login process, enhance security, and improve user experience.

Becoming an Identity Provider (IdP)

Understanding the IdP Role

An Identity Provider (IdP) is a system that authenticates and stores user identity information. By becoming an IdP, your organization can manage user credentials and allow users to log in to HeyPeers seamlessly through your existing authentication system.

Your organization acts as an Identity Provider (IdP), managing user credentials.
You will create, sign, and redirect SAML 2.0 assertions to HeyPeers.

IdP Requirements

SSO capabilities supporting the SAML 2.0 protocol.
Ability to configure SAML settings.

Integration Steps

Generate Private Key and Public Certificate

You'll need to generate a private key and a corresponding public certificate to sign SAML assertions securely. You can use OpenSSL to accomplish this:

Generate a private key:

openssl genpkey -algorithm RSA -out private_key.pem

Create a self-signed certificate using the private key:

openssl req -new -x509 -key private_key.pem -out certificate.pem -days 365

Create the Fingerprint

You'll need to create a fingerprint of the certificate using a hashing algorithm like SHA-256:

openssl x509 -noout -fingerprint -sha256 -inform pem -in certificate.pem

Create and Sign SAML Assertions

Here's a Ruby code example that demonstrates how to create, sign, and send a SAML 2.0 assertion with mapped user attributes to HeyPeers. In this example, we're mapping the following user attributes:

email -> User's email address.
first_name -> User's first name.
last_name -> User's last name.
user_id -> User's username.

require 'ruby-saml'
 
def create_signed_saml_assertion(user)
  settings = OneLogin::RubySaml::Settings.new
 
  # Set your SSO Service URL (HeyPeers will provide this)
  settings.assertion_consumer_service_url = "https://www.heypeers.com/saml/consume?organization_id=#{your_heypeers_organization_id}"
 
  # Set your IdP entity ID
  settings.issuer = "https://your-organization.com"
 
  # SAML 2.0 settings
  settings.protocol_binding = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  settings.name_identifier_format = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
 
  # Load your private key and certificate
  settings.private_key = File.read("private_key.pem")
  settings.certificate = File.read("certificate.pem")
 
  # Create a SAML response with the user's information
  saml_response = OneLogin::RubySaml::Response.new
 
  # Set issuer and name ID
  saml_response.issuer = settings.issuer
  saml_response.name_id = user.email # Change to a persistent identifier if required
 
  # Create and set attributes
  attributes = OneLogin::RubySaml::Attributes.new
  attributes['email'] = user.email
  attributes['first_name'] = user.first_name
  attributes['last_name'] = user.last_name
  attributes['user_id'] = user.username
  saml_response.attributes = attributes
 
  # Sign the SAML response
  saml_response.sign!
 
  # Return the signed XML
  saml_response.to_xml
end

Here is an example in Python. Note this was generated using ChatGPT-4.0. Only use it as a reference or guide.

First install the python3-saml library, which is quite similar to the ruby-saml library used in the Ruby code.

pip install python3-saml

from django.http import HttpResponseRedirect
from onelogin.saml2.auth import OneLogin_Saml2_Auth
from onelogin.saml2.utils import OneLogin_Saml2_Utils
from django.http import HttpRequest
 
def sso_assertion(request: HttpRequest):
    # Prepare the request data
    request_data = {
        'https': 'on',
        'http_host': request.META['HTTP_HOST'],
        'script_name': request.path,
        'server_port': 443,
        'get_data': request.GET.dict(),
        'post_data': request.POST.dict()
    }
 
    # Initialize SAML settings (Replace with your actual settings)
    saml_settings = {
        "strict": True,
        "debug": False,
        "idp": {
            "entityId": "urn:lifespan:sso:idp", # URN (Uniform Resource Name) 
            "singleSignOnService": {
                "url": "https://lifespan.com/sso",
                "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
            },
            "x509cert": "",  # Load from file or environment variable
        },
        "sp": {
            "entityId": "urn:heypeers:sso:sp", # URN (Uniform Resource Name)
            "assertionConsumerService": {
                "url": "https://www.heypeers.com/saml/consume?organization_id=your_heypeers_organization_id",
                "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            },
            "NameIDFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
            "x509cert": "",  # Load from file or environment variable
        }
    }
 
    auth = OneLogin_Saml2_Auth(request_data, saml_settings)
 
    # Assume user is already authenticated in LifeSpan
    name_id = "user.email"  # replace this with the actual email or unique identifier
 
    attributes = {
        'email': "user.email",  # replace with actual user email
        'first_name': "user.first_name",  # replace with actual first name
        'last_name': "user.last_name",  # replace with actual last name
        'user_id': "user.username"  # replace with actual username
    }
 
    # Create SAML Response
    saml_response = auth.create_saml_response(name_id, attributes=attributes)
 
    # Base64 encode the SAML Assertion
    saml_response_encoded = OneLogin_Saml2_Utils.b64encode(saml_response)
 
    # Redirect user to HeyPeers with the SAML Response
    hey_peers_consume_url = f"https://www.heypeers.com/saml/consume?organization_id=your_heypeers_organization_id&SAMLResponse={saml_response_encoded}"
    return hey_peers_consume_url

Redirect the user to HeyPeers

The redirection to HeyPeers with the SAML response typically happens through an HTTP POST request. Here's a step-by-step explanation of how this process occurs:

Here's an example of the HTML code for the form:

<!DOCTYPE html>
<html>
  <head>
    <title>SSO Redirect</title>
  </head>
  <body onload="document.forms[0].submit()">
    <form action="https://www.heypeers.com/saml/consume" method="post">
      <input type="hidden" name="SAMLResponse" value="ENCODED_SAML_RESPONSE"/>
      <!-- Additional parameters if needed -->
    </form>
  </body>
</html>

Replace ENCODED_SAML_RESPONSE with the Base64 encoded SAML response.

Enable SSO in HeyPeers

Enable SSO by contacting customer support at support@heypeers.com.
Login to your HeyPeers organization account.
Navigate to Organization Settings > SSO Settings.
Enter the SAML 2.0 settings:
- SSO URL: Endpoint URL provided by your IdP for SAML requests.
- SSO Certificate Fingerprint: Fingerprint of the certificate used by your IdP.
Save the settings.

Testing and Support

Technical Assistance

If your organization does not have SSO capabilities, you may consider using third-party SSO solutions or consulting with IT professionals to implement SSO.

Test the Integration

Request a test organization from the HeyPeers technical support.
Perform a test login from your test environment.
Verify the login redirects to HeyPeers test environment and successfully logs in the user.

Support

If you encounter any issues or have questions about the integration, please contact HeyPeers support at support@heypeers.com.

FAQs and Troubleshooting

Q: What if I don’t have SSO capabilities? A: You may consider using third-party SSO solutions or consulting with IT professionals to implement SSO.
Q: What if the SSO integration fails? A: Check the SAML settings in both HeyPeers and your IdP. Ensure that the attributes are correctly mapped. If the issue persists, contact HeyPeers support.

API Calendar Meetings