OperationsCommander - https://opscom.wiki

Configuring SAML SSO with OPSCOM

What is Single Sign-On (SSO)

Single Sign-On (SSO) simplifies user access to OPSCOM by allowing them to authenticate using their existing, managed corporate accounts. This eliminates the need for separate OPSCOM usernames and passwords, enhancing convenience and security. This article details the setup and configuration of SAML-based SSO with OPSCOM, explaining the necessary fields, metadata exchange, and user synchronization.  For more general information about SSO and OPSCOM refer to this wiki article.

Prerequisites and Considerations

Implementing SSO with OPSCOM, specifically using SAML (Security Assertion Markup Language), requires coordination between your organization's Identity Provider (IdP) and OPSCOM as the Service Provider (SP).

  • Paid Feature: SSO is a paid feature. You must have the setup fee and recurring fees negotiated before proceeding. Contact your Sales Representative or email support@ops-com.com to initiate this.

  • Login Sources: You must first follow the instructions to set up Login Sources within OPSCOM, as SSO will be configured as a specific login source.

  • User Management Strategy: Consider the following:
    • Will you have different Login Sources (e.g., Students/Staff use SSO, but Public Users do not)?
    • Will login sources vary by user type?
    • How do you want to initially get your users into OPSCOM (e.g., pre-import vs. on-the-fly creation)?
    • Do you want users to be created automatically upon their first SSO login?
    • Do you want to keep user information synchronized with your Identity Provider regularly, or will it be a one-time import?
    • What user profile data/fields do you want synchronized between your SSO system and OPSCOM?
    • Can you take advantage of the UserPush APIs for proactive user synchronization?

Your OPSCOM Client Success team will be happy to discuss these options to ensure a smooth and successful setup.

Once the prerequisites are addressed, the SAML setup involves configuring fields for both OPSCOM (as the Service Provider) and your external SAML system (as the Identity Provider).

Configuring SAML Setup

  1. Hover over System Configuration, Users, and click Login Sources.
  2. Click the pencil icon to edit your login source you created already as mentioned above. You should already have configured the login source to the point of the Unique ID field.

The settings below must be filled out correctly and saved before you will see the Metadata tab to continue.

When OPSCOM generates your SP metadata, it is available as a live URL — not just a downloadable file. The metadata URL follows this pattern:

https://[your-domain]/auth/saml2/[ENTITY_ID]/metadata

We strongly recommend providing your Identity Provider with this URL rather than a downloaded XML file. When an IdP is configured to pull from a live URL, it will automatically fetch fresh metadata and the integration stays current.

If you upload a static XML file to your IdP instead, be aware that the metadata contains a validUntil timestamp (calculated from the cacheDuration of 7 days from the time it was fetched). An IdP that strictly enforces this value may reject the metadata after that window. In practice, most enterprise IdPs — including Azure AD — do not enforce validUntil on uploaded SP metadata, but it is still better practice to use the live URL wherever possible.

Azure AD note: When configuring the Enterprise Application in Azure, look for the option to enter a Federation Metadata URL rather than uploading a file. This is found in the Basic SAML Configuration section.

Service Provider Fields (Configured in OPSCOM)

These fields define how OPSCOM will interact with your Identity Provider.

  • Unique ID:  Required - This is a crucial part of the XML communication between OPSCOM and your SAML system. It is supplied by your SAML system and is the value OPSCOM uses to match against its internal UniqueID field to identify a user.
  • Entity ID for Service Provider:  Required - This value defines the unique SAML integration path within the URL in the metadata. If your OPSCOM system has more than one SAML integration, each Entity ID needs to be unique. The value you supply will appear in the integration path like this: https://client.OPSCOM.com/auth/saml2/ENTITY_ID_FIELD/acs.  Only add the ENTITY_ID_FIELD not the whole URL.  
  • SP x509 Certificate: (Optional) This is the certificate OPSCOM will use to sign or decrypt SAML messages. It is generated within your OPSCOM or IdP setup — it is not the same as the IdP's certificate. You only need to configure this field if you are enabling signed logout requests, signed logout responses, or encrypted assertions. All three of those features are disabled by default.
  • Private Key: (Optional)  Required only if the SP certificate above is in use. Leave blank for standard configurations.
Identity Provider Fields (Configured in OPSCOM, Values from Your SAML System):

These fields capture information from your external SAML system (Identity Provider). You will find these values within your SAML system's metadata (e.g., often displayed under Federation → Show Metadata on your SAML installation page).

  • You will input values such as the Identity Provider's Entity ID, Single Sign-On URL (SSO URL), and x509 Certificate (which is often different from the one provided for the Service Provider).

⚠️ Important — Certificate Mismatch: The IdP x509 Certificate field must contain the certificate issued by your Identity Provider — for example, the certificate embedded in Azure's Federation Metadata XML. Do not copy the SP certificate into this field. Entering the wrong certificate here will cause SAML assertion validation to fail silently, and users will be unable to log in. If in doubt, download your IdP's Federation Metadata XML and extract the certificate from within it.

Once these settings have been completed and saved in OPSCOM, you will gain access to additional tabs: MetaData, Synchronization, and Translations.

 

Additional Settings Reference

When you open your Login Source configuration, you will see several additional fields below the core SP and IdP sections. The defaults are appropriate for most integrations, but the following are worth understanding:

Setting Default What It Does
Requested Auth Context false When set to false, OPSCOM does not specify an authentication method in its request to the IdP — the IdP decides. Set to true to require password-based authentication (PasswordProtectedTransport). Leave as false for most Azure AD integrations.
Require Name ID Policy Enabled Includes a NameIDPolicy element in the SAML request, specifying the Name ID Format. Disable this if your IdP is Microsoft ADFS — ADFS frequently rejects the NameIDPolicy element and returns an InvalidNameIDPolicy error. Azure AD (Entra ID) handles it correctly and this should remain enabled.
Require Encrypted Assertions Disabled Requires the IdP to encrypt SAML assertions. Only enable if your IdP supports it and your SP certificate and private key are configured. Not required for standard Azure AD integrations.
Sign Logout Requests / Responses Disabled Requires the SP certificate and private key to be configured. Not required for standard Azure AD integrations.

Using this Feature

image.png
Metadata Tab

The Metadata tab in OPSCOM provides the XML code that you will need to provide to your Service Provider (OPSCOM, in the context of SAML communication from your IdP's perspective). This XML contains all the necessary information for your Identity Provider to communicate correctly with OPSCOM.

image.png

Sample XML File

Sample XML File Explanation: When your external system (e.g., a SimpleSAMLPhp service set up as the identity provider) sends a response back to OPSCOM, it includes an saml:AttributeStatement tag containing several attributes. These attributes are required for OPSCOM to match to a user within its system. The most important field in this attribute section is the value used as the permanently unique identifier for a user. For example, if the XML response shows [uid] => Array ( [0] => 6ddf4027-3397-4e45-8628-0189f60fe91e ), then uid should be entered as the Unique ID Field in your Identity Provider Fields configuration within OPSCOM. If the unique ID is something else, such as SAMaccountName, then that should be used instead.

... DEV-2K8 - DEBUG: Saml2 Incoming User Array ( [uid] => Array ( [0] => 6ddf4027-3397-4e45-8628-0189f60fe91e ) [full name] => Array ( [0] => Sarah Knowles ) [email] => Array ( [0] => sknowles@tomahawk.ca ) ) []

<?xml version="1.0"?>
        <samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_aa1963115aa6490e728c7376f4c8849813bbb...">
          ...
          <saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="_9efd79bf6425983ee9176f3d33a99d1a9176180...">
            ...
            <saml:Subject>
              <saml:NameID SPNameQualifier="MinionOpsComStaff" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">_7a426e0be71f14c1f349db00d7d543b6f7dcb52baa</saml:NameID>
              <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData NotOnOrAfter="2021-08-24T16:00:41Z" Recipient="https://minion-3.dev.parkadmin.com/auth/saml2/MinionOpsComStaff/acs" InResponseTo="ONELOGIN_bb8a09203c888cf59af4c621a71cfa8f7559c016"/>
              </saml:SubjectConfirmation>
            </saml:Subject>
            <saml:Conditions NotBefore="2021-08-24T15:55:11Z" NotOnOrAfter="2021-08-24T16:00:41Z">
              <saml:AudienceRestriction>
                <saml:Audience>MinionOpsComStaff</saml:Audience>
              </saml:AudienceRestriction>
            </saml:Conditions>
            <saml:AuthnStatement AuthnInstant="2021-08-24T15:34:46Z" SessionNotOnOrAfter="2021-08-24T23:34:46Z" SessionIndex="_a7a68666092117d24aab8adecf1b0830622855b85...">
              <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
              </saml:AuthnContext>
            </saml:AuthnStatement>
 
 
            <saml:AttributeStatement>
              <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">6ddf4027-3397-4e45-8628-0189f60fe91e</saml:AttributeValue>
              </saml:Attribute>
              <saml:Attribute Name="full name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">Sarah Knowles</saml:AttributeValue>
              </saml:Attribute>
              <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">sknowles@tomahawk.ca</saml:AttributeValue>
              </saml:Attribute>
            </saml:AttributeStatement>
 
 
          </saml:Assertion>
        </samlp:Response>

⚠️ Do not rename your Login Source after users have been associated to it. The Login Source value is stored against every user record created via SSO. If you change it, those users will no longer be matched to this login source on their next login attempt, effectively locking them out. If a rename is ever necessary, contact OPSCOM Support to arrange a coordinated update of all affected user records.

Synchronization Tab

The Synchronization tab allows you to configure how user information is managed between your SSO system and OPSCOM.

  • Auto Create/Update User: To begin, ensure you enable the Auto Create/Update User checkbox. This feature allows OPSCOM to automatically create new user profiles when they first log in via SAML, if they don't already exist in OPSCOM. It also enables the system to update existing user information.
  • User Attribute Mapping: On this tab, you will map the user attributes from your SSO system (your Identity Provider) to the corresponding fields in OPSCOM. For example, your SSO system might send "full name" and "email" attributes, which you would map to OPSCOM's firstName, lastName, and email fields.
  • Any field that is mapped and has a value from your SSO side should get updated to the value from SAML.

After you have provided the information in each field, click Save Changes.

Your users will then begin to be created or updated automatically upon their SSO login attempts. If any of the supplied fields are incorrect or don't match, the corresponding information will be blank in OPSCOM when the user logs in, or it will remain unchanged if the user already existed.

What to enter in the field mapping boxes: Each field mapping box accepts the attribute name exactly as your Identity Provider sends it in the SAML assertion. These names vary between IdP systems. The sample values shown (such as full name, email, uid) are from a SimpleSAMLphp test installation and will be different for other identity providers.

For Azure AD (Microsoft Entra ID), the attribute names depend on how the claims were configured in the Enterprise Application. Azure uses two formats:

  • Short-name format (if you created custom claims): e.g., first_name, last_name, emailaddress
  • Full URI format (Azure defaults): e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

To confirm exactly what your Azure AD tenant is sending, use the Test button on the Single sign-on page of your Azure Enterprise Application. The test result displays every claim name and value as it will arrive at OPSCOM.

⚠️ Azure AD does not send a combined "full name" attribute by default. If you map the First Name field to a full name or displayName attribute, the user's entire display name (e.g., "Sarah Knowles") will be stuffed into the first name field. Map First Name and Last Name to separate attributes (givenname / surname, or first_name / last_name if configured as custom claims in Azure).

image.png

The exact sample values from our test system may differ from your actual SAML system attributes.

Translations Tab

The Translations tab allows you to customize the text displayed on your login button from the user side. You can create as many different translations as are available in your system (e.g., English and French). This ensures that the SSO login experience is localized for your users.

image.png

Error Handling: CommonPproblems and Their Causes

Best Practices & Considerations

  • Coordinate with IT/SAML Administrator: Successful SSO implementation requires close collaboration with your organization's IT department or the administrator of your SAML Identity Provider. They will provide the necessary metadata and attribute names.
  • Unique User Identifiers: Ensure the Unique Identifier chosen for matching users is truly unique and persistent within your SSO system. Incorrect or changing identifiers will lead to duplicate accounts or login failures.
  • Attribute Mapping Accuracy: Carefully map all desired user attributes from your Identity Provider to OPSCOM. Inaccurate mapping will result in missing or incorrect user data.
  • Test Thoroughly: After initial configuration, conduct thorough testing with various user types and scenarios to ensure seamless login, proper user creation/updates, and correct data synchronization.
  • User Experience: Clearly communicate the new SSO login process to your users. Provide instructions on how to access OPSCOM via SSO and address any potential questions.
  • Error Handling: Be prepared to troubleshoot potential issues. Common problems include incorrect Entity IDs, expired certificates, or mismatched attribute names. The SSO system logs can be invaluable for diagnosing such issues.
  • Use the Metadata URL, not a downloaded file: When providing your SP metadata to an Identity Provider, share the live metadata URL from the Metadata tab rather than a downloaded XML file. This avoids the need to re-upload metadata when the validUntil timestamp rolls forward, and ensures the IdP always has current configuration data.
  • Keep your SP and IdP certificates straight: A very common configuration error is entering the SP certificate in the IdP certificate field, or vice versa. The SP certificate comes from OPSCOM (or is generated during your Azure Enterprise Application setup). The IdP certificate comes from your Identity Provider's metadata. They are different certificates issued to different entities — treat them as such.
Take Command of Your Parking and Security - https://OperationsCommander.com

Revision #21
Created 21 May 2024 11:20:41
Updated 16 June 2026 11:30:56