Skip to main content

Configuring SAML SSO with OPSCOM

What

The isConfiguring SingleSAML Sign-OnSSO (SSO)

with

SingleOPSCOM Sign-On (SSO)feature simplifies user access to OPSCOM by allowing them to securely authenticate using their existing, managed corporate accounts. ThisIts eliminatesprimary purpose is to eliminate the need for separate OPSCOM usernames and passwords, significantly enhancing user convenience and security.overall system security through automated synchronization. This article detailsis theintended setupfor OPS-COM administrators.

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

Configuration

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

Single

Sign-On
  • Paid Feature: SSO(SSO) is a premium paid feature. You must have the setup fee and recurring fees negotiated before proceeding. Contactwith your Sales Representative orbefore emailproceeding. support@ops-com.comYou must also configure your baseline login sources prior to initiatecompleting this.this setup.

    Admin Side:

    Configuring the Login Source

    1. Hover over System Configuration, hover over Users, and click Login Sources.

    2. 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.

    3. 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 youpreviously created alreadySSO aslogin mentionedsource.

    above.
    3. You
  3. should

    Fill already have configuredout the loginService source to the point of the Unique ID field.

The settings below must be filled out correctlyProvider 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 withfields thisdetailed URLbelow.

rather than
  • a

    Click downloadedthe XMLSave file.Changes When an IdP is configuredbutton to pull from a live URL, it will automatically fetch fresh metadata andreveal the integrationrequired staysconfiguration current.tabs.

    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)

    OPS-COM)

    These fields define exactly how OPSCOMOPS-COM will interact with your Identity Provider.

    • Unique ID:  RequiredID: -This Thisrequired field is a crucial part of the XML communication between OPSCOM and your SAML system.communication. It is supplied by your SAML system and is the exact value OPSCOMOPS-COM uses to match against its internal UniqueIDunique fieldidentifier.

      to identify a user.

    • Entity ID for Service ProviderProvider::  Required - This required value defines the unique SAML integration pathpath. withinSupply only the URLspecific in the metadata. If your OPSCOM system has more than one SAML integration, each Entityentity 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_FIELDname, not the wholeentire URL.

       

    • SP x509 Certificate: (Optional)This Thisoptional certificate is the certificate OPSCOM will useused 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 configureConfigure this field only if you are enabling signed logout requests, signed logout responses,requests or encrypted assertions.

      All three of those features are disabled by default.

    • Private Key: (Optional)This Requiredfield is only required if the SP certificate above is actively in use.

      Leave blank for standard configurations.

    Identity Provider Fields (ConfiguredExternal in OPSCOM, Values from Your SAML System):

    SAML)

    TheseYou fieldsmust captureinput informationvalues from your external SAML system (Identity Provider). You will find these values within your SAML system's metadata (e.g.,into oftenOPS-COM. displayedThis undertypically Federation → Show Metadata on your SAML installation page).

    • You will input values such asincludes 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.

    The IdP x509 Certificate field must contain the specific certificate issued by your Identity Provider — for example,(e.g., the certificate embedded in Azure's Federation Metadata XML.Metadata). Do not copy the OPS-COM SP certificate into this field. Entering the wrong certificate here will cause SAML assertion validation to failsilently silently,fail.

    and

    Synchronization usersTab willConfiguration

    be
      unable

    1. Click the Synchronization tab.

    2. Enable the Auto Create/Update User checkbox to logallow in.the Ifsystem to automatically create or update user profiles upon their first SAML login.

    3. Map the user attributes from your SSO system directly to the corresponding fields in doubt,OPS-COM download(e.g., mapping your IdP's Federation"email" 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:

      SettingDefaultWhat It Does
      Requested Auth ContextfalseWhen set to false, OPSCOM does not specify an authentication method in its requestattribute to the IdPOPS-COM —email thefield).

      IdP decides. Set to true to require password-based authentication (PasswordProtectedTransport). Leave as false for most Azure AD integrations.
      Require Name ID PolicyEnabledIncludes 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 AssertionsDisabledRequires 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 / ResponsesDisabledRequires the SP certificate and private key to be configured. Not required for standard Azure AD integrations.

      Using this Feature

      image.png
      Metadata Tab

    4. 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 asClick the UniqueSave ID FieldChanges in your Identity Provider Fields configuration within OPSCOM. If the unique ID is something else, such as SAMaccountName, then that should be used instead.button.

      ...

      5. 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 towith it. The Login Source value is permanently stored against every user record created via SSO. IfChanging youit changewill it,immediately lock out 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.attempt.

    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

     Configuration

    1. TheClick the Translations tabtab.

      allows
      2. you
    2. to customize

      Customize the text displayed on yourthe login button fromfor the user side.portal Youto can create as many different translations as are available in your system (e.g., English and French). This ensures thatensure the SSO login experience is localized for your users.specific audiences.

    image.png

    User
    Side:

    ErrorEnd-users Handling:do CommonPproblemsnot interact with the SAML setup. Once configured, they simply navigate to the User Portal and Theirclick Causesthe newly customized login button to seamlessly authenticate with their corporate credentials.

    Using this Feature

    Administrators interact with this feature primarily by establishing the initial metadata handshake and monitoring the system for synchronization errors.

    Exchanging Metadata

    To establish the connection, you must provide your Identity Provider with the OPS-COM Service Provider metadata.

    1. Click the Metadata tab to view your system's XML code and integration URL.

    2. Copy the live metadata URL (e.g., https://[your-domain]/auth/saml2/[ENTITY_ID]/metadata).

    3. Provide this live URL directly to your Identity Provider.

    We strongly recommend providing your Identity Provider with the live URL rather than a downloaded, static XML file. When an IdP pulls from a live URL, it automatically fetches fresh metadata, ensuring the integration stays current and bypasses strict expiration timestamps.

    Troubleshooting Synchronization

    If users encounter issues logging in, administrators should review the following common causes:

    • User cannotnot logfound: Verify that the Unique ID field in /OPS-COM "userperfectly not found" — The Unique ID Field in OPSCOM does not matchmatches the attribute name being sent by the IdP,IdP.

      or the user has not been assigned to the application in the IdP.

    • Assertion validation failurefailure: —Check Thethe IdP x509 Certificate field to ensure it contains the wrongcorrect certificateexternal (oftencertificate, not the OPS-COM SP certcertificate.

      copied
      • in
    • by mistake).

      InvalidNameIDPolicy error —error: Disable the "Require Name ID Policy"Policy togglesetting within the login source configuration (this is highly common with Microsoft ADFS IdPs)integrations).

    • Incorrect user data on auto-created accounts — A field mapping value doesn't match the attribute name the IdP is actually sending.data: Use your IdP's test/debug tool to seeconfirm the exact claim names in the assertion.

      • assertion,
    • Loginand sourceadjust mismatchyour —Synchronization Thetab Login Source value was changed after users were created. Contact OPSCOM Support.
    • OPSCOM's SSO debug log (when enabled) will display the full incoming user array, which makes attribute name mismatches straightforwardmapping to identify.match.

    Best Practices &and Considerations

    • Coordinate with IT/SAMLIT Administratoradministrators:: Successful SSO implementation requires close collaboration with your organization's IT department or the administrator of your SAML Identity Provider. They willmust provide the necessary metadata and accurate attribute names.

    • UniqueKeep Useryour Identifierscertificates separated:: Never enter the SP certificate in the IdP certificate field, or vice versa. The SP certificate is generated by OPS-COM, while the IdP certificate comes from your external Identity Provider's metadata. Treating them as identical will break the integration.

    • Map Azure AD attributes carefully: Azure AD does not send a combined "full name" attribute by default. If using Azure, always map the First Name and Last Name to completely separate attributes (e.g., givenname and surname) to prevent the entire display name from being stuffed into a single field.

    • Use true unique identifiers: Ensure the Unique Identifier chosen for matching users is truly unique and persistent within your SSO system. Incorrect or changing identifiers will rapidly lead to duplicate accounts or widespread 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.
    Back to top