Setup Guide: OneLogin SAML SSO | Axero Documentation

This guide provides step-by-step instructions to configure OneLogin for Single Sign-On (SSO) with Axero using SAML 2.0. Users will authenticate using their OneLogin credentials, with account management handled in Axero.

Overview

• Preparation
• Step 1: Configure OneLogin
• Step 2: Configure Axero
• Step 3: Test SSO Integration
• Optional: Add Custom Attributes
• Troubleshooting

Preparation

Before you start, ensure you have:

• Administrator access to your OneLogin portal
• Site Administrator access to your Axero site
• Confirmed the following Axero System Properties are configured:
  • Go to Control Panel > System > System Properties
  • EnableAutoLoginViaSaml = False
  • SAMLAutoUserCreation = True
  • SAMLAutoUserUpdate = True
  • SAMLUserEmailMatch = False
• Adjusted the following settings for your planned usernames:
  • Go to Control Panel > System > General Settings > Advanced Settings.
  • Update Minimum length for username and Maximum length for username as needed to accommodate your planned username format.

Adjusting these settings will help prevent potential errors during user creation and login.

Step 1: Configure OneLogin

1. Log in to your OneLogin Admin portal.
2. Go to Applications > Applications and click Add App.
   
3. Search for and select SCIM Provisioner with SAML (SCIM v2 Core).
   
4. Enter a display name for your application (for example, "Axero") and click Save.
   
5. On the Configuration tab, enter the following:
   1. SAML Audience URL: Enter your Axero site URL (for example, https://your-axero-site.com).
   2. SAML Consumer URL: Enter your Axero site URL followed by /SAML/AssertionConsumerService.aspx (for example, https://your-axero-site.com/SAML/AssertionConsumerService.aspx).
   3. SCIM Base URL: Enter your Axero site URL followed by /api/scim/v2 (for example, https://your-axero-site.com/api/scim/v2). OneLogin requires this URL to be set even though you're only setting up SAML SSO now.
      
   4. Click Save.
      
6. On the Parameters tab, configure these required attributes:
   1. First Name
      1. Click + to add a new parameter.
         
      2. Set Field name to "FirstName".
      3. Select "Include in SAML assertion".
      4. Click Save.
      5. Select "First Name" from the Value dropdown.
      6. Click Save.
         
   2. Last Name
      1. Click + to add a new parameter.
      2. Set Field name to "LastName".
      3. Select "Include in SAML assertion".
      4. Click Save.
      5. Select "Last Name" from the Value dropdown.
      6. Click Save.
         
   3. Email
      1. Click + to add a new parameter.
      2. Set Field name to "Email".
      3. Select "Include in SAML assertion".
      4. Click Save.
      5. Select "Email" from the Value dropdown.
      6. Click Save.
         
   4. Click Save to save your changes.
      

   Note: These attributes are case-sensitive and must match exactly as shown above for proper mapping in Axero.

7. On the SSO tab:
   1. Under SAML Signature Algorithm, select SHA-256.
      
   2. Click Save.
   3. Return to the SSO tab.
   4. Record the following values:
      • Issuer URL
      • SAML 2.0 Endpoint (HTTP)
      • SLO Endpoint (HTTP)
        
        
   5. Under X.509 Certificate, click View Details.
      
   6. Under X.509 Certificate, select "X.509 PEM" and click Download to download the certificate.
      
   7. Share the certificate in your support ticket, and Axero will convert it to the correct format and upload it to your Axero site.

Step 2: Configure Axero

1. Log in to your Axero site as a Site Administrator.
2. Navigate to Control Panel > System > Single Sign-On.
   
3. Select SAML as the authentication method and click Save.
   
4. Enter the following information from the OneLogin SSO tab:
   • Partner Identity Provider URL: Enter the Issuer URL.
   • Single Sign-On Service URL: Enter the SAML 2.0 Endpoint (HTTP).
   • Relying Party Trust Identifier: Enter your Axero site URL.
   • Single Logout Service URL: Enter the SLO Endpoint (HTTP).
     
5. Click Update to save your changes.
   
6. Click the Data Mapping tab and select SAML from the dropdown.
   
7. Update the following mappings so that the property names match exactly as shown:

   SAML Attribute Mappings

   Property Name	Field
   FirstName	First name
   LastName	Last name
   Email	Email

   Note: These mappings are case-sensitive and must match exactly as shown above for proper mapping in Axero.

8. Delete any other mappings and click Update to save your changes.
   

Step 3: Test SSO Integration

1. In OneLogin:
   1. Assign yourself to the Axero application.
      1. Go to Users > Users.
      2. Select yourself from the list.
      3. Click the Applications tab.
      4. Click +.
         
      5. Select Axero from the dropdown and click Continue.
         
      6. Click Save.
   2. Ensure your user profile has the required attributes (first name, last name, email).
2. Test SSO login:
   1. Follow the instructions for adding a "Login via SSO" button to your login page.
   2. Open a new incognito/private browser window.
   3. Navigate to your Axero site's login page.
   4. Click the Login via SSO button.
   5. Verify successful authentication and profile data mapping.

Optional: Add Custom Attributes

1. In OneLogin, go to your application's Parameters tab.
2. Click + to add a custom attribute.
3. Enter the Field name from the following list:

   SAML Attribute Mappings

   Field Name	Value
   ProfilePhoto	Profile Picture
   Phone	Phone
   ManagerEmail	Manager Email
   Company	Company
   Department	Department
   Title	Title

4. Select "Include in SAML assertion".
5. Click Save.
6. Select the corresponding value for the field name in step 3 from the dropdown.
7. Repeat steps 2-6 for each custom attribute.
8. Click Save.
   
9. In Axero, go to Control Panel > System > Single Sign-On > Data Mapping.
10. Select SAML from the dropdown.
11. Click Add to add a new mapping.
    
12. Add a mapping for each desired attribute, ensuring the property names match precisely:

    SAML Attribute Mappings

    Property Name	Field
    ProfilePhoto	Profile photo
    Phone	Phone
    ManagerEmail	Reports to
    Company	Company
    Department	Department
    Title	Occupation

13. Click Update to save your changes.
    
14. Test the new attribute mappings by logging in via SSO.

Troubleshooting

• User Deprovisioning: OneLogin SAML integration does not automatically deactivate users in Axero. Deactivate users manually in Axero or use SCIM provisioning.
• Role Mapping: To map OneLogin roles/groups to Axero roles, use custom attributes and configure them in the Data Mapping section.