Setup Guide: Okta SAML SSO | Axero Documentation

This guide explains how to configure Okta for Single Sign-On (SSO) with Axero using SAML 2.0. Users will log in with their Okta credentials, and their accounts will be managed in Axero.

To enable automatic user provisioning, see the Okta SCIM Provisioning Setup Guide.

Overview

• Preparation
• Step 1: Configure Okta
• Step 2: Configure Axero
• Step 3: Test SSO Integration
• Optional: Add Custom Attributes
• Optional: Add Okta Groups
• Additional Considerations

Preparation

Before you start, ensure you have:

• Administrator access to your Okta organization
• 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 Okta

1. In the Okta Admin Console, go to Applications > Applications.
   
2. Click Browse App Catalog.
   
3. Search for Communifire.
4. Click on Communifire.
   
5. Click Add Integration.
   
6. Update the Application label (for example, "Axero: [Your Site Name]").
   
7. Enter your site URL (including https://) in Base URL. Delete any trailing slashes.
   
8. Click Done.
   
9. Click the Sign On tab and select More details.
   

Step 2: Configure Axero

1. Open a new browser tab and navigate to Control Panel > System > Single Sign-On on your Axero site.
   
2. Select SAML as the authentication method and click Save.
   
3. Enter the following information:
   • Partner Identity Provider URL: Enter the Issuer URL from Okta
   • Single Sign On Service URL: Enter the Sign on URL from Okta
   • Relying Party Trust Identifier: Enter your Axero site URL and remove any trailing slashes
   • Single Logout Service URL: Enter the Sign out URL from Okta
     
   • Partner Identity Certificate (CER): Download the Signing Certificate from Okta and upload it here
     
4. Click Update to save your changes.
   

Step 3: Test SSO Integration

1. Assign yourself to the Axero application in Okta:
   • In the Okta Admin Console, go to your Axero application.
   • Click on the Assignments tab.
     
   • Click Assign and choose Assign to People.
     
   • Select your user account and click Assign, then Save and Go Back.
     
   • Click Done when finished.
2. Test SSO login
   • Follow the instructions for adding a "Login via SSO" button to your login page.
   • Open an incognito/private browser window to prevent conflicts with active sessions.
   • Navigate to your Axero site's login page.
   • Click the Login via SSO button.
   • You should be redirected to the Okta login page.
   • Enter your Okta credentials.
   • Upon successful authentication, you should be redirected back to Axero and logged in.
   • If you receive an error, log in to your site using your Axero username and password, go to the Single Sign On page, click the Data Mapping tab, select SAML in the Type dropdown, and click the Reset button to reset to the default settings. Open a new incognito/private window and test logging in via SSO again.
3. Verify user attributes
   • Once logged in, check your user profile in Axero.
   • Confirm that the default attributes mapped from Okta (First Name, Last Name, Email) are correctly displayed.
4. Test SSO logout
   • Click the logout button in Axero.
   • Verify that you are logged out of Axero. You may still be logged into your Okta account.
5. Test user provisioning
   • In Okta, assign a new user to the Axero application.
   • Have the new user log in to Axero via SSO.
   • Verify that a new user account with the correct attributes is created in Axero.

Optional: Add Custom Attributes

1. In the Okta Admin Console, go to your Axero application.
2. Click the Sign On tab.
   
3. In the Settings section, click Edit.
   
4. Click Attributes (Optional) to expand the section.
   
5. Scroll down to the Attribute Statements section.
6. Add additional attribute statements as needed. For example:

   Name	Name format	Value
   Company	Unspecified	user.organization
   Department	Unspecified	user.department
   Title	Unspecified	user.title
   TelephoneNumber	Unspecified	user.primaryPhone
   Manager	Unspecified	user.manager
   HireDate	Unspecified	user.hireDate

   
   Note: For the Manager attribute, values must be either email addresses (e.g., john.doe@example.com) or strings formatted as FirstName LastName (e.g., "John Doe"). Incorrect formats may cause mapping errors or prevent proper manager relationships from being established.
   Note: Hire Date is a custom Okta attribute added with the Profile Editor. Ensure the format of profile values matches your Axero site setting (e.g., "MM/dd/yyyy") at Control Panel > System > General Settings > Localization Settings > Date Format.
   
7. Click Save to update the SAML settings.
   
8. In Axero, go to Control Panel > System > Single Sign-On > Data Mapping.
   
9. Select SAML as the Type.
10. Click Add to add a new mapping. Ensure the property name is identical to the attribute name you entered in step 6. Select your site's corresponding profile field on the right.
11. Delete any unused mappings.
12. Click Update to save your changes.
13. Test the new attribute mappings by logging in via SSO and verifying that the additional attributes are correctly displayed in the user's Axero profile.

Optional: Add Okta Groups

Okta Groups use the Groups Attribute type and are sent to Axero as a comma-separated list. These groups can be used with Personas to manage space membership.

1. In the Okta Admin Console, go to your Axero application.
2. Click the Sign On tab.
   
3. In the Settings section, click Edit.
   
4. Expand the Attribute Statements (Optional) section.
   
5. Scroll down to the Group Attribute Statements (Optional) section.
   
6. Add the following Group Attribute Statement:
   • Name: OTG-Groups
   • Name format: Unspecified
   • Filter: Matches regex
   • Value: .*
   
   Note: The regex ".*" will include all groups. You can use a more specific regex to filter groups if needed.
7. Click Save to update the SAML settings.
   
8. In Axero, go to Control Panel > System > Single Sign-On > Data Mapping.
9. Select SAML as the Type.
10. Click Add to create a new mapping for groups:
    • Set the Property Name to "OTG-Groups" (matching the name used in Okta).
    • Select the appropriate Axero field for group mapping (e.g., "Groups").
    
11. Click Update to save your changes.
12. Test the group mapping:
    • Assign a user to one or more groups in Okta.
    • Have the user log in to Axero via SSO.
    • Verify that the user is added to the corresponding Spaces or Roles in Axero based on their Okta group memberships.

Additional Considerations

• User Deprovisioning: Okta SAML does not automatically deactivate users in Axero.
• Profile Images: Okta does not support syncing profile images. Consider using Axero's REST API to update images.
• User Syncing: For real-time updates and more robust user lifecycle management, consider implementing Okta's SCIM provisioning with Axero.