Matching Service Adapter

What is the Matching Service Adapter? Matching Service Adapter What does the Matching Service Adapter do? Table of contents Benefits of using the Matching Service Adapter Disadvantages of using the Matching Service Adapter Prerequisites How to request the Matching Service Adapter How to install the Matching Service Adapter How to configure the Matching Service Adapter How to configure the Matching Service Adapter for the production and integration environments How to configure the Matching Service Adapter to use with the compliance tool How to obtain certificates for the Matching Service Adapter How to supply Matching Service Adapter metadata Starting the Matching Service Adapter Testing the Matching Service Adapter using the compliance tool Expected matching request Examples Example of matching request for normal cycle matching Example of response from matching service Matching dataset fields: firstname, middlenames, surnames, dateofbirth Matching dataset fields: address Matching dataset fields: cycle3dataset Example of request from hub to Matching Service Adapter (SAML SOAP format) Creating user accounts Monitoring Logging Document history

What is the Matching Service Adapter? The Matching Service Adapter is a software tool supplied free of charge by the GOV.UK Verify team. It simplifies communication between your matching service and the GOV.UK Verify hub service. The hub uses SAML (Security Assertion Markup Language) as its communication method, while government services typically use JSON (JavaScript Object Notation) for their matching services, so a SAML interface is required. Implementing a SAML interface is difficult and expensive, so using the Matching Service Adapter saves government services time and money. Essentially the Matching Service Adapter converts SAML into JSON and vice versa. What does the Matching Service Adapter do? The Matching Service Adapter performs encryption, decryption and signing of SAML messages, and provides simple JSON communication between the Matching Service Adapter and your matching service. The Matching Service Adapter accepts the following: SAML attribute query with a matching dataset (as described in the Identity Assurance Hub Service SAML 2.0 Profile ). The Matching Service Adapter forwards this query as a JSON matching request to your matching service for normal cycle matching this query can also optionally make an unknown user request to the matching service to assist in user account creation when a match is not found (see Creating user accounts for more information) Benefits of using the Matching Service Adapter You can concentrate on the business logic and matching rules for your matching service You don't have to build your own SAML interface Your technical integration team doesn't have to spend time understanding SAML, conforming to the SAML specifications and to the hub service interface specifications Page 2 of 20

Disadvantages of using the Matching Service Adapter You already have an application that provides a SAML interface and the Matching Service Adapter might duplicate or adversely affect this. In this case, please contact the GOV.UK Verify team to discuss your options Prerequisites Java 1.8 (Java runtime environment) For the integration environment only, the hub must allow access to the IP address where the Matching Service Adapter is hosted to allow dynamic fetching of hub metadata How to request the Matching Service Adapter Once you've completed Stage 3: Planning, you request access to the secure site from which you can download the Matching Service Adapter by emailing idasupport+onboarding@digital.cabinet office.gov.uk. How to install the Matching Service Adapter 1. When you re given access by the GOV.UK Verify team, download the Matching Service Adapter from the secure site. 2. Install the Matching Service Adapter jar ( java archive ) file on a target system that complies with the prerequisites listed in Prerequisites. 3. To extract the relevant files and move the truststore to the environment in which you want to use the Matching Service Adapter, execute the following commands, supplying values for the text in square brackets: tar xf Matching Service Adapter build xxx ( year month day ).tar.gz tar xf ida msa xxx.zip mv prod_ida_truststore.ts [path to trust store dir] mv test_ida_truststore.ts [path to trust store dir] In the above commands: xxx represents the build number (year month day) represents the build date, in the format yyyy mm dd Page 3 of 20

[ path to trust store dir] is the URI (Uniform Resource Identifier) where you decide to locate the truststore. This can be anywhere you choose. You specify the truststore location when configuring the Matching Service Adapter (under the configuration option storeuri: ). to use the Matching Service Adapter in the production environment, execute: mv prod_ida_truststore.ts to use the Matching Service Adapter with the compliance tool or in the integration environment, execute: mv test_ida_truststore.ts How to configure the Matching Service Adapter When you start the Matching Service Adapter, you must pass a YAML configuration file ( configuration.yml ) as input. YAML is a human friendly data serialisation standard supported by most programming languages. An example of a YAML configuration file is shown below, followed by an explanation of the configuration. Supply values for the text in square brackets: server: applicationconnectors: type: http port: [application port] adminconnectors: type: http port: [admin port] assertionlifetime: 5m matchingserviceuri: [Matching Service URI] matchingserviceadapterlocation: [Matching Service Adapter Location URI] unknownusercreationserviceuri: [Unknown User Creation Location URI this property is optional] saml: entityid: [matching service adapter entity id] Page 4 of 20

httpclient: timeout: 2s timetolive: 10m cookiesenabled: false connectiontimeout: 1s metadatauri: https://www.[your env].signin.service.gov.uk/saml2/metadata/sp # location to fetch hub metadata from acceptselfsignedcerts: true serviceinfo: name: matching service adapter # If you would like the Matching Service Adapter to report to a graphite instance. metrics: frequency: 30s reporters: type: graphite host: [graphite host] port: [graphite port] prefix: [some prefix of your choosing] privatesigningkeyconfiguration: keyuri: /[path to private key].pk8 privateencryptionkeyconfiguration: keyuri: /[path to private key].pk8 publicsigningkeyconfiguration: keyuri: /[path to pub key].crt keyname: [key name] publicencryptionkeyconfiguration: keyuri: /[path to pub key].crt Page 5 of 20

keyname: [key name] returnstacktraceinresponse: true clienttruststoreconfiguration: storeuri: /[path to trust store dir]/[prod test]_ida_truststore.ts password: puppet featureflagconfiguration: iscertificatechainvalidationrequired: true logging: level: INFO appenders: type: file currentlogfilename: apps home/test rp msa.log archivedlogfilenamepattern: apps home/test rp msa.log.%d.gz logformat: '% 5p [%diso8601,utc}] %c: %XlogPrefix}%m%n%xEx' archivedfilecount: 7 type: console Page 6 of 20

How to configure the Matching Service Adapter for the production and integration environments The above example file configures the Matching Service Adapter to run in both the production and integration environments. Configuring the Matching Service Adapter for the compliance tool is slightly different, as described in How to configure the Matching Service Adapter for the compliance tool. Supply values as described below: 1. enter port numbers for the server application and admin ports 2. do not change the assertionlifetime default timeout. This is the time period allowed for matching a user, starting from the time the matching request query is sent by the hub 3. enter the URIs for your matching service and Matching Service Adapter in matchingserviceuri: and matchingserviceadapterlocation : respectively 4. if you're creating new user accounts when a match is not found (optional), enter this URI in unknownusercreationserviceuri : (see Creating user accounts ) 5. in saml:[matching service adapter entity id], enter the entity id for the Matching Service Adapter in URI format. You create your own URI, possibly to reflect the name of your service, for example: https://< service name >/MSA It's good practice to use the same URI as for the Matching Service Adapter itself, but this isn't mandatory 6. define the httpclient timeout, time to live and connection timeout, for example 2s ( s = seconds, m = minutes). Specify whether cookies are to be enabled ( false or true ) 7. i n metadatauri:, specify the location from which the hub is to fetch your metadata, substituting the name of your environment for [ your env ] in the following URI: https://www.[ your env ].signin.service.gov.uk/saml2/metadata/sp metadatauri: is different for each environment (production and integration) 8. ensure that acceptselfsignedcerts: is set to true Page 7 of 20

9. if you want to use Graphite monitoring software to monitor the Matching Service Adapter s performance (optional), supply the required metrics: frequency, type, host, port and prefix of the reporter 10. enter paths to the location of the public and private key for the following certificates, required to access the production and integration environments: privatesigningkeyconfiguration: privateencryptionkeyconfiguration: publicsigningkeyconfiguration: publicencryptionkeyconfiguration: See How to obtain certificates for the Matching Service Adapter for more details 11. ensure that returnstacktraceinresponse: is set to true 12. in storeuri, enter your truststore URI and specify whether this is for the production or integration environment (called test here). The password is puppet 13.leave the default values for f eatureflagconfiguration unchanged 14.define the logging level (eg INFO ) 15. in appenders: type:, define where you want the logging information to be sent (eg file, console ). You can specify multiple types if required. if you choose file logging (as shown in the above example configuration file), supply a filename for the current log file and, if you choose to archive old events in separate files, supply a filename pattern for the archived log file in archivedlogfilenamepattern When the current log file rotates, the archived log takes its name; %d is replaced with the previous day s date (in yyyy MM dd format) and the file is gzipped (. gz file extension) in logformat:, define the format in which log events display, for example date, time. logprefix adds context to the logging output in archivedfilecount, enter the number of archived files that you want to keep (must be between 1 and 50) More information on configuration is available at Dropwizard Configuration Reference. Page 8 of 20

How to configure the Matching Service Adapter for the compliance tool Follow the steps listed in How to configure the Matching Service Adapter for the production and integration environments ; however, you need to configure certain aspects of the Matching Service Adapter differently for use with the compliance tool, as follows: port numbers the Matching Service Adapter must listen on port 80 (for http) or port 443 (for https) as the compliance tool only allows outbound connections on these ports whitelist IP address whitelist the compliance tool s IP (Internet Protocol) address, as the compliance tool makes a direct SOAP (Simple Object Access Protocol) request to your Matching Service Adapter server. Whitelisting an IP address means that you add it to a list of trusted IP addresses that are allowed access to your network. You re given the compliance tool s IP address ( compliance tool.ipaddress ) by your GOV.UK Verify engagement lead when you are given access to the compliance tool metadata ensure the Matching Service Adapter s metadatauri points to the URL (Universal Resource Locator): compliance tool.metadatauri You re given this URL by your GOV.UK Verify engagement lead when you are given access to the compliance tool How to obtain certificates for the Matching Service Adapter As part of the process for accessing the integration environment to carry out end to end testing of your service, you need to obtain certificates and request access (see steps 5 and 6 in Stage 4 of the GOV.UK Verify Onboarding Guide). This includes obtaining and supplying signed certificates for both your service and for the Matching Service Adapter. You must also obtain these certificates before you can access the production environment. You need the following certificates for the Matching Service Adapter: matching service signature validation certificate. This must be a valid X509 certificate in pk8 PEM format signed by the GDS Test Certificate Authority or the GDS Production Certificate Authority (as appropriate), for example: Page 9 of 20

cat server.crt server.key > server.pem openssl pkcs8 nocrypt in server.pem out server.pk8.pem outform PEM topk8 This certificate is used to validate the digital signature present on all responses sent from the Matching Service Adapter and should correspond to the private key configured for use by the Matching Service Adapter. You can retrieve this (and other details) from your Matching Service Adapter by accessing /matching service/saml2/metadata matching service encryption certificate. This must be a valid X509 certificate signed by the GDS Test Certificate Authority or the GDS Production Certificate Authority (as appropriate), and is used to encrypt the assertions in a request sent from the hub to your Matching Service Adapter. It s decrypted by the private key configured in your Matching Service Adapter. You can retrieve this (and other details) from your Matching Service Adapter by accessing /matching service/saml2/metadata Note: Metadata responses only return the public parts of the signing / encryption certificate; the private key is never returned Follow the procedure described in steps 5 and 6 of Stage 4 of the GOV.UK Verify Onboarding Guide to obtain and supply these certificates. How to supply Matching Service Adapter metadata The Matching Service Adapter has its own metadata that needs to be sent to the GOV.UK Verify support team. To make this easier, we ve provided a metadata endpoint on the Matching Service Adapter itself to generate the metadata based on how you ve configured the Matching Service Adapter. To create the relevant metadata file, access /matching service/saml2/metadata on the Matching Service Adapter after you ve configured it. Starting the Matching Service Adapter To start using the Matching Service Adapter, execute the following command, supplying the path to your configuration file: java jar matching service adapter.jar server [path to configuration file].yml Page 10 of 20

Testing the Matching Service Adapter using the compliance tool Note: For a better experience, we strongly recommend that you use a JSONview plugin for your browser POST the following JSON (via Advanced Rest Client, curl or similar) to the URL compliance tool.msposturi: You are given this URI by your GOV.UK Verify engagement lead when you are given access to the compliance tool Content Type: application/json "matchingserviceentityid": "[entity of the matching service]", "transactionentityid": "[entity id of the transaction (service)]", "matchingserviceendpoint": "[the matching service's endpoint]", "matchingservicepublicsigningcert": "[Public cert to verify the response]", "matchingservicepublicencryptioncert": "[Public cert to encrypt the assertions]" } You receive a response similar to the following: Status 201 Created Location:.../ms test run/8fd7782f efac 48b2 8171 3e4da9553d19 POST the expected matching dataset request (as shown below) to the Location field in the above response (.../ms test run/8fd7782f efac 48b2 8171 3e4da9553d19 in the above example), selecting a value from those in square brackets. For example, if the available values are [true false], select the appropriate value. Expected matching request "persistentid":"[expected unhashed pid]" # required! "firstname": "value": "joe", "verified": "[true false]", Page 11 of 20

"from": "2010 04 04", "to": "2011 03 05" }, "middlenames": "value": "Bob Rob", "verified": "[true false]", "from": "2010 04 04", "to": "2011 03 05" }, "surnames": [ "value":"dou", "verified":"[true false]", "from":"2010 06 05", "to":"2011 02 05" }], "gender": "value": "[NOT_SPECIFIED MALE FEMALE]", "verified":"[true false]", "from":"2010 06 05", "to":"2011 02 05" }, "dateofbirth": "value": "1998 03 05", "verified":"[true false]", "from":"2010 06 05", "to":"2011 02 05" }, "addresses": + [ "lines": ["foo st."], "postcode": "GB1 2PP", "internationalpostcode": "123 GAB", Page 12 of 20

"uprn": "abc", "verified": "[true false]", "from": "2010 06 05", "to": "2010 09 09" }], "levelofassurance":"level_1", "cycle3dataset": "key":"drivers_licence", "value":"123abc" } } In the above expected matching dataset request: the value of addresses (address history) and surnames is an array PersistentId is mandatory you must supply at least one other value (in addition to PersistentId ) Examples To help your understanding, we've provided examples of the following: normal cycle matching request (JSON format) with supplied values response (JSON format) from the Matching Service Adapter to your matching service, followed by an explanation of the matching dataset fields request the hub sends to the Matching Service Adapter (SAML SOAP format) Example of matching request for normal cycle matching "hashedpid": "60ddc43c02b28ac94624299cdc99551b603b77380d4a0310725ff86afed3bb5f", "levelofassurance": "LEVEL_2", "matchid": "_08084c3b 4df0 4f27 ac92 196649d0842e", "matchingdataset": "addresses": [ Page 13 of 20

"lines": [ "1 Two St" ], "postcode": "1A 2BC", "verified": true }, "fromdate": "2007 09 26T00:00:00.000Z", "lines": [ "221b Baker St." ], "postcode": "W4 1SH", "todate": "2007 09 27T00:00:00.000Z", "verified": true }, "fromdate": "2006 09 28T00:00:00.000Z", "lines": [ "1 Goose Lane" ], "postcode": "M1 2FG", "todate": "2006 09 07T00:00:00.000Z", "verified": false } ], "dateofbirth": "value": "1984 02 29", "verified": true }, "firstname": "value": "Jack", "verified": true }, "gender": "value": "MALE", "verified": true Page 14 of 20

} }, "middlenames": "value": "Charles", "verified": true }, "surnames": [ "value": "Brown", "verified": true } ] } Example of response from matching service 200 result : match no match } Matching dataset fields: firstname, middlenames, surnames, dateofbirth These fields have optional from / to attributes in which you can capture historical values. For example, if the user has changed their surname, there's an additional entry for the old surname with the from and to values defining the period for which the name was valid. The new surname only has the from attribute, containing the date from which it was valid. Matching dataset fields: addresses The addresses field contains the value for the postcode attribute for local addresses and the value for the internationalpostcode for foreign addresses. uprn (Unique Property Reference Number) is a unique reference for each property in Great Britain, ensuring accuracy of address data. This is an optional attribute that can contain up to 12 integers and should not have any leading zeros. Page 15 of 20

The addresses field that holds the current address contains a fromdate attribute for the date from which the address is valid. Past addresses also contain the todate attribute. Matching dataset fields: cycle3dataset This field is only present for a cycle 3 matching attempt. Page 16 of 20

Example of request from hub to Matching Service Adapter (SAML SOAP format) The following example shows a request from the hub to the Matching Service Adapter in SAML SOAP format. Page 17 of 20

Creating user accounts If all matching cycles complete without finding a match, you can optionally decide to create a new account for the user. The new account consists of the hashed personal identifier and a subset of specified attributes from the matching dataset supplied by the identity provider. For more information, see Creating user accounts in step 2 of Stage 4 of the GOV.UK Verify Onboarding Guide. If you want to create user accounts in the above circumstances, your matching service must expose an unknown user creation endpoint. The Matching Service Adapter receives a normal SAML attribute query with the matching dataset and makes the following request to this unknown user creation endpoint: "hashedpid": "cadde401539bdb2231a9eb81ae37ec6e32614a0690f8d0b297a73ecf99a05bac", } "levelofassurance":"level_2" The unknown user creation endpoint responds as follows: 00 } "result": success failure Note: success and failure are case sensitive and must be lower case, as shown in the above example Monitoring In both test environments, a health check runs every 60 seconds to ensure that the Matching Service Adapter is functioning correctly. It tests the following: connectivity Matching Service Adapter accepts the hub signature hub accepts the Matching Service Adapter signature Page 18 of 20

In the production environment, Graphite monitoring software continually monitors the Matching Service Adapter s performance. Logging Configure your logging requirements as described in How to configure the Matching Service Adapter for the production and integration environments. The log files are written to disk as per your configuration. How to keep the Matching Service Adapter up to date The GOV.UK Verify support team updates the Matching Service Adapter when required. To ensure you are informed of the updates, contact the GOV.UK Verify support team to ensure you are on the Matching Service Adapter email distribution list. Page 19 of 20

Document history Version Date Author Reason for change 0.1 08/01/15 Jenny Wright Initial draft 0.2 15/01/15 Jenny Wright After review by Oliver Harper, David King, David Illsley, Rebecca Law and Hugh Quigley 1.0 26/01/15 Jenny Wright Approved by David Illsley and Oliver Harper 2.0 28/01/15 Jenny Wright After editorial review 2.1 10/02/15 Jenny Wright Name change: Test hub now called compliance tool. Request access to an environment form removed from Onboarding Guide 2.2 11/05/15 Jenny Wright References to Onboarding pack removed from Onboarding Guide. Change to logging information in configuration file Page 20 of 20