Matching Service Adapter

(1)

Matching Service Adapter

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

(3)

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

[email protected]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 (yearmonthday).tar.gz tar xf idamsaxxx.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

(yearmonthday) represents the build date, in the format yyyymmdd

Page 3 of 20

(4)

[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 humanfriendly 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

(5)

httpClient: timeout: 2s timeToLive: 10m cookiesEnabled: false connectionTimeout: 1s metadataUri: https://www.[yourenv].signin.service.gov.uk/SAML2/metadata/sp # location to fetch hub metadata from acceptSelfSignedCerts: true serviceInfo: name: matchingserviceadapter # 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

(6)

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: appshome/testrpmsa.log archivedLogFilenamePattern: appshome/testrpmsa.log.%d.gz logFormat: '%5p [%d{ISO8601,UTC}] %c: %X{logPrefix}%m%n%xEx' archivedFileCount: 7  type: console Page 6 of 20

(7)

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. in metadataUri:, specify the location from which the hub is to fetch your metadata, substituting the name of your environment for [yourenv]in the following URI:

https://www.[yourenv].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

(8)

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 featureFlagConfiguration 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 yyyyMMdd 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

(9)

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 (compliancetool.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): compliancetool.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

endtoend 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

(10)

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 /matchingservice/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 /matchingservice/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 /matchingservice/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 matchingserviceadapter.jar server [path to configuration file].yml Page 10 of 20

(11)

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 compliancetool.MSPostUri: You are given this URI by your GOV.UK Verify engagement lead when you are given access to the compliance tool ContentType: 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: .../mstestrun/8fd7782fefac48b281713e4da9553d19 POST the expected matching dataset request (as shown below) to the Location field in the above response (.../mstestrun/8fd7782fefac48b281713e4da9553d19 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

(12)

"from": "20100404", "to": "20110305" }, "middleNames": { "value": "Bob Rob", "verified": "[true | false]", "from": "20100404", "to": "20110305" }, "surnames": [{ "value":"Dou", "verified":"[true | false]", "from":"20100605", "to":"20110205" }], "gender": { "value": "[NOT_SPECIFIED | MALE | FEMALE]", "verified":"[true|false]", "from":"20100605", "to":"20110205" }, "dateOfBirth": { "value": "19980305", "verified":"[true | false]", "from":"20100605", "to":"20110205" }, "addresses": + [{ "lines": ["foo st."], "postCode": "GB1 2PP", "internationalPostCode": "123 GAB", Page 12 of 20

(13)

"uprn": "abc", "verified": "[true | false]", "from": "20100605", "to": "20100909" }], "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": "_08084c3b4df04f27ac92196649d0842e", "matchingDataset": { "addresses": [ { Page 13 of 20

(14)

"lines": [ "1 Two St" ], "postCode": "1A 2BC", "verified": true }, { "fromDate": "20070926T00:00:00.000Z", "lines": [ "221b Baker St." ], "postCode": "W4 1SH", "toDate": "20070927T00:00:00.000Z", "verified": true }, { "fromDate": "20060928T00:00:00.000Z", "lines": [ "1 Goose Lane" ], "postCode": "M1 2FG", "toDate": "20060907T00:00:00.000Z", "verified": false } ], "dateOfBirth": { "value": "19840229", "verified": true }, "firstName": { "value": "Jack", "verified": true }, "gender": { "value": "MALE", "verified": true Page 14 of 20

(15)

}, "middleNames": { "value": "Charles", "verified": true }, "surnames": [ { "value": "Brown", "verified": true } ] } } Example of response from matching service 200 { result : match|nomatch } 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

(16)

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

(17)

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

(18)

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

(19)

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 uptodate

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

(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

Matching Service Adapter