Shibboleth

# Configuring Your Shibboleth Service Provider Profile With MIRACL Trust SSO

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

Make sure that your Shibboleth SP is properly installed:
- https://<yourspip>/Shibboleth.sso/Status should return the xml status handler of the running Shibboleth SP service
- https://<yourspip>/Shibboleth.sso/Session should return A valid session was not found.
Download the Shibboleth metadata from https://<yourspip>/Shibboleth.sso/Metadata.

Edit /etc/miracl-sso/service_providers/shibboleth.yaml file:

sp:
  shibboleth:
    description: Shibboleth
    name: My Shibboleth SP
    relay_state: "/"
    login_url: https://<yourspip>/Shibboleth.sso/Login
    logout_url: https://<yourspip>/Shibboleth.sso/Logout
    metadata: >-
      <?xml version="1.0" encoding="UTF-8"?>
      <!-- insert downloaded SP metatadata here -->

    sign_response: true
    sign_assertion: true
    encrypt_assertion: true
    authorize:
    - - email: ^[^@]+@example.com$

Note that, if you are using JSON format for your config file, the downloaded metadata should be saved as an xml file and converted to a single line with the " characters escaped with \ to meet json structure requirements. This can be achieved by running the following command on the downloaded metadata.xml file:

echo -e "\n"$(cat 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.

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/shibboleth.
Update the SP login_url and logout_url entries with the correct information depending on your Shibboleth SP configuration.
Shibboleth supplies you with your SP metadata which should be pasted into the above metadata field.
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 test purposes, you could set it to authorize: true to authorize by default every user.
  
  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 shibboleth.yaml to the list of ‘includes’:
```
includes:
  - core.yaml

# service providers
  - service_providers/shibboleth.yaml
```
As always after config changes, restart the server.

# Configuring Your Shibboleth SP With MIRACL Trust SSO

Copy the MIRACL SSO metadata to the Shibboleth SP

# curl --output /etc/shibboleth/miracl-metadata.xml https://<yourssoip>/metadata

Add the configuration path in the Shibboleth SP configuration file
```
# nano /etc/shibboleth/shibboleth2.xml
```
Find the SSO declaration configuration and update the entityID with the one of your MIRACL SSO running service. Note it should be exactly the same with the one listed in the miracl metadata file.
```
    <SSO entityID="https://<yourssoip>/metadata"
        discoveryProtocol="SAMLDS"
discoveryURL="https://ds.example.org/DS/WAYT">
      SAML2 SAML1
    </SSO>
```
Add a line with the path to the just copied metadata at the end of the ApplicationDefaults section as follows:
```
  <MetadataProvider type="XML" file="miracl-metadata.xml"/>
```
Restart the service in order the changes to take effect:
```
# service shibd restart
```
Now your service is configured, you can visit https://<yourssoip>/login/shibboleth or https://<yourssoip>/services to login to the service using IdP-initiated login, or visit the Shibboleth SP login page https://<yourspip>/Shibboleth.sso/Login 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. After you login https://localhost/Shibboleth.sso/Session already displays information about your logged in identity.