Guide to Setting Up SAML Single Sign-On (SSO) on Your Infigo Storefront | BG_SSO_001
Welcome to the step-by-step guide to setting up SAML 2.0 Single Sign-On (SSO) for your Infigo storefront. This guide is designed to help you integrate your Identity Provider (IDP) with Infigo, enabling seamless authentication for your users.
A glossary of key technical terms in relation to SAML has been provided in a section below the main article.
Prerequisites
Before you begin, ensure you have the following:
- Administrative Access to Infigo: You need admin privileges on your Infigo storefront as a Storefront Administrator to configure SAML settings.
- Access to an Identity Provider (IDP): Administrative rights to configure SAML applications on the chosen IDP (e.g., SSOcircle, Active Directory, OneLogin).
- Knowledge of User Attributes: Understanding of which user attributes (email, username, first name, last name, etc) are available from your IDP and you would like to also pass to Infigo.
- SAML Metadata from IDP: The metadata XML file or metadata URL provided by your IDP.
- Access to your Server: Administrative access to the server, with permissions to manage certificates.
Step 1: Gather Identity Provider Information
Note: The steps to configure your IDP may vary depending on the provider. The following steps use SSOcircle as an example.
Obtain IDP Metadata
- Metadata URL: For SSOcircle for example, the metadata URL is:
https://idp.ssocircle.com/meta-idp.xml
- Metadata XML File: Alternatively, download the metadata XML file from your IDP's console.
Identify the IDP Entity ID
- Open the metadata XML file.
- Look for the
entityID
attribute.
- For SSOcircle, it is:
http://idp.ssocircle.com
Determine User Attributes
- Identify which user attributes are available from your IDP.
- Common attributes include
FirstName
, LastName
, EmailAddress
, and Username
.
Step 2: Enable SAML in Infigo
Access SAML Settings
- Log in to your Infigo admin panel.
- Navigate to Configuration > Settings > SAML 2.0 Settings.
- If you cannot any of the settings mentioned in this guide, please contact Infigo Support who can enable it for you.
Enable SAML Client
- Check the box labeled SAML client enabled undr the SAML 2.0 Configuration heading.
Set the Service Provider (SP) Name (Entity ID)
- In the Service provider name field, enter a unique identifier for your storefront.
- Example:
urn:InfigoServiceProvider
- This will become your SP Entity ID.
Enter the Service Provider Server URL
- Check your storefront's URL in the Service Provider Server URL field.
- Example:
https://yourstorefront.com/
- Important: Ensure that the URL is correct and uses HTTPS.
- This is taken from the General Settings page of your Infigo storefront.
Save Your Settings
- Click the Save button to apply your changes.
Step 3: Install and Configure Certificates on Your Server
To ensure secure communication and verify identities between your Infigo storefront (SP) and your IDP, you need to install and configure the necessary certificates on your server.
Add a Certificates System to the Server
- Open the Microsoft Management Console (MMC):
- Click on the Start menu.
- Type
mmc.exe
in the search bar.
- Right-click on
mmc.exe
and select Run as administrator.
- Add the Certificates Snap-in:
- In the MMC window, navigate to File > Add/Remove Snap-in....
- From the list of available snap-ins, select Certificates.
- Click Add >.
- Select the Certificate Snap-in:
- Choose Computer account when prompted.
- Click Next.
- Select Local computer.
- Click Finish.
- Click OK to close the snap-in selection window.
Optional Step: Install a CA Certificate for Self-Signed Certificates
If you're using self-signed certificates, you need to install your Certificate Authority (CA) certificate to establish trust.
- Obtain the CA Certificate:
- Ensure you have the CA certificate file (typically with a
.cer
extension).
- Import the CA Certificate:
- In MMC, expand Certificates (Local Computer).
- Expand Trusted Root Certification Authorities > Certificates.
- Right-click on Certificates under Trusted Root Certification Authorities.
- Go to All Tasks > Import....
- Complete the Certificate Import Wizard.
- A message should confirm the successful import.
Install the Private Key Pair Certificate
You need to install your service provider's certificate that includes the private key.
- Obtain Your Certificate:
- Ensure you have the certificate file (typically with a
.pfx
extension) containing the private key.
- If you don't have a
.pfx
file, you may need to convert your existing certificate using tools like OpenSSL.
- Import the Certificate:
- In MMC, locate a node to install the certificate (such as Trusted Publishers.)
- Right-click on Trusted Publishers.
- Go to All Tasks > Import....
- Complete the Certificate Import Wizard:
- Enter the password for the private key when prompted.
- A message should confirm the successful import.
Assign Permissions to the Certificate
For your Infigo application to access the private key, you need to grant the necessary permissions.
- Locate the Certificate:
- In MMC, drag and drop your imported certification from their import location to Personal > Certificates. Permission changes can only be done under the Personal > Certificates node.
- Manage Private Keys Permissions:
- Right-click on your certificate.
- Go to All Tasks > Manage Private Keys....
- In the Groups and Users dialog, click on Add....
- Add the Web Service Account:
- In the Select Users, Computers, Service Accounts, or Groups window:
- Enter / search for the username of the website account.
- Click Check Names to verify the account.
- Click OK.
- Set Permissions:
- In the Permissions list, ensure that Read and Full Control are allowed for the added user.
- Click OK to apply the permissions.
- Optional: Move the Certificate Back:
- If you initially imported the certificate into a different node, you can drag and drop it back to its original location after setting the permissions.
Step 4: Configure SAML Settings in Infigo
Configure Customer Identification Method
- Decide how Infigo will identify users during SAML authentication.
Options:
- NameID - Automatic: Uses the
NameID
element from the SAML assertion.
- Attribute Statement - Email: Uses an attribute named
email
from the SAML assertion.
- Attribute Statement - Username: Uses an attribute named
username
.
Configure Mapping Settings
- Create users if not present: Check this option to allow Infigo to create user accounts when new users log in via SSO.
- Customer Properties Mapping: Map SAML attributes to Infigo customer properties. This allows additional information to be sent to Infigo and maintain up to date information in user accounts.
- The below image shows an example of SAML attributes sent with a log in request.
- These SAML attribute names, such as
FirstName
or EmailAddress
can be mapped to matching fields within Infigo
- To add a mapping:
- Click Add New Mapping under Customer Properties Mapping.
- Enter the SAML attribute name and select the corresponding Infigo field.
- External Customer Role Mapping allows you to apply one or more Infigo customer roles to a user logging in via SAML.
- Customer Information to be Updated on Login allows you to specify Infigo customer attributes that you would like to be updated on a customer's account each time a user logs in.
Configure Security Settings
- Allow Unsolicited Responses: Check this if your IDP initiates the login process (IDP-initiated SSO).
- Enable Assertion Signature Check: Check this to ensure SAML assertions are signed and verified.
- Validate Trust Chain: Check this if your IDP uses a trusted certificate authority.
Input Identity Provider Configuration
- IDP Entity ID: Enter the Entity ID from your IDP metadata.
- For SSOcircle, for example:
http://idp.ssocircle.com
- Use Identity Provider Metadata Link: Check this option if you have a metadata URL.
- IDP metadata link: Enter the metadata URL.
- For SSOcircle:
https://idp.ssocircle.com/meta-idp.xml
- Identity Provider Metadata XML: Alternatively, paste the metadata XML content if you have it.
Save Your Settings
- Click the Save button to apply all configurations.
Step 5: Provide Service Provider Metadata to Your IDP
Access the Storefront Metadata Link
- In the SAML settings page, find the Storefront Metadata link.
- Alternatively, you can provide the full Storefront Metadata XML, also found in the SAML2.0 Settings page.
Provide SP Metadata to Your IDP
- Send this link or download the XML and provide it to your IDP administrator.
- This allows the IDP to recognize your Infigo storefront as a trusted service provider.
Step 6: Configure Your Identity Provider
Note: The steps may vary depending on your IDP. The following is a general guide.
Add Infigo as a Service Provider
- Log in to your IDP's administrative console.
- Create a new SAML application or service provider entry.
- Use the SP Entity ID and ACS URL from your Infigo settings:
- Entity ID: As entered in Infigo (e.g.,
urn:InfigoServiceProvider
).
- ACS URL
Import SP Metadata
- If your IDP supports it, import the SP metadata using the link or XML provided.
Configure User Attributes
- Map the user attributes to be sent in the SAML assertion to match the Customer Properties Mapping in Infigo.
- For example, ensure that the attributes
FirstName
, LastName
, and EmailAddress
are included.
Assign Users to the Application
- Select which users or groups should have access to the Infigo application.
Finalize IDP Settings
- Save all configurations and ensure the application is active.
Step 7: Test the SSO Integration
Initiate SSO Login
- Navigate to your Infigo storefront's login page.
- If Login Mode is set to Button In Login, click on the Login with SAML button.
- If automatic redirection is enabled, you will be redirected to the IDP login page.
Authenticate with Your IDP
- Log in using your IDP credentials.
Verify Access to Infigo
- After successful authentication, you should be logged into your Infigo storefront.
Troubleshoot if Necessary
- If you encounter issues, double-check:
- Entity IDs and URLs on both Infigo and your IDP.
- User attribute mappings.
- Certificates and security settings.
Use SAML Tracer (Optional)
- Install the SAML Tracer browser extension to inspect SAML messages for troubleshooting, however this information can all be obtained from your browsers developer capabilities.
Additional Configuration Options
Logout Mode
- Choose how the logout process is handled:
- Logout from Infigo only: Users remain logged into the IDP.
- Logout from Infigo and the IDP: Users are logged out of both.
Login Mode
- Determine how users initiate SSO login:
- Button In Login: Users click a button to log in via SSO.
- Automatic Redirect: Users are automatically redirected to the IDP when accessing the login page.
Support and Assistance
If you need help during any step of this process, please reach out to our support team. We're here to ensure your SSO integration is successful.