Samanage

# Setting up MIRACL Trust SSO as an Identity Provider Within Samanage

These instructions are up-to-date at the time of writing, but you should refer back to the Samanage SAML settings for SSO page to check for any changes. We cannot guarantee the accuracy of our SP-specific guidance.

Log in to Samange via <yoursamanageissueurl>.samanage.com/login. Your dashboard is displayed.
Choose Setup from the ‘Dashboard’ drop-down:

The ‘Settings’ page is displayed.
Click on the Single Sign-On text and icon:

The ‘Single Sign-On’ page is displayed.
Tick the Enable Single Sign-On with SAML checkbox:
Complete the fields as below, updating any placeholders with the specifics of your MIRACL Trust SSO setup:
- Identity Provider URL - http://<yourssoip>/sso
- Login URL - https://<yoursamanageissueurl>.samanage.com/saml_login/
- Logout URL - https://<yoursamanageissueurl>.samanage.com/saml_login/
- Error URL - https://<yoursamanageissueurl>.samanage.com/saml_login/
- SAML Issuer - SAManage.com
- Paste your Identity Provider x.509 Certificate below - paste in the contents of your security certificate including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers.
- Create users if they do not exist in Samanage -
- Redirect to the saml login page when logging into Samanage by default.
Click on the Update button.

# Configuring Your Samanage Service Provider Profile With MIRACL Trust SSO

Edit /etc/miracl-sso/service_providers/samanage.yaml:

profile:
  attribute:
    samanage: >-
      <AttributeStatement>
        <Attribute NameFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" Name="IDPEmail">
          <AttributeValue>{{.SessionUserEmail}}</AttributeValue>
        </Attribute>
      </AttributeStatement>
sp:
  samanage:
    description: Samanage
    name: Samanage
    relay_state: ""
    login_url: https://example.samanage.com/saml_login/EXAMPLE
    logout_url: https://example.samanage.com
    metadata: >-
      <!-- samanage doesnt provide a link to download its sp metadata, so this is hand-crafted -->
      <?xml version="1.0"?>
      <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://example.samanage.com/saml_login/EXAMPLE">
        <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
         <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
          <md:AssertionConsumerService index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://example.samanage.com/saml/EXAMPLE"/>
        </md:SPSSODescriptor>
      </md:EntityDescriptor>
    sign_response: false
    sign_assertion: true
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      nameid: email
      attribute: samanage

Note that the name under which the SP is registered in the sp section is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/samanage.
Add the SP login URL and logout URL from Samanage.
For the metadata, use the content from the example, but update the SP URL within entityID and Location.

Note that if you are working with json config files rather than yaml, you need to save the metadata as e.g. samanage_metadata.xml. It is then necessary to convert it to single line format and escape all " characters before copying and pasting it as the above metadata parameter. This can be done with the following command:
```
echo -e "\n"$(cat samanage_metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n"
```
The contents are output in the terminal in a format that can be pasted into the metadata field of a JSON file.
In the authorize subsection, you can control what users are allowed to attempt login by following one or both of the below steps:
- Call up an LDAP setup from an ldap.yaml file stored in /etc/miracl-sso/integrations.
- Configure a regex list of email addresses/domains. The above config shows an example of how you would use email: ^[^@]+@example.com$ to only allow users from a certain email domain to login.
  
  Note that if this is not set correctly, you receive ‘unauthorized user’ messages.
  
  For more detailed info on using LDAP, API and/or regex to control authorized users, please see the authorization menu section.
Save and close the file.
In your /etc/miracl-sso/config.yaml file make sure you add samanage.yaml to the list of ‘includes’:
```
includes:
  - core.yaml

# service providers
  - service_providers/sap.yaml
```
As always after config changes, restart the server.
Now your service is configured, you can visit https://<yourssoip>/login/samanage or https://<yourssoip>/services to login to the service using IdP-initiated login, or visit the Samanage login page and SP-initiated login are triggered automatically.
You are able to login using the in-browser PIN pad or with the MIRACL Trust app. When logging in to your SSO service for the first time you are asked to register an email address so as to confirm your identity and register you as a user.