# Using SAML SSO with OPS-COM

### What is Single Sign-On (SSO)

Single Sign-On, or SSO, is a way to make it easier for your users to access OperationsCommander using your existing managed accounts. Your users will not have to remember a separate username and password and will instead login directly to your corporate service provider.

### Configuring SAML Setup

<p class="callout info">Important - You must first follow the instructions to setup login sources found [here](https://opscom.wiki/books/administrators/page/login-sources-sso).</p>

<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-red-fields-are-requi"><div class="confluence-information-macro-body"></div></div>### Service Provider Fields

The **Unique Identifier** <span data-colorid="ud9hsvya1f">is part of the XML communication between OPSCOM and your SAML system. It is supplied by your SAML system and it is what OPS-COM uses to match against our UniqueID field.</span>

The **Entity ID** for **Service Provider** <span data-colorid="eog3cd27fd">defines the SAML integration path of the URL in the metadata. If there is more than one SAML integration in the system, each ID needs to be unique. The value supplied ends up in the path like this: "</span>[https://client.ops-com.com/auth/saml2/](https://client.ops-com.com/auth/saml2/)<span data-colorid="d4kkcltbgc"> ENTITY\_ID\_FIELD /acs"</span>

The **x509 certificate** can be generated and added to the service provider. You, the Identity Provider provide this.

### Identity Provider Fields

These fields come from the system you are working with, such as SAML, when communicating with OPS-COM. For example, SAML should display its metadata under **Federation → Show Metadata** on the SAML installation page.

Once the settings have been completed and saved, you will have access to the **MetaData, Synchronization,** and **Translations** tabs.

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

### Metadata

The Metadata tab provides the XML that would be provided to the Service Provider.

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

### Sample XML File

<p class="callout info">The following is an example of a response from an external system to OPS-COM. In this case, it is a SimpleSAMLPhp service set up as the identity provider. At the bottom, are several attributes within an saml:AttributeStatement tag. These are required for our system to match to a user within our system. The one field that matters in this attribute section is the value being used as the permanently-unique identifier for a user. In this case it is "uid". Since "uid" is being sent back, then the setup for Identity Provider Fields should have "uid" as the Unique ID Field. If the unique ID is something else, such as SAMaccountName, then that should be used for the UniqueID. </p>

<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``=``"<a href="http://www.w3.org/2001/XMLSchema-instance%22">http://www.w3.org/2001/XMLSchema-instance"</a>` `xmlns:xs``=``"<a href="http://www.w3.org/2001/XMLSchema%22">http://www.w3.org/2001/XMLSchema"</a>` `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``=``"<a href="https://minion-3.dev.parkadmin.com/auth/saml2/MinionOpsComStaff/acs%22">https://minion-3.dev.parkadmin.com/auth/saml2/MinionOpsComStaff/acs"</a>` `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 data-colorid="r35i1wvwwl">Translations</span>

Translations can be used to change the text displayed on your login button from the user side. We can create as many different translations as we have available on our system.

For this example, we have English and French.

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

### Synchronization

The synchronization tab allows you to create users in OPS-COM when they login from SAML if they do not already exist by mapping your user attributes to our system. This also lets you update existing users information in the system.

In this example, a<span class="legacy-color-text-blue3">ny field that is mapped and has a value from your SSO side should get updated to the value from SAML. </span>

To begin, ensure that you enable **Auto Create/Update User**. Keep in mind that these are sample values from our test system, and that your SAML system may differ.

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

After you have supplied the information in each field, you can click **Save Changes** and your users will begin to be created/updated.

If any of the supplied fields are incorrect, then the information will be blank when the user logs in, or it will be unchanged if the user already existed.