Setting up MIRACL Trust SSO as an Identity Provider within Expensify

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

  1. Log in to Expensify (as administrator).

  2. To enable SSO in Expensify you first need to have Domain Control enabled.

  3. Once you have Domain Control enabled, navigate to Admin > Domain Control > [domain name] > SAML to display the following page.

  4. Find the MIRACL Trust metadata document – you should have downloaded this as an XML file (available at the following endpoint: http://<yourssoip>/metadata). Note that, for a production setup, if you manually download your IdP metadata file, the validUntil date at the top of the file will need to be edited to an appropriate date (it defaults to 48hrs from the current date).

  5. Copy and paste the MIRACL Trust metadata into the Identity Provider MetaData text box.

  6. Make a note of the endpoint in the Login URL field.

  7. Make a note of the endpoint in the Logout URL field.

  8. Scroll down to display the second half of the page:

  9. Copy the contents of the Service Provider MetaData field into a text file.

  10. Authorise SAML in Expensify by clicking on the ‘SAML Login’ ENABLED switch.

Configuring your Expensify Service Provider profile with MIRACL Trust SSO

  1. Edit /etc/miracl-sso/service_providers/expensify.yaml:
    description: expensify
    relay_state: ""
    login_url: https://www.expensify.com/authentication/saml/loginCallback?domain=example.com
    logout_url: https://www.expensify.com/authentication/saml/logoutCallback?domain=example.com
    metadata: >-
      <!-- insert downloaded SP metatadata here -->
    sign_response: true
    sign_assertion: true
    encrypt_assertion: false
    - - email: ^[^@]+@example.com$
  1. Note that sp name is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/expensify

  2. Update the SP login_url and logout_url entries with the correct information retrieved from Expensify.

  3. Expensify should supply you with your SP metadata which can be pasted into the above metadata field.

The downloaded metadata file must be converted to a single line with a command such as:

echo -e "\n"$(cat metadata.xml | tr -d '\n')"\n"

The contents will then be output in the terminal in a format that can be pasted into the metadata field.

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 will then be output in the terminal in a format that can be pasted into the metadata field of a JSON file.

  1. 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 will receive ‘unauthorized user’ messages.

For more detailed info on using LDAP and regex to control authorized users, please see the LDAP and authorization menu section

  1. Save and close the file.

  2. In your /etc/miracl-sso/config.yaml file make sure you add expensify.yaml to the list of ‘includes’:

  - core.yaml

# service providers
  - service_providers/expensify.yaml
  1. As always after config changes, restart the server with sudo service miracl-sso restart

  2. Now your service is configured, you can visit https://<yourssoip>/login/expensify or https://<yourssoip>/services to login to the service using IdP-initiated login, or visit the Expensify login page and SP-initiated login will be triggered automatically.

  3. You will be 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 will be asked to register an email address so as to confirm your identity and register you as a user.