# 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](https://opscom.wiki/books/customization-and-integration/page/single-sign-on-sso-and-operationscommander-what-do-you-need-to-consider).

### 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).

<div class="confluence-information-macro confluence-information-macro-information conf-macro output-block" data-hasbody="true" data-macro-id="4c44a372-8f2e-4c9a-abcb-af05c071ddac" data-macro-name="info" id="bkmrk-paid-feature%3A-sso-is"><div class="confluence-information-macro-body"><div _ngcontent-ng-c617919120="" class="chat-history-scroll-container"><div _ngcontent-ng-c617919120="" class="conversation-container message-actions-hover-boundary ng-star-inserted"><div _ngcontent-ng-c3942763368=""><div _ngcontent-ng-c4086532758="" class="response-container ng-tns-c4086532758-215 response-container-with-gpi ng-star-inserted" jslog="173900;track:impression"><div _ngcontent-ng-c4086532758="" class="presented-response-container ng-tns-c4086532758-215"><div _ngcontent-ng-c4086532758="" class="response-container-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3942763368="" class="response-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3017587935="" class="markdown markdown-main-panel enable-updated-hr-color" dir="ltr">- **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.
- <p class="callout warning">**Login Sources**: You must first [follow the instructions to set up Login Sources](https://opscom.wiki/books/setup-configuration-for-admins/page/login-sources-sso) within OPSCOM, as SSO will be configured as a specific login source.</p>
- **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?

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

<span class="citation-2 citation-end-2">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).</span>

---

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

<p class="callout warning">The settings below must be filled out correctly and saved before you will see the Metadata tab to continue.</p>

##### <span style="text-decoration: underline;">Service Provider Fields (Configured in OPSCOM)</span>

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

<div class="confluence-information-macro confluence-information-macro-information conf-macro output-block" data-hasbody="true" data-macro-id="4c44a372-8f2e-4c9a-abcb-af05c071ddac" data-macro-name="info" id="bkmrk-unique-identifier%3A-t"><div class="confluence-information-macro-body"><div _ngcontent-ng-c617919120="" class="chat-history-scroll-container"><div _ngcontent-ng-c617919120="" class="conversation-container message-actions-hover-boundary ng-star-inserted"><div _ngcontent-ng-c3942763368=""><div _ngcontent-ng-c4086532758="" class="response-container ng-tns-c4086532758-215 response-container-with-gpi ng-star-inserted" jslog="173900;track:impression"><div _ngcontent-ng-c4086532758="" class="presented-response-container ng-tns-c4086532758-215"><div _ngcontent-ng-c4086532758="" class="response-container-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3942763368="" class="response-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3017587935="" class="markdown markdown-main-panel enable-updated-hr-color" dir="ltr">- **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.
- **<span class="citation-1">Entity ID for Service Provider</span>**<span class="citation-1 citation-end-1">: **Required** - This value defines the unique SAML integration path within the URL in the metadata.<sup class="superscript" data-turn-source-index="6"></sup></span> 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: `<a href="https://client.OPSCOM.com/auth/saml2/ENTITY_ID_FIELD/acs">https://client.OPSCOM.com/auth/saml2/ENTITY_ID_FIELD/acs</a>`. ***Only add the ENTITY\_ID\_FIELD not the whole URL.***
- **x509 Certificate**: (Optional) This certificate is provided by your Identity Provider (IdP) and can be generated and added to the Service Provider (OPSCOM) for secure communication.
- Private Key: (Optional)

</div></div></div></div></div></div></div></div></div></div>##### <span style="text-decoration: underline;">Identity Provider Fields (Configured in OPSCOM, Values from Your SAML System):</span>

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

<div class="confluence-information-macro confluence-information-macro-information conf-macro output-block" data-hasbody="true" data-macro-id="4c44a372-8f2e-4c9a-abcb-af05c071ddac" data-macro-name="info" id="bkmrk-you-will-input-value"><div class="confluence-information-macro-body"><div _ngcontent-ng-c617919120="" class="chat-history-scroll-container"><div _ngcontent-ng-c617919120="" class="conversation-container message-actions-hover-boundary ng-star-inserted"><div _ngcontent-ng-c3942763368=""><div _ngcontent-ng-c4086532758="" class="response-container ng-tns-c4086532758-215 response-container-with-gpi ng-star-inserted" jslog="173900;track:impression"><div _ngcontent-ng-c4086532758="" class="presented-response-container ng-tns-c4086532758-215"><div _ngcontent-ng-c4086532758="" class="response-container-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3942763368="" class="response-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3017587935="" class="markdown markdown-main-panel enable-updated-hr-color" dir="ltr">- 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).

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

<div class="confluence-information-macro confluence-information-macro-information conf-macro output-block" data-hasbody="true" data-macro-id="4c44a372-8f2e-4c9a-abcb-af05c071ddac" data-macro-name="info" id="bkmrk--1"><div class="confluence-information-macro-body"><div _ngcontent-ng-c617919120="" class="chat-history-scroll-container"><div _ngcontent-ng-c617919120="" class="conversation-container message-actions-hover-boundary ng-star-inserted"><div _ngcontent-ng-c3942763368=""><div _ngcontent-ng-c4086532758="" class="response-container ng-tns-c4086532758-215 response-container-with-gpi ng-star-inserted" jslog="173900;track:impression"><div _ngcontent-ng-c4086532758="" class="presented-response-container ng-tns-c4086532758-215"><div _ngcontent-ng-c4086532758="" class="response-container-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3942763368="" class="response-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3017587935="" class="markdown markdown-main-panel enable-updated-hr-color" dir="ltr">---

</div></div></div></div></div></div></div></div></div></div>### Using this Feature

##### <span style="text-decoration: underline;">[![image.png](https://opscom.wiki/uploads/images/gallery/2024-06/scaled-1680-/Om4image.png)](https://opscom.wiki/uploads/images/gallery/2024-06/Om4image.png)</span>

##### <span style="text-decoration: underline;">Metadata Tab</span>

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](https://opscom.wiki/uploads/images/gallery/2024-06/scaled-1680-/BLMimage.png)](https://opscom.wiki/uploads/images/gallery/2024-06/BLMimage.png)

##### <span style="text-decoration: underline;">Sample XML File</span>

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

<span class="message css-14uc8v9"><span data-colorid="ihs6me7lvb">... DEV-2K8</span> - DEBUG: Saml2 Incoming User Array ( \[uid\] =&gt; Array ( \[0\] =&gt; 6ddf4027-3397-4e45-8628-0189f60fe91e ) \[full name\] =&gt; Array ( \[0\] =&gt; Sarah Knowles ) \[email\] =&gt; Array ( \[0\] =&gt; sknowles@tomahawk.ca ) ) \[\]</span>

<div class="code panel pdl conf-macro output-block" data-hasbody="true" data-macro-id="8c2f3283-e2df-4f84-8b64-c685cebf809c" data-macro-name="code" id="bkmrk-%3C%3Fxml%C2%A0version%3D%221.0%22%3F"><div class="codeContent panelContent pdl"><div><div class="syntaxhighlighter sh-confluence nogutter  xml" id="bkmrk-%3C%3Fxml%C2%A0version%3D%221.0%22%3F-1"><table border="0" cellpadding="0" cellspacing="0"><tbody><tr><td class="code"><div class="container" title="Hint: double-click to select code"><div class="line number1 index0 alt2" data-bidi-marker="true">`<?``xml` `version``=``"1.0"``?>`</div><div class="line number2 index1 alt1" data-bidi-marker="true">`        ``<``samlp:Response` `xmlns:samlp``=``"urn:oasis:names:tc:SAML:2.0:protocol"` `xmlns:saml``=``"urn:oasis:names:tc:SAML:2.0:assertion"` `ID``=``"_aa1963115aa6490e728c7376f4c8849813bbb..."``>`</div><div class="line number3 index2 alt2" data-bidi-marker="true">`          ``...`</div><div class="line number4 index3 alt1" data-bidi-marker="true">`          ``<``saml:Assertion` `xmlns:xsi``=``"http://www.w3.org/2001/XMLSchema-instance"` `xmlns:xs``=``"http://www.w3.org/2001/XMLSchema"` `ID``=``"_9efd79bf6425983ee9176f3d33a99d1a9176180..."``>`</div><div class="line number5 index4 alt2" data-bidi-marker="true">`            ``...`</div><div class="line number6 index5 alt1" data-bidi-marker="true">`            ``<``saml:Subject``>`</div><div class="line number7 index6 alt2" data-bidi-marker="true">`              ``<``saml:NameID` `SPNameQualifier``=``"MinionOpsComStaff"` `Format``=``"urn:oasis:names:tc:SAML:2.0:nameid-format:transient"``>_7a426e0be71f14c1f349db00d7d543b6f7dcb52baa</``saml:NameID``>`</div><div class="line number8 index7 alt1" data-bidi-marker="true">`              ``<``saml:SubjectConfirmation` `Method``=``"urn:oasis:names:tc:SAML:2.0:cm:bearer"``>`</div><div class="line number9 index8 alt2" data-bidi-marker="true">`                ``<``saml:SubjectConfirmationData` `NotOnOrAfter``=``"2021-08-24T16:00:41Z"` `Recipient``=``"https://minion-3.dev.parkadmin.com/auth/saml2/MinionOpsComStaff/acs"` `InResponseTo``=``"ONELOGIN_bb8a09203c888cf59af4c621a71cfa8f7559c016"``/>`</div><div class="line number10 index9 alt1" data-bidi-marker="true">`              ``</``saml:SubjectConfirmation``>`</div><div class="line number11 index10 alt2" data-bidi-marker="true">`            ``</``saml:Subject``>`</div><div class="line number12 index11 alt1" data-bidi-marker="true">`            ``<``saml:Conditions` `NotBefore``=``"2021-08-24T15:55:11Z"` `NotOnOrAfter``=``"2021-08-24T16:00:41Z"``>`</div><div class="line number13 index12 alt2" data-bidi-marker="true">`              ``<``saml:AudienceRestriction``>`</div><div class="line number14 index13 alt1" data-bidi-marker="true">`                ``<``saml:Audience``>MinionOpsComStaff</``saml:Audience``>`</div><div class="line number15 index14 alt2" data-bidi-marker="true">`              ``</``saml:AudienceRestriction``>`</div><div class="line number16 index15 alt1" data-bidi-marker="true">`            ``</``saml:Conditions``>`</div><div class="line number17 index16 alt2" data-bidi-marker="true">`            ``<``saml:AuthnStatement` `AuthnInstant``=``"2021-08-24T15:34:46Z"` `SessionNotOnOrAfter``=``"2021-08-24T23:34:46Z"` `SessionIndex``=``"_a7a68666092117d24aab8adecf1b0830622855b85..."``>`</div><div class="line number18 index17 alt1" data-bidi-marker="true">`              ``<``saml:AuthnContext``>`</div><div class="line number19 index18 alt2" data-bidi-marker="true">`                ``<``saml:AuthnContextClassRef``>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</``saml:AuthnContextClassRef``>`</div><div class="line number20 index19 alt1" data-bidi-marker="true">`              ``</``saml:AuthnContext``>`</div><div class="line number21 index20 alt2" data-bidi-marker="true">`            ``</``saml:AuthnStatement``>`</div><div class="line number22 index21 alt1" data-bidi-marker="true"> </div><div class="line number23 index22 alt2" data-bidi-marker="true"> </div><div class="line number24 index23 alt1" data-bidi-marker="true">`            ``<``saml:AttributeStatement``>`</div><div class="line number25 index24 alt2" data-bidi-marker="true">`              ``<``saml:Attribute` `Name``=``"uid"` `NameFormat``=``"urn:oasis:names:tc:SAML:2.0:attrname-format:basic"``>`</div><div class="line number26 index25 alt1" data-bidi-marker="true">`                ``<``saml:AttributeValue` `xsi:type``=``"xs:string"``>6ddf4027-3397-4e45-8628-0189f60fe91e</``saml:AttributeValue``>`</div><div class="line number27 index26 alt2" data-bidi-marker="true">`              ``</``saml:Attribute``>`</div><div class="line number28 index27 alt1" data-bidi-marker="true">`              ``<``saml:Attribute` `Name``=``"full name"` `NameFormat``=``"urn:oasis:names:tc:SAML:2.0:attrname-format:basic"``>`</div><div class="line number29 index28 alt2" data-bidi-marker="true">`                ``<``saml:AttributeValue` `xsi:type``=``"xs:string"``>Sarah Knowles</``saml:AttributeValue``>`</div><div class="line number30 index29 alt1" data-bidi-marker="true">`              ``</``saml:Attribute``>`</div><div class="line number31 index30 alt2" data-bidi-marker="true">`              ``<``saml:Attribute` `Name``=``"email"` `NameFormat``=``"urn:oasis:names:tc:SAML:2.0:attrname-format:basic"``>`</div><div class="line number32 index31 alt1" data-bidi-marker="true">`                ``<``saml:AttributeValue` `xsi:type``=``"xs:string"``>sknowles@tomahawk.ca</``saml:AttributeValue``>`</div><div class="line number33 index32 alt2" data-bidi-marker="true">`              ``</``saml:Attribute``>`</div><div class="line number34 index33 alt1" data-bidi-marker="true">`            ``</``saml:AttributeStatement``>`</div><div class="line number35 index34 alt2" data-bidi-marker="true"> </div><div class="line number36 index35 alt1" data-bidi-marker="true"> </div><div class="line number37 index36 alt2" data-bidi-marker="true">`          ``</``saml:Assertion``>`</div><div class="line number38 index37 alt1" data-bidi-marker="true">`        ``</``samlp:Response``>`</div></div></td></tr></tbody></table>

</div></div></div></div>##### <span style="text-decoration: underline;">Synchronization Tab</span>

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

<div class="confluence-information-macro confluence-information-macro-information conf-macro output-block" data-hasbody="true" data-macro-id="4c44a372-8f2e-4c9a-abcb-af05c071ddac" data-macro-name="info" id="bkmrk-auto-create%2Fupdate-u"><div class="confluence-information-macro-body"><div _ngcontent-ng-c617919120="" class="chat-history-scroll-container"><div _ngcontent-ng-c617919120="" class="conversation-container message-actions-hover-boundary ng-star-inserted"><div _ngcontent-ng-c3942763368=""><div _ngcontent-ng-c4086532758="" class="response-container ng-tns-c4086532758-215 response-container-with-gpi ng-star-inserted" jslog="173900;track:impression"><div _ngcontent-ng-c4086532758="" class="presented-response-container ng-tns-c4086532758-215"><div _ngcontent-ng-c4086532758="" class="response-container-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3942763368="" class="response-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3017587935="" class="markdown markdown-main-panel enable-updated-hr-color" dir="ltr">- **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.
- **<span class="citation-0">User Attribute Mapping</span>**<span class="citation-0 citation-end-0">: On this tab, you will map the user attributes from your SSO system (your Identity Provider) to the corresponding fields in OPSCOM.<sup class="superscript" data-turn-source-index="7"></sup></span> 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.

</div></div></div></div></div></div></div></div></div></div>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.

[![image.png](https://opscom.wiki/uploads/images/gallery/2024-06/scaled-1680-/W2qimage.png)](https://opscom.wiki/uploads/images/gallery/2024-06/W2qimage.png)

<p class="callout info">The exact sample values from our test system may differ from your actual SAML system attributes.</p>

##### <span style="text-decoration: underline;">Translations Tab</span>

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](https://opscom.wiki/uploads/images/gallery/2024-06/scaled-1680-/0Bpimage.png)](https://opscom.wiki/uploads/images/gallery/2024-06/0Bpimage.png)

---

### <span style="color: rgb(22, 145, 121);">Best Practices &amp; Considerations</span>

<div class="confluence-information-macro confluence-information-macro-information conf-macro output-block" data-hasbody="true" data-macro-id="4c44a372-8f2e-4c9a-abcb-af05c071ddac" data-macro-name="info" id="bkmrk-coordinate-with-it%2Fs"><div class="confluence-information-macro-body"><div _ngcontent-ng-c617919120="" class="chat-history-scroll-container"><div _ngcontent-ng-c617919120="" class="conversation-container message-actions-hover-boundary ng-star-inserted" id="bkmrk-coordinate-with-it%2Fs-1"><div _ngcontent-ng-c3942763368=""><div _ngcontent-ng-c4086532758="" class="response-container ng-tns-c4086532758-215 response-container-with-gpi ng-star-inserted" jslog="173900;track:impression"><div _ngcontent-ng-c4086532758="" class="presented-response-container ng-tns-c4086532758-215"><div _ngcontent-ng-c4086532758="" class="response-container-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3942763368="" class="response-content ng-tns-c4086532758-215"><div _ngcontent-ng-c3017587935="" class="markdown markdown-main-panel enable-updated-hr-color" dir="ltr" id="bkmrk-coordinate-with-it%2Fs-2">- <span style="color: rgb(22, 145, 121);">**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.</span>
- <span style="color: rgb(22, 145, 121);">**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.</span>
- <span style="color: rgb(22, 145, 121);">**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.</span>
- <span style="color: rgb(22, 145, 121);">**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.</span>
- <span style="color: rgb(22, 145, 121);">**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.</span>
- <span style="color: rgb(22, 145, 121);">**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.</span>

</div></div></div></div></div></div></div></div></div></div>