G Suite

Setting up MIRACL Trust SSO as an Identity Provider within G Suite

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

  1. Log in to the GSuite Admin Console and go to Security > Setup Single Sign On.
    Note that for the above link to take you to the correct page, you need to have previously logged in to a valid G Suite account.

  2. Complete the fields as below:

  • tick the Setup SSO with third party identity provider checkbox
  • enter http://<yourssoip>/sso in the Sign-in page URL field
  • enter https://accounts.google.com/Logout in the Sign-out page URL field
  • under ‘Verification certificate’, upload a file containing the contents of the ‘public_certificate’ entry from the idp section of config.json
  1. Click on SAVE to apply your settings.

Configuring a G Suite SP profile with MIRACL Trust SSO

  1. Edit /etc/miracl-sso/service_providers/google.yaml:
sp:
  google:
    description: Google G-Suite Services
    relay_state: ""
    login_url: https://mail.google.com/a/example.com
    logout_url: https://accounts.google.com/Logout
    metadata: >-
      <?xml version="1.0" encoding="UTF-8"?>
      <!-- google doesnt provide a link to download its sp metadata, so this
            is hand-crafted -->
      <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="google.com">
        <md:SPSSODescriptor WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
          <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
          <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.google.com/a/example.com/acs" index="0"/>
        </md:SPSSODescriptor>
      </md:EntityDescriptor>
    sign_response: true
    sign_assertion: true
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      attribute: empty
  1. Note that sp name is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/google

  2. For login_url your specified domain should replace ‘example.com’. This will also need changed in the Location parameter in the above metadata. The logout_url is the standard url which G Suite makes available for SAML IdPs to use.

Note that, if you are using JSON format for your config file, the handcrafted metadata above must be saved as an xml file; then converted to a single line with the " characters escaped with \ to meet the json structure requirements. This can be achieved by running the following command on the e.g. 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 google.yaml to the list of ‘includes’:

includes:
  - core.yaml

# service providers
  - service_providers/google.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/google or https://<yourssoip>/services to login to the service using IdP-initiated login, or visit the G-Suite 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.