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

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.

<p class="callout info">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.</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.***
- **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.

</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><span style="color: rgb(230, 126, 35);">⚠️ 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.</span>

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

<div class="overflow-x-auto w-full px-2 mb-6" data-sourcepos="59:1-64:165;3524-4615" id="bkmrk-setting-default-what"><table class="min-w-full border-collapse text-sm leading-[1.7] whitespace-normal" style="width: 100%;"><thead class="text-left"><tr><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 12.7533%;">Setting</th><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 12.8725%;">Default</th><th class="text-text-100 border-b-0.5 border-[hsl(var(--border-300)/0.6)] py-2 pr-4 align-top font-bold" scope="col" style="width: 74.3743%;">What It Does</th></tr></thead><tbody><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.7533%;">**Requested Auth Context**</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.8725%;">`false`</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 74.3743%;">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.</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.7533%;">**Require Name ID Policy**</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.8725%;">Enabled</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 74.3743%;">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.</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.7533%;">**Require Encrypted Assertions**</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.8725%;">Disabled</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 74.3743%;">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.</td></tr><tr><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.7533%;">**Sign Logout Requests / Responses**</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 12.8725%;">Disabled</td><td class="border-b-0.5 border-[hsl(var(--border-300)/0.3)] py-2 pr-4 align-top" style="width: 74.3743%;">Requires the SP certificate and private key to be configured. Not required for standard Azure AD integrations.</td></tr></tbody></table>

</div><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--2"><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><p class="callout warning"><span style="text-decoration: underline;">⚠️ 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.</span></p>

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

> **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.
> 
> <p class="callout warning">⚠️ 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).</p>

[![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)

---

### Error Handling: CommonPproblems and Their Causes

- User cannot log in / "user not found" — The Unique ID Field in OPSCOM does not match the attribute name being sent by the IdP, or the user has not been assigned to the application in the IdP.
- Assertion validation failure — The IdP x509 Certificate field contains the wrong certificate (often the SP cert copied in by mistake).  
    InvalidNameIDPolicy error — Disable the "Require Name ID Policy" toggle (common with ADFS IdPs).
- Incorrect user data on auto-created accounts — A field mapping value doesn't match the attribute name the IdP is actually sending. Use your IdP's test/debug tool to see the exact claim names in the assertion.
- Login source mismatch — The 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 straightforward to identify.

---

### <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>
- <span style="color: rgb(22, 145, 121);">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.</span>
- <span style="color: rgb(22, 145, 121);">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.</span>

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