Installation / Quick Start

Intro

This quick start guide will take you through all the steps necessary to get your IdP server installed, connected to the authentication portal backend and set up with a single service provider. This will enable you to then run your IdP server and make a test login to the configured SP, thus ensuring that you have a good grasp of how to configure the system before going on to add any other service providers, whether they are ones supported ‘out of the box’ by MIRACL Trust SSO, or ones you wish to add from scratch. The list of Service Providers supported out of the box can be found here

Installation


Debian Installation

Redis is used for user session storage (it can be run locally or remotely):

sudo apt-get update && sudo apt-get install redis-server

For ubuntu/debian you can install via the following commands when logged in as root:

wget -qO - http://repo.miracl.com/build-team-public.asc | apt-key add --

Create a new file:

/etc/apt/sources.list.d/miracl.list

Now add the following to miracl.list:

deb http://repo.miracl.com/apt/ubuntu all main

Save and close the file, then continue with the commands: sudo apt-get update sudo apt-get install miracl-srv-idp

Starting/Restarting the service

The service can be run with sudo service srv-idp start

After any changes are made to the config file the service needs to be restarted:

sudo service srv-idp restart

Uninstallation

The program can be uninstalled with sudo apt-get --purge remove miracl-srv-idp

RPM Installation

First, the EPEL repositories need to be enabled, so:

sudo yum install epel-release

Redis is used for user session storage (it can be run locally or remotely):

sudo yum install redis

You can now install via the following:

Create a new repo file: /etc/yum.repos.d/miracl-rpm.repo

Then add the following:

[miracl]
name= Latest Release for RHEL/Centos 7Server
baseurl=http://repo.miracl.com/yum/redhat/7Server
gpgkey=http://repo.miracl.com/build-team-public.asc
enabled=1
gpgcheck=1

Save and close the file.

During initial install of any package from this repo, you will be asked to accept the key.

Finally, install with:

sudo yum install miracl-srv-idp

Starting/Restarting the service

The service can be run with sudo service srv-idp start

After any changes are made to the config file the service needs to be restarted:

sudo service srv-idp restart

[/ui-tab] [/ui-tabs]

Core configuration

Configuration of your IdP server is driven by files located in the /etc/srv-idp/ directory (please see the overview for an intro to how these files work):

/etc/srv-idp/
├── config.yaml
├── core.yaml
└── service_providers
    ├── aws.yaml
    └── dropbox.yaml

Edit /etc/srv-idp/config.yaml to list the config files that are to be included:

includes:
  - core.yaml

# example service providers
  - service_providers/aws.yaml
  - service_providers/bamboo.yaml

Note that settings in files lower down the list of includes will override settings in those higher in the list. For example if you include a file which specifies a server port number, this will override a server port number set in a file higher in the list of includes.

Remote config with Consul

If you wish to load your configuration files remotely, you can add the url of your config as an include, as per the following consul example:

includes:
  - http://127.0.0.1:8500/v1/kv/config/srv-idp/config.yaml?raw

Obtain the Client ID and Client Secret

To begin using MIRACL Trust SSO, you must first log into the MIRACL Trust authentication portal at https://trust.miracl.cloud to create a new app:

  1. Click on the ‘Apps’ link in the dashboard and create a new SSO with SAML app. Note that, normally, the entered Redirect URL must be the publicly available url which will be serving your installation of the SSO IdP server, and it must use the /login endpoint. Setting it as e.g. http://127.0.0.1:8000/login will enable local testing of your setup.

  2. Note that your Client Secret will only be issued to you once so it must be grabbed when first displayed. The Client ID can then be grabbed from the app settings screen. Both of these values are needed, for entering in your configuration below.

Now edit /etc/srv-idp/core.yaml:

server:
  address: ":8000"
  public_address: "http://127.0.0.1:8000"
mfa:
  client_id: ""
  client_secret: ""
idp:
  private_key: ""
  public_certificate: ""

Leaving the server section will enable local testing with http://127.0.0.1:8000

Note that public_address should not end with a "/" i.e. http://yoursso.net is correct but http://yoursso.net/ will result in an error.

In the mfa section enter the Client ID and Client Secret for your SSO app.

Generate certificates

In the idp section you need to add your private key and public certificate for your IdP server. These can be generated and output in the terminal in single line format with a command such as:

openssl req -x509 -nodes -newkey rsa:2048 -keyout idp.key -out idp.crt -days 1000 -subj /C=UK/ST=London/L=London/O=Development/CN=example.com \
&& echo -e "\nCONFIG PRIVATE KEY:\n" \
&& echo $(cat idp.key | tr -d '\n' | sed -E 's/-----[^-]+-----//g') \
&& echo -e "\nCONFIG PUBLIC CERTIFICATE:\n" \
&& echo $(cat idp.crt | tr -d '\n' | sed -E 's/-----[^-]+-----//g') \
&& echo ""

This script will generate a key and certificate within your current directory (pwd) and display them in the terminal in a format ready to be pasted straight into the config file (they will appear in the correct order with the private key appearing first).

You can now restart the IdP server with sudo service srv-idp restart

Service Provider Setup

You can choose to set up either Dropbox or AWS as a Service Provider. Dropbox is very simple to set up, although you will need a paid account in order to use the SAML SSO module. A free AWS account does include SAML.

Please choose a tab for whichever Service Provider you wish to test:

DropBox


Table of Contents:

1. Setting up MIRACL Trust SSO as an Identity Provider within Dropbox 2. Configure DropBox as a Service Provider within MIRACL Trust SSO


Setting up MIRACL Trust SSO as an Identity Provider within Dropbox

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

  1. Log in to your Dropbox for Business account.

  2. Click on Admin Console.
    The ‘Dropbox Admin Console’ is launched in a new browser tab.

  3. Click on Settings.
    The following page is displayed: dropbox-settings

  4. Click on Single sign-on

dbox_settings

  1. Select Required

  2. Set the Sign in URL as the https://<myssoip>/sso endpoint on your IdP server. If you are running a local test it will be http://127.0.0.1:8000/sso

  3. Upload your X.509 certificate. To do this you can just upload the public certificate generated earlier - (idp.crt) in the command given above. This file is in newline format and begins with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----. Dropbox also receives certificates in .pem format.

Configuring a Dropbox Service Provider profile with MIRACL Trust SSO

  1. Edit /etc/srv-idp/service_providers/dropbox.yaml:
sp:
  dropbox:
    description: Dropbox is a cloud storage provider
    issuer: Dropbox
    relay_state: ""
    login_url: https://www.dropbox.com/login
    logout_url: https://www.dropbox.com/logout
    metadata: >-
      <?xml version="1.0" encoding="UTF-8"?>
      <!-- dropbox 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="www.dropbox.com">
        <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 Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.dropbox.com/saml_login"/>
        </md:SPSSODescriptor>
      </md:EntityDescriptor>
    sign_response: true
    sign_assertion: false
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      nameid: email
  1. Note that sp name is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/dropbox

  2. login_url and logout_url are the standard SP URLs which Dropbox makes available for SAML IdPs to use.

  3. Do not make any changes to the SP metadata. It is handcrafted for Dropbox.

Note that, if you are using JSON format for your config file, the handcrafted 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 handcrafted 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/srv-idp/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/srv-idp/config.yaml file make sure you add dropbox.yaml to the list of ‘includes’:

includes:
  - core.yaml

# service providers
  - service_providers/dropbox.yaml
  1. As always after config changes, restart the server with sudo service srv-idp restart

  2. Now your service is configured, you can visit https://<yourssoip>/login/dropbox or https://<yourssoip>/services to login to the service using IdP-initiated login, or visit the Dropbox 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.

AWS


Table of Contents:

1. Setting up MIRACL Trust SSO as an Identity Provider within AWS 2. Configure AWS as a Service Provider within MIRACL Trust SSO


Setting up MIRACL Trust SSO as an Identity Provider within AWS

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

  1. Log in to Amazon AWS Console and click on IAM under ‘Security, Identity and Compliance’.

  2. Click on Identity providers in the menu on the left.

  3. Click on the Create Provider button: create-provider

  4. Choose SAML from the ‘Provider Type’ dropdown: configure provider

  5. Enter a Provider Name - e.g. ‘MyCompany’.

  6. Upload 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)

  7. Click on Next Step.
    The ‘Verify Provider Information’ page is displayed.

  8. Click on Create.
    A message is displayed: “To use this provider, you must create an IAM role using this provider in the role's trust policy. Do this now.”

  9. Click on Do this now.

  10. Click on Create New Role.

  11. Enter a Role Name - e.g. ‘SSOTest’.

  12. Select the Role for Identity Provider Access radio button.

  13. Click on ‘Grant Web Single Sign-On (WebSSO) access to SAML providers’.

  14. On the next page, ensure that the provider created in step 5 above is selected in the ‘SAML Provider’ drop-down menu.

  15. Click on Next Step followed by Next Step.

  16. Choose an appropriate permissions policy template.

  17. Click on Next Step followed by Create Role.

Configuring your AWS Service Provider profile with MIRACL Trust SSO (IdP-initiated login)

  1. Edit /etc/srv-idp/service_providers/aws.yaml:
profile:
  attribute:
    aws: >-
      <AttributeStatement>
        <Attribute Name="https://aws.amazon.com/SAML/Attributes/Role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <AttributeValue>arn:aws:iam::YOURAWSACCOUNTNUMBER:role/YOURSSOROLE,arn:aws:iam::YOURAWSACCOUNTNUMBER:saml-provider/YOURPROVIDER</AttributeValue>
        </Attribute>
        <Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
          <AttributeValue>{{.SessionUserEmail}}</AttributeValue>
        </Attribute>
      </AttributeStatement>
sp:
  aws:
    description: Amazon Web Services (AWS) Cloud Computing
    issuer: urn:amazon:webservices
    relay_state: ""
    login_url: http://127.0.0.1:8000/login/aws
    logout_url: https://console.aws.amazon.com/iam/logout!doLogout
    metadata: >-
      <?xml version="1.0"?>
      <!-- https://signin.aws.amazon.com/static/saml-metadata.xml -->
      <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="urn:amazon:webservices" validUntil="2017-11-16T00:00:00Z">
        <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAssertionsSigned="true">
          <KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
              <ds:X509Data>
                <ds:X509Certificate>***</ds:X509Certificate>
              </ds:X509Data>
            </ds:KeyInfo>
          </KeyDescriptor>
          <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
          <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
          <AssertionConsumerService index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://signin.aws.amazon.com/saml"/>
          <AttributeConsumingService index="1">
            <ServiceName xml:lang="en">AWS Management Console Single Sign-On</ServiceName>
            <RequestedAttribute isRequired="true" Name="https://aws.amazon.com/SAML/Attributes/Role" FriendlyName="RoleEntitlement"/>
            <RequestedAttribute isRequired="true" Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName" FriendlyName="RoleSessionName"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" FriendlyName="eduPersonAffiliation"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.2" FriendlyName="eduPersonNickname"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.3" FriendlyName="eduPersonOrgDN"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.4" FriendlyName="eduPersonOrgUnitDN"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.5" FriendlyName="eduPersonPrimaryAffiliation"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" FriendlyName="eduPersonPrincipalName"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" FriendlyName="eduPersonEntitlement"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.8" FriendlyName="eduPersonPrimaryOrgUnitDN"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" FriendlyName="eduPersonScopedAffiliation"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" FriendlyName="eduPersonTargetedID"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.11" FriendlyName="eduPersonAssurance"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.2" FriendlyName="eduOrgHomePageURI"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.3" FriendlyName="eduOrgIdentityAuthNPolicyURI"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.4" FriendlyName="eduOrgLegalName"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.5" FriendlyName="eduOrgSuperiorURI"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:1.3.6.1.4.1.5923.1.2.1.6" FriendlyName="eduOrgWhitePagesURI"/>
            <RequestedAttribute isRequired="false" Name="urn:oid:2.5.4.3" FriendlyName="cn"/>
          </AttributeConsumingService>
        </SPSSODescriptor>
        <Organization>
          <OrganizationName xml:lang="en">Amazon Web Services, Inc.</OrganizationName>
          <OrganizationDisplayName xml:lang="en">AWS</OrganizationDisplayName>
          <OrganizationURL xml:lang="en">https://aws.amazon.com</OrganizationURL>
        </Organization>
      </EntityDescriptor>
    sign_response: true
    sign_assertion: true
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      attribute: aws
  1. In the attribute subsection of the first profile section, replace both instances of YOURAWSACCOUNTNUMBER with your actual AWS account number, and also YOURSSOROLE and YOURPROVIDER with the values set in the AWS Console as detailed above.

  2. In the sp: aws: entry in the file, update login_url with your SSO IP address. Note here that the AWS login URL is IdP-initiated (i.e. initiated on your IdP server as opposed to on an AWS-served URL) and, in order to work, must make use of the /login endpoint. To complete the URL the name of the service is appended to the /login endpoint. The name must match the heading of the AWS subsection in the sp config section. Looking at the config you can see that it is aws:

aws-login-endpoint

Note that logout_url is the standard SP logout URL which AWS makes available for SAML IdPs to use, and that the metadata is the standard SP metadata which AWS makes available for IdPs to use in order to connect with them. It has already been entered for you and can be used ‘as is’.

The attribute value in the profile section must be set as aws, in order to invoke the correct settings made in step 2.

  1. The standard AWS metadata is entered in aws: metadata. It is available from https://signin.aws.amazon.com/static/saml-metadata.xml. Note that, if you ever need to download the metadata, 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.

if you are using JSON format for your config file, the " characters need to be escaped with \ to meet the 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 JSON metadata field.

  1. In the authorize subsection, you can control what users are allowed to attempt login. You must use one of the following options:
  • Call up an LDAP setup from an ldap.yaml file stored in e.g /etc/srv-idp/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/srv-idp/config.yaml file make sure you add the aws.yaml to the list of ‘includes’:

includes:
  - core.yaml

# service providers
  - service_providers/aws.yaml
  1. As always after config changes, restart the server with sudo service srv-idp restart

  2. Now your service is configured, you can visit https://<yourssoip>/login/aws or https://<yourssoip>/services to login to the service using IdP-initiated login.

  3. 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.

[/ui-tab] [/ui-tabs]