The GOV.UK Verify onboarding process

Transcription

1 To help us improve, this site uses cookies. Docs» GOV.UK Verify documentation GOV.UK Verify Onboarding Guide This guide is for government service providers wanting to learn about and integrate with GOV.UK Verify. Any government service that requires assured identities must use GOV.UK Verify for the identity verification element. The guide outlines the 6 stages to onboarding with GOV.UK Verify, and describes how to complete each stage. It s in beta, so it isn t a comprehensive guide yet. We ll regularly expand and improve it. The GOV.UK Verify onboarding process Before beginning the onboarding process you may find it useful to read the Introduction to GOV.UK Verify. There are 6 stages to the GOV.UK Verify onboarding process: Stage 1 - Proposal Stage 2 - Needs analysis Stage 3 - Planning Stage 4 - Build and integration testing Stage 5 - Production onboarding Stage 6 - In beta Find out how your service moves through the onboarding process. Introduction to GOV.UK Verify GOV.UK Verify is the new way for people to prove who they are online, so they can use government services safely. General information about GOV.UK Verify Introducing GOV.UK Verify GOV.UK blog post: What is identity assurance? The GOV.UK Verify blog contains lots of information about the service. We recommend subscribing to keep up to date with what s going on Information for technical teams Architecture overview Build a matching service How the service is performing GOV.UK Verify performance dashboard How your service moves through the GOV.UK Verify onboarding process There are 6 stages to the GOV.UK Verify onboarding process. To move from one stage to the next, a set of outputs must be completed. You can find these outputs, along with information on how they can be completed, in this onboarding guide. Our experience in working with teams across government that want to use GOV.UK Verify has shown a

2 Our experience in working with teams across government that want to use GOV.UK Verify has shown a need to complete the onboarding stages in full and in order. The onboarding process has been designed to help teams do the right things at the right time so the right preparations are in place for a successful integration. Your service moves to the next stage once all the outputs have been completed. Stage 1: Proposal Purpose of this stage To establish whether your service needs to use GOV.UK Verify and to propose how you intend to use GOV.UK Verify as part of your service. Prerequisites before entering this stage None What s expected from your service Complete an initial assessment of your service that indicates the type of identity assurance (eg citizen, agent, organisation) and level of assurance your service may require Your service s Senior Information Risk Officer has confirmed the need for GOV.UK Verify A proposal showing how you intend to use GOV.UK Verify What the GOV.UK Verify team will do Assess your service s proposal to use GOV.UK Verify Outputs required to complete this stage Your service has made a decision that it needs to use GOV.UK Verify Your proposed use of GOV.UK Verify is appropriate A proposal showing how you intend to use GOV.UK Verify Before any detailed analysis takes place, we want to make sure that GOV.UK Verify is right for your service. Your proposal will help us understand whether GOV.UK Verify can meet the identity assurance needs of your service. It will also show how you intend to use GOV.UK Verify as part of your service. Your proposal should include the following: Questions to consider Does your service present existing data records back to users? Your need for identity assurance Will your service be paying people? Is there a regulatory requirement for your users to be verified? Do you need to register users for your service? What are the user needs being met by this service? What level of assurance will your service require? Who are your users and how many are there? A short description of the service Has work has already started? Has a discovery or alpha taken place? Will the new service replace or operate alongside an existing service? When are you planning to launch your service? Are you dependent upon external suppliers to build your service?

3 Are you dependent upon external suppliers to build your service? What are the user journeys for your new service? Where will GOV.UK Verify fit in? Design of the new service Does your service already hold data about the user or will you be creatingnew use Has your service recently conducted an analysis of the quality and completeness Does your service have a strategy for matching users to your local records? Stage 2: Needs analysis Purpose of this stage To identify the specific needs of your service and confirm that they can be met; define how GOV.UK Verify will fit into your service; and align expectations on what will be done and where responsibilities lie. Prerequisites before entering this stage See required outputs from Stage 1 What s expected from your service Help us complete a detailed analysis of the needs of your service Share any planning constraints related to your service Complete a full risk assessment of your digital service and confirm that your service needs to use GOV.UK Verify Decide the level of assurance your service requires and validate this decision with your Senior Information Risk Officer (SIRO) Document and share the proposed user journeys for your service Identify, inform and engage important stakeholders of your service s intention to use GOV.UK Verify and secure their approval Read the MOU (memorandum of understanding) and raise any queries with your GOV.UK Verify engagement lead Review your service s data quality and consider the design of your matching service What the GOV.UK Verify team will do Request information to complete a detailed analysis of the needs of your service and understand any planning constraints Provide support and guidance on your risk assessment and level of assurance decision Provide guidance on the development of your user journeys Meet your important stakeholders as required Share the MOU and answer any questions your service may have Outputs required to complete this stage A shared understanding of the detailed needs of your service A shared understanding of any planning constraints related to your service Your organisation has made an informed decision that it needs to use GOV.UK Verify You have reached a decision on the level of assurance your service requires Your proposed use of GOV.UK Verify has been approved by the GOV.UK Verify team Your important stakeholders are aware of and approve of, in principle, your plan to use GOV.UK Verify Detailed analysis of your service To identify and meet your specific needs, we first need a detailed understanding of your service. This

4 To identify and meet your specific needs, we first need a detailed understanding of your service. This will help prepare for planning in Stage 3. Examples of what your GOV.UK Verify engagement lead may ask for are: Who uses the service? Do you have demographic data or other information about your users? What s the anticipated number of users? Are there any known peaks in the use of your service? How frequently is your service accessed? What s the cost relating to identity fraud for your service? How much, if any, does your service spend on identity assurance? When do you expect to start using GOV.UK Verify? Share any planning constraints related to your service Before any planning starts, we need to know if there are any planning constraints that may affect the onboarding of your service. For example: commitments regarding when your service should be live policy factors relating to the use of your service legislative dependencies contracts you have, or are expected to have, with external suppliers to support delivery of your service public announcements regarding your service Stage 3: Planning Purpose of this stage To produce a plan showing what will be done, and get the approvals you need to build and integrate with GOV.UK Verify. Prerequisites before entering this stage See required outputs from Stage 2 What s expected from your service Share your plans showing how you intend to integrate GOV.UK Verify into your service Agree the plan with your GOV.UK Verify engagement lead Secure any approvals you need Identify all user scenarios and design suitable user journeys Complete the operations contacts form Your service has shared content for the pages relating to GOV.UK Verify Raise a ticket with the GOV.UK content team and add your engagement lead to the ticket What the GOV.UK Verify team will do Help you plan your service s integration with GOV.UK Verify Meet your important stakeholders as required to help you get the approvals your service needs Provide guidance on the development of your user journeys Include your service in the pipeline of services as reported to the identity assurance programme board Share the operations contacts form Include your service in the pipeline of services as reported to the identity assurance programme board Outputs required to complete this stage A plan showing how you intend to integrate GOV.UK Verify into your service Any approvals you require to proceed with onboarding

5 Any approvals you require to proceed with onboarding User journeys showing how you will use GOV.UK Verify User journeys showing what happens to a user where they are unable to complete verification of their identity Inclusion of the service in the pipeline as reported to the programme board Share contact details for your operations team and escalations Your plan for integrating GOV.UK Verify into your service Integrating GOV.UK Verify into your service is a complex process that requires planning. We recommend working closely with your GOV.UK Verify engagement lead when putting your plans together. This helps make sure the support you need is available when you need it, and means we can share lessons other services have learnt. The table below contains some of the activities and questions to help you put your plan together. Each service is different and will have its own unique set of things to consider, so this should be treated as guidance rather than a comprehensive list. We re not looking for too much detail, just enough to show your approach and give an idea of what will be delivered, by whom, and when within your service. Things to plan Delivery milestones Questions to consider What are your expected dates for alpha, beta and live? When will the major components of your service be delivered? What does your service need to build? Who will build each component? Build, test and integration What s your approach to testing? Who will perform your testing? When will your service make use of GOV.UK Verify test and integration environments? How will your service match users to your records? Matching Which internal data sources will the users of your service match to? Will your department use a shared identifier across multiple services? If your service has any existing APIs or technology that enables users to be matched to Who has an interest in your service? Stakeholder management Who will your service inform and engage? Who will your service need to secure approval from to proceed? What will your service communicate to your users regarding service changes? How will your service do this? Communications What s your service s approach to handling the media? What materials and assets does your service need? When does your service need them? Does your service have agents that require briefing materials? What s your service s approach for beta? Scale up approach How will your service scale up the number of users accessing your service? How many users does your service expect to have? How will your service attract users? Skills Do you have the right skills in your team?

6 How will your service support users who encounter difficulties in accessing your service End-user support How will your service interact with GOV.UK Verify support? What s your service s plan for assisted digital support? How will your service share briefing materials with support centres? Does your service have a support transition plan for when your service moves into live? How will your service ensure your service remains operational? Does your service have the appropriate tools to triage user issues? Operational support model What are your Service Level Agreements? How will your service manage out of hours support? How will your service manage out of hours security incidents? How will your service manage out of change notifications? Stage 4: Build and integration testing Purpose of this stage For your service to build a complete end-to-end service and provide evidence of SAML interoperability testing using the compliance tool. Prerequisites before entering this stage See required outputs from Stage 3 Outputs required to complete this stage Successful completion of integration testing, including performance testing A full demonstration of all user journeys showing that they work for users Your operations team have met the GOV.UK Verify operations team How to build, integrate and test your service Read the GOV.UK Verify Architecture Overview for important background information on the architecture. Complete the steps below in the following order: Step 1. Build a service that sends authentication requests to, and receives authentication responses from, the GOV.UK Verify hub Step 2. Build a matching service and use the Matching Service Adaptor (MSA) provided by the GOV.UK Verify team to integrate it to the GOV.UK Verify hub Step 3. Carry out SAML interoperability testing using the compliance tool Step 4. Provide evidence of successful testing with the compliance tool Step 5. Request test certificates for the integration environment Step 6. Request access to the integration environment Step 7. Conduct end-to-end testing of the entire user journey in the integration environment Onboarding pack You ll need an onboarding pack that contains the URIs, credentials and other details that have been purposely omitted from the guide. Omitted details are highlighted as Onboarding Pack: [key name], where lookup.key is the YML path to find the omitted value. To request an onboarding pack, idasupport+onboarding@digital.cabinet-office.gov.uk. Step 1: Build your service

7 Build a service that sends authentication requests to, and receives authentication responses from, the GOV.UK Verify hub. Provide public keys and endpoints for authentication requests. Configure firewalls as appropriate. Key requirements You must meet the following technical requirements to integrate your service with GOV.UK Verify. These requirements are high level and each requirement is supported by technical documentation that gives specific details on meeting the requirement. Accreditation and commercial requirements are covered in framework documentation available from the GOV.UK Verify team on request. You are expected to: build a matching service based on the Identity Assurance Hub Service SAML 2.0 Profile that integrates with the hub service, or build a matching service that integrates with the Matching Service Adaptor (MSA) provided by the GOV.UK Verify team optionally, provide an endpoint on the matching service that handles creation of an unknown user manage cryptographic keys used for signing and encryption provide endpoints for authentication requests configure firewalls to connect to necessary environments build or procure the implementation of the Identity Assurance Hub Service SAML 2.0 Profile to send authentication requests and receive authentication responses provide details of required self-asserted attributes for matching engage in the test environment and carry out necessary tests The GOV.UK Verify team provides: test environments to support interoperability testing with the hub and end-to-end testing of user journeys access to a Public Key Infrastructure (PKI) used to sign cryptographic keys the ability for you to create test users to be used in the testing process SAML (Security Assertion Markup Language) adaptor that integrates with your matching service and translates SAML into a common data language (JSON). This is the MSA SAML integration You must understand SAML and in particular how the GOV.UK Verify team has implemented the SAML 2.0 protocol. This is defined in the Identity Assurance Hub Service SAML 2.0 Profile. All services connecting to the GOV.UK Verify hub must be compliant with this specification. SAML profile The identity assurance SAML 2.0 Profile describes in detail how we conform to the OASIS Security Assertion Markup Language (SAML) V2.0. It describes the methods used and the rules applied to the authentication process from the perspective of identity providers, service providers and matching services. The SAML 2.0 Profile is implemented using the SAML Authentication Request protocol and the SAML Attribute Query protocol. It uses the existing SAML Web SSO (single sign on) and Assertion Query/Request profiles. We assume that the user is using a standard commercial web browser and that their authentication with the identity provider takes place outside the scope of SAML. Note: Even though based on the Web SSO profile, the Identity Assurance SAML 2.0 Profile doesn t support single sign on across GOV.UK services, as no user case currently exists for it. The identity assurance SAML 2.0 Profile follows the criteria for conformance defined in the SAML 2.0

8 The identity assurance SAML 2.0 Profile follows the criteria for conformance defined in the SAML 2.0 document titled Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0. You must adhere to the following sections of this document: 3.4 Implementation of Encrypted Elements 3.6 Metadata Structures 3.7 Metadata Interoperation 4 XML Digital Signature and XML Encryption 5 Use of SSL 3.0 or TLS 1.0 We recommend that you implement all items described as optional in the SAML 2.0 Profile (as well as the mandatory items) because of the possibility that any identity provider may use any optional item. Useful SAML documents We advise you familiarise yourself with the following OASIS SAML documents, on which we have defined the SAML 2.0 Profile: SAML core (saml-core-2.0-os.pdf) SAML profiles (saml-profiles-2.0-os.pdf) SAML conformance (saml-conformance-2.0-0s.pdf) The following identity assurance SAML standards are also available: Identity Assurance Hub Service Profile: SAML Attributes - describes matching dataset and fraud event assertion attributes Identity Assurance Hub Service Profile: Authentication Contexts - describes values used to specify levels of assurance for SAML authentication requests and responses to those requests from identity providers Reverifying an identity (optional) Some services may need additional assurance when submitting user data, requiring the user to reverify their identity. For example, in 2015, users completing their HMRC Self Assessment online must sign in when they start the assessment and then again when they are ready to submit it. Users also have to reverify their identity if their session times out. In these circumstances, using the optional journey_hint parameter directs the hub to take users straight back to the identity provider they previously selected, instead of presenting them with all the identity providers and making them choose again. This enhances their user experience. Specifying the journey_hint parameter On the SAML form you generate to submit an AuthenticationRequest to the hub, POST the journey_hint input as well as the SAMLRequest and RelayState input. Enter one of the following values in journey_hint, as appropriate: submission_confirmation for reverifying an identity after the user has made their submission session_expiry for reverifying an identity when a session has timed out The following example shows the journey_hint parameter with a value of submission_confirmation : <form action=" method="post"> <input value="pd94bwwgdmvyc2lvbj0ims4wiiblbmnvzgluzz0ivvrgltgip..." name="samlrequest" type="hidden"> <input value="425" name="relaystate" type="hidden"> <input value="submission_confirmation" name="journey_hint" type="hidden"> <input id="continue-button" value="click here to continue" type="submit"> </form> SAML integration commercial off the shelf products You are free to use SAML integration commercial off the shelf products like Shibboleth to simplify

9 integration of services to the GOV.UK Verify hub. The initial implementation of the identity assurance SAML profile supported Web SSO within the standard, but not in line with how most commercial off the shelf products have implemented the standard. As a consequence, we ve changed the identity assurance SAML profile so that you can use products, such as Shibboleth and ForgeRock OM, to simplify integration of services to the GOV.UK Verify hub. These products enable web applications written with any programming language or framework to integrate natively with popular web servers such as Apache and IIS to integrate with the GOV.UK Verify hub service. We ve detailed the configuration required to implement Shibboleth on Apache web server to integrate the Shibboleth application to the GOV.UK Verify hub. Setting up Shibboleth To try out Shibboleth, set up a simple website with one public and one secure page. This will run on a vagrant box. The website then pretends to be test-rp and uses the compliance tool. Starting with Ubuntu LTS and Vagrent, create a Vagrantfile, setting box, ip address and hostname. An example can be found here. Note: Use ubuntu/precise64 if you re using a Linux system Start it up and log on to it: vagrant up vagrant ssh Update all installed packages: sudo apt-get update sudo DEBIAN_FRONTEND=noninteractive apt-get -y upgrade The DEBIAN_FRONTEND is to avoid the GRUP graphical installer. Install Apache: sh sudo apt-get -y install apache2

10 Add a secure resource: sudo mkdir /var/www/secure sudo cp /var/www/index.html /var/www/secure/index.html sudo vi /var/www/secure/index.html Change it so you can see it s the secure one. Test that Apache and the pages work: Goto Goto Install Shibboleth: sudo apt-get -y install shibboleth-sp2-schemas libapache2-mod-shib2 Check the Shibboleth installation: cd /etc/shibboleth shibd -t This will have some problems, we ll fix them next. You ll now need to create 3 certificates using this script../create-certificate.sh signing./create-certificate.sh encryption./create-certificate.sh msa_x509 In the vagrant box: sudo cp /vagrant/signing.pem /etc/shibboleth sudo cp /vagrant/signing_certificate.pem /etc/shibboleth sudo cp /vagrant/encryption.pem /etc/shibboleth sudo cp /vagrant/encryption_certificate.pem /etc/shibboleth sudo cp /vagrant/msa_x509.pem /etc/shibboleth sudo cp /vagrant/msa_x509_certificate.pem /etc/shibboleth Configure the identity provider In the vagrant box: Create metadata file /etc/shibboleth/hub-metadata.xml. Use the following template and replace with your data: <?xml version="1.0" encoding="utf-8"?> <md:entitydescriptor entityid="{msa entity id}" xmlns:md="urn:oasis:names:tc:saml:2.0:metadata" xmlns:xsi=" ID="_b731f22b-ea6e-46f8-be92-c9b745d00479" validuntil=" T00:00:00.000Z" xsi:type="md:entitydescriptortype"> <md:idpssodescriptor protocolsupportenumeration="urn:oasis:names:tc:saml:2.0:protocol" xsi:type="md:idpssodescriptortype"> <md:keydescriptor use="signing" xsi:type="md:keydescriptortype"> <ds:keyinfo xmlns:ds=" xsi:type="ds:keyinfotype"> <ds:keyname xmlns:xs=" xsi:type="xs:string">{msa entity id}</ds:keyname> <ds:x509data xsi:type="ds:x509datatype">

11 <ds:x509data xsi:type="ds:x509datatype"> <ds:x509certificate>{msa x509 certificate here}</ds:x509certificate> </ds:x509data> </ds:keyinfo> </md:keydescriptor> <md:singlesignonservice Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="{hub sso uri: name here>/saml2/sso}" /> </md:idpssodescriptor> </md:entitydescriptor> For an example file see here. Configuring Shibboleth: Make the following changes to /etc/shibboleth/shibboleth2.xml: Changes to the ApplicationDefaults tag attributes: Change the value of entityid to <your entity id>. Add requiresignedassertions= false. Add signing= true. Remove the SSO tag: Add the following after the Logout tag: <SessionInitiator type="chaining" Location="/Login" isdefault="true" id="login" entityid="{msa entity id}"> <SessionInitiator entityid="{msa entity id}" acsbyindex="true" outgoingbindings="urn:oasis:names:tc:saml:2.0:bindings:http-post" type="saml2" template="bindingtemplate.html"/> </SessionInitiator> Remember to change the {msa entity id} in the above tag. Add the following as the last thing in the Sessions tag: <md:assertionconsumerservice Location="/SAML2/POST" index="1" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP- POST" isdefault="true" /> Changes to the CredentialResolver tag: Replace the tag with these 2 tags <CredentialResolver type="file" key="{your signing key name}.pem" certificate="{your signing cert name}.pem"/> <CredentialResolver type="file" key="{your encryption key name}.pem" certificate="{your encryption cert name}.pem"/> Add this tag <MetadataProvider type= XML file= hub-metadata.xml />. For an example file see here. Recheck the config: shibd -t There should now be no problems. Configuring Apache: sudo a2enmod proxy sudo a2enmod proxy_http sudo a2enmod shib2 sudo apachectl configtest sudo service apache2 restart

12 sudo service apache2 restart sudo service shibd restart Add this Location elements to /etc/apache2/sites-available/default, below the line beginning with DocumentRoot: <Location /> AuthType shibboleth ShibRequestSetting requiresession false ShibUseHeaders On Require Shibboleth </Location> <Location /secure> AuthType shibboleth ShibRequestSetting requiresession true ShibUseHeaders On Require valid-user </Location> An example can be found here. Restart Apache and Shibboleth: sudo service apache2 restart sudo service shibd restart Set up the compliance tool: Use the following data to make the compliance tool work: { } "rpentityid":"<your entity id>", "assertionconsumerserviceurl":" ip address>/shibboleth.sso/saml2/post", "signingpubliccert":"<your public signing certificate>", "encryptionpubliccert":"<your public encryption certificate>", "expectedpid":"donaldid", "matchingserviceentityid":"<msa entity id>", "matchingservicesigningprivatecert":"<msa private key (pem format)>", "usesimpleprofile":true An example can be found here Test it: Go to ip address> and you should see the default page. Go to ip address>/secure and you should be redirected to the compliance tool. Step 2: Build a matching service When a user has been authenticated and their identity provided by the GOV.UK Verify hub, you need to match them to their record in your service (local identifier). You do this by building a matching service, which must be within your security domain. Optionally, if no match can be found, the matching service can create a new user account. See creating user accounts for more information. All SAML interaction with the GOV.UK Verify hub must conform to the SAML 2.0 Profile implemented by the GOV.UK Verify team. Your matching service responds to matching requests from the hub service in the form of an

13 Your matching service responds to matching requests from the hub service in the form of an <AttributeQuery>. Read Build a matching service for a full description of the matching service. Creating user accounts (optional) If all 3 matching cycle matches fail to find a match for the user s identity in your records, you can choose to create a new account for the user based on the hashed persistent identifier and a subset of specified attributes from the matching dataset returned by the identity provider. Creating new accounts is optional and, if you decide to do this, you must ensure your matching service supports this feature. Prerequisites 1. Build your matching service to support creation of new accounts if matching fails. 2. Ensure your matching service exposes the User Account Creation URI endpoint. This is the fully qualified URI to which the hub makes Unknown User Attribute Query requests (message flow number 7 in the message flow diagram below). This endpoint must accept the following JSON: [{ "hashedpid": "<some string value>", "levelofassurance": "<the level of assurance, e.g. LEVEL_1>" }] You also have to specify this URI on the Request access to an environment form that you fill in when requesting access to the integration and production environments. This form is available from your engagement lead. 3. Ensure the User Account Creation URI endpoint returns the following JSON, choosing SUCCESS or FAILURE as appropriate: [{ "result": "<SUCCESS or FAILURE>" }] 4. Configure your Matching Service Adapter to create new user accounts by supplying the User Account Creation URI in unknownusercreationserviceuri: in the configuration file. See Matching Service Adapter for a description of how to configure the Matching Service Adapter. 5. Provide the hub with a list of the attributes you want to be returned to your service when creating new user accounts. The options are: FIRST_NAME MIDDLE_NAME SURNAME DATE_OF_BIRTH CURRENT_ADDRESS CYCLE_3 You define your required attributes on the Request access to an environment form. User account creation message flow The diagram below shows the message flow for user account creation (happy path), followed by an outline description of the process.

14 1. Message flow number 1 in the above diagram: Your service sends a request to the hub to authenticate the user s identity, forwarded by the hub to the identity provider. 2. The identity provider authenticates the user and sends the user s matching dataset (MDS) to the hub. 3. The hub passes the matching dataset and the persistent identifier to the Matching Service Adapter. 4. The Matching Service Adapter hashes the persistent identifier and forwards it with the matching dataset to your matching service. Your matching service tries to find a match for the user in your records, using cycle 0, then cycle 1 if necessary, and then cycle 3 if necessary. Note: The Matching Service Adapter hashes the persistent identifier to prevent it being used by other services, as hashing makes it meaningless to them. 5. Your matching service sends a match or no match response to the Matching Service Adapter. 6. The Matching Service Adapter forwards the match or no match response to the hub. 7. If there s no match, even after the user-asserted match (cycle 3), the hub checks your matching service to see if you wish to receive certain attributes (specified by you) from the matching dataset so that you can create a new user account, and then makes an Unknown User Attribute Query request. 8. If your matching service supports creating new user accounts, the hub passes the persistent identifier and level of assurance to the Matching Service Adapter. The hub passes on the level of assurance to prevent identity theft via fake uplifting, ie the act of being lifted from one level of assurance to a higher one. 9. The Matching Service Adapter forwards the hashed persistent identifier and level of assurance to your matching service. Your matching service then typically creates a new record for the user (called a local identifier), linking the hashed persistent identifier and level of assurance to that record. However, it s up to you to define what your matching service does with the hashed persistent identifier and level of assurance. Note: Your matching service must not add attributes to your local records at this point. 10. If your matching service successfully creates a new account (or does whatever you specify), it returns a SUCCESS response to the Matching Service Adapter. If your matching service fails to create a new account (or fails to do whatever you specify), it returns a FAILURE response to the Matching Service Adapter (eg because the hashed persistent identifier already exists in the system). It returns a urn:oasis:names:tc:saml:2.0:status:responder and no attributes are extracted from the matching dataset. 11. The Matching Service Adapter extracts your specified attributes from the matching dataset (if

15 available). 12. The Matching Service Adapter returns these attributes to the hub. 13. If the response is SUCCESS, the hub sends your service the attributes and hashed persistent identifier. Your service uses the hashed persistent identifier to look for a mapped local identifier and then creates a new account, associating the attributes with the local identifier. Note: To create a user account, the Matching Service Adapter must send the attributes and hashed persistent identifier to your service via the hub (message flows 12 and 13). This is because of user control (the user must give their informed consent to the information being sent) and data minimisation (the service only receives the restricted set of attributes it needs, not the full matching dataset). For more information see the Privacy and Consumer Advisory Group: Draft Identity Assurance Principles. Matching Service Adapter The GOV.UK Verify team provides you with a Matching Service Adapter (MSA) to integrate your matching service with the GOV.UK Verify hub. The MSA essentially converts the SAML used by the hub into the JSON used by your matching service. You need to configure and operate the MSA to suit your service. We strongly recommend that you use the MSA as it enables you to concentrate on the business logic and rules for your matching service rather than on conforming to the SAML specification. However, if you decide not to use it, please contact us so that we can ensure your proposed alternative meets the requirements. Read the Matching Service Adapter document for a full description of the MSA, including how to configure and install it on different environments. Step 3: Test your service using the compliance tool You use the compliance tool for SAML interoperability testing before testing complete user journeys in the integration environment. The compliance tool enables you to carry out isolated testing of both the connection from your service to the hub and the connection from the hub to the MSA. We recommend that you use the compliance tool as the first step for all development because it gives the most reliable and rapid feedback for SAML integration issues. We also advise you to consider using the compliance tool as part of your continuous integration pipeline, as changes always maintain backwards compatibility. Produce a high-level test strategy for both the compliance tool. This should cover what you re going to test and how you are going to test it. How to use the compliance tool In summary, you need to: connect to the compliance tool provide metadata for your service, the associated matching service and the MSA conduct SAML interoperability testing provide evidence of successful testing with the compliance tool before starting end-to-end testing in the integration environment (see step 4) More detail on the compliance tool is provided below. The compliance tool enables you to send a number of different canned responses to your service. It ignores all interactions with your matching service and instead, using the information provided in the initial post, generates the assertion normally provided by the matching service. Another, separate part of the compliance tool allows you to test your matching service to SAML integration. You need to send all the information required to generate a response to a compliance tool URI via a

16 You need to send all the information required to generate a response to a compliance tool URI via a JSON post. These details include: entity id assertion consumer service URL signing public certificate encryption public cert expected PID matching service entity id matching service signing private certificate user account creation required attributes (optional field) Note: This data is persisted in memory, meaning that until the next deployment, you don t need to resubmit this data. We would suggest that you consider resubmitting the data for each test run, but not between each test case. Note: User account creation is an optional list of fields for account creation: FIRST_NAME FIRST_NAME_VERIFIED MIDDLE_NAME MIDDLE_NAME_VERIFIED SURNAME SURNAME_VERIFIED DATE_OF_BIRTH DATE_OF_BIRTH_VERIFIED CURRENT_ADDRESS CURRENT_ADDRESS_VERIFIED CYCLE_3 Note: The matching service signing private certificate needs to be in pk8 PEM format, for example: cat server.crt server.key > server.pem openssl pkcs8 -nocrypt -in server.pem -out server.pk8.pem - outform PEM -topk8 You can consume the hub s metadata from the URI Onboarding Pack: compliance-tool.metadatauri. Use Accept:application/samlmetadata+xml to obtain xml and Accept:application/json to get json format. Use this to set up your environment to point at the compliance tool. Once the set up, SAML requests are consumed by the compliance tool. When the compliance tool receives a request, it validates it and displays PASSED or FAILED, together with any additional messages that relate to the issues encountered. At this point, select the link responsegeneratorlocation to bring up a JSON document with a set of test cases. When you select the link executeuri, the appropriate SAML response is sent to your service enabling you to validate the expected behaviour of your service. Using the compliance tool: example Note: We strongly recommend that you use a JSONview plugin for your browser to improve viewing. 1. POST the following JSON (via Advanced Rest Client or curl or similar) to the URL: Onboarding Pack: compliance-tool.rpposturi: Content-Type: application/json { "rpentityid":"[entity Id for your service]", "assertionconsumerserviceurl":"[url that will consume responses from the hub]", "signingpubliccert":"[base 64 encoded public cert used to validate signatures]", "encryptionpubliccert":"[base 64 encoded public cert for encryption]", "expectedpid":"[user id that will be returned in the assertion from the matching service]", "matchingserviceentityid":"[entity id of the matching service]", "matchingservicesigningprivatecert":"[private key that the matching service would use to sign the messages]"

17 "useraccountrequiredattributes": "[ list of attributes that RP requires for account creation. eg FIRST } You receive a response similar to the following: Status 200 Created 2. POST the expected matching dataset request (as shown below) to the Location header in the above response. 3. Navigate (via a browser or a suitably scripted alternative) to your service. 4. Click on the link that starts your authentication flow. 5. If the status is PASSED, select the link provided in responsegeneratorlocation. 6. Select the executeuri link on the test case you wish to execute. Screencast You can download a screencast (compliance-toolforrp) that shows how to use the compliance tool. To request access to the secure site from which you can download compliance-toolforrp, send a request to idasupport+onboarding@digital.cabinet-office.gov.uk. Step 4: Provide evidence of successful testing with the compliance tool To ensure confidence in your service, your matching service and interaction with the GOV.UK Verify hub, you need to provide the GOV.UK Verify team with evidence of successful testing. The evidence typically consists of a test report. After this, you can carry out end-to-end testing in the integration environment (see steps 5, 6 and 7). Step 5: Request test certificates for the integration environment GOV.UK Verify is a secure service based on encryption and signing messages. To interoperate with the GOV.UK Verify hub, you need to obtain signed certificates from the Government Digital Services (GDS) public key infrastructure (PKI) for both the integration and production environments. Follow the procedure below to obtain the necessary signed certificates. Obtain these certificates before you request access to the integration or production environment, as you need to enter details of the certificates on the form used to request access. A complete description of the GDS PKI, the Certification Practice Statement, is available on request. Certificates A certificate is a file that contains a public key. Data encrypted with a public key can only be decrypted with the corresponding private key, and vice versa. You need to generate both private and public keys before you request certificates. The different types of certificates relevant to service providers are: SAML signing - contains a public key that the receiver uses to decrypt a message encrypted with the sender s private key. This provides the receiver with assurance as to the sender s identity SAML encryption - contains a public key that the sender uses to encrypt a message that the receiver decrypts using their corresponding private key. This provides the sender with assurance that only the receiver can decrypt the message TLS (Transport Layer Security) - used for endpoints and associated with a URL. This certificate type is typically used for your service What certificates do you need? You need to obtain the following certificates for an environment (integration or production) before you

18 can use that environment: 2 certificates for your service - SAML signing and SAML encryption 2 certificates for your Matching Service Adapter - SAML signing and SAML encryption You also need the following certificates: 2 certificates for the hub, obtained automatically by the Matching Service Adapter - SAML signing and SAML encryption a hub public SAML signing certificate to validate the authenticity of SAML assertions from the hub. You obtain this by ing GOV.UK Verify at idasupport+onboarding@digital.cabinet-office.gov.uk How to request certificates You request certificates from the appropriate GDS certificate authority. A certificate authority is a service that signs and subsequently verifies the authenticity of digital certificates. GOV.UK Verify uses 2 certificate authorities: GDS Test CA, which issues certificates for non-production environments such as the integration environment. Test certificates are valid for 2 years GDS CA, which issues certificates for production environments only. Production certificates are valid for 6 months Only certificates approved by the GDS CAs can be used with GOV.UK Verify. Overview of process 1. Identify certificate requesters, for those requesters. 2. Inform GDS of these requesters and approvers and supply their contact details. 3. Generate a private key in the form of a file. From this you generate the certificate signing request file containing a corresponding public key. Data can only be encrypted and decrypted by such a matching public and private key pair. Do not share the private key outside the environment where you created it. You must securely store and protect private key files. Define appropriate controls (such as restricting access to approved staff and storing them offline, eg in a safe) and ensure you enforce them. You must generate a new private key for each certificate signing request file that you need, as the public key in the certificate signing request file must have a corresponding private key. We strongly advise that you don t re-use existing private keys and instead you generate a new private key for each certificate signing request. This naturally retires private keys that may have been compromised and means that you keep familiar with the process of updating keys. 4. From the private key file, generate a certificate signing request file to create a corresponding public key. 5. Submit the certificate signing request file to the GDS Test certificate authority or GDS certificate authority (for the production environment). Identify your certificate requesters and approvers Before you request certificates, ensure you have identified certificate requesters, and approvers for those requesters. Approvers must be in a senior role within your organisation, for example a project manager with responsibility for security. For security reasons, we recommend that you keep the number of approved requesters to a minimum. Inform GDS of the first name, last name, address and telephone number of the requesters and approvers. Do this by ing idappki@digital.cabinet-office.gov.uk from the Service Manager s address. GDS adds them to the list we maintain, covering all organisations who may request certificates. If GDS receives a certificate signing request from someone who isn t an approved requester, we put the request on hold while we ask a project sponsor for approval. Ensure that you notify GDS when you want to remove someone from the list.

19 Generate a private key Run the following command from a Linux (or OSX) command line: openssl genrsa -out <file name>.key ensures that the private key meets the RSA 2048 standard required by the GDS CA. where <file name> is a meaningful name, typically indicating the URL or function and a version number, for example: myservice_dev_saml_signing_1.key myservice_uat_msa_saml_encryption_3.key You ll need to issue new private keys in future, so naming these files properly and organising them now saves confusion later. Securely store private keys You must securely store and protect private key files. Define appropriate controls, typically including the following, and ensure you enforce them: restrict private key access to approved staff store files in encrypted format store files offline, for example on a USB memory stick kept in a safe For further advice and guidance, contact the government s National Technical Authority for Information Assurance (CESG). Generate a certificate signing request Create the certificate signing request file from the private key by running the following command from a Linux (or OSX) command line: openssl req -new -key <file name>.key -out <file name>.csr where: <file name>.key is the name of the private key file <file name>.csr is a meaningful name for the certificate signing request file, typically the name of your service or the Matching Service Adapter as appropriate, and a version number, for example: myservice_dev_saml_signing_3.csr myservice_uat_msa_saml_encryption_3.csr The private key and certificate signing request files can have the same filename as they have different file extensions (.key and.csr). You may need to reuse a certificate signing request file, so establishing a naming convention with version numbers helps you avoid future problems. You re then asked to supply the following information: Country Name - 2 letter code for your country, for example GB for Great Britain State - county or city Locality - city or town Organisation Name - this must match your contractual or programme status Organisation Unit - your unit within the organisation, for example team Common Name - one of the following, depending on the type of certificate. Common Name must not contain underscores

20 TLS mutual authentication: hostname of the server or URL of the service, for example SAML message signing: <servicename> SAML Signing <version> SAML message encryption: <servicename> SAML Encryption <version> JSON message signing: <servicename> JSON Signing <version>. Don t select this type; it s for identity providers only JSON message encryption: <servicename> JSON Encryption <version>. Don t select this type; it s for identity providers only Address - address of the certificate requester Extra attributes - you don t have to fill in these final fields If you fill in any of the above details incorrectly, the request is rejected and you must generate a new certificate signing request file and submit it again. Common reasons for rejection include: misspelt organisation name or URL incorrect certificate type selected, for example you selected a type of SAML Encryption in Common Name but the certificate is actually a SAML Signing certificate. If the certificate signing request filename does not reflect its content, this error may only become apparent when you submit the Request access to an environment form with the certificate pasted into the wrong box unrecognised certificate requester, ie you haven t previously notified GDS that they are an approved requester for your organisation Store certificate signing request files Certificate signing request files don t have the same security issues as private key files, but it s advisable to store a copy of them with the corresponding private key files. Submit the certificate signing request to the certificate authority 1. Upload the certificate signing request file you created to either the IDAP Test certificate authority or the IDAP certificate authority web portal as appropriate: IDAP Test certificate authority web portal is Use this when submitting certificate signing requests for the integration environment IDAP certificate authority (for the production environment) web portal is 2. Click ENROL to begin the submission. The portal prompts you to browse for and select your certificate signing request file. 3. Click Submit. A screen displays, asking for more details. Several fields are pre-populated with information taken from the certificate signing request file. 4. In Applicant Details, enter details of the approved certificate requester. The requester must have previously been notified to GDS as described in Identify your certificate requesters and approvers. 5. Enter the requester s Address. The GDS certificate authority sends the signed certificate to this address. 6. In the Certificate Profile section, select the appropriate certificate type. This must match the intended use of the certificate, ie if you re submitting a signing certificate, you must select SAML Signing. If you select the wrong certificate type, it won t be valid for GOV.UK Verify. Note: You need a pair of certificates (SAML signing and SAML encryption) for your Matching Service Adapter (or equivalent), and you also need both types of certificates for your service itself. Choose one of the following certificate types: SAML signing SAML encryption JSON Signing - don t select this type; it s for identity providers only JSON Encryption - don t select this type; it s for identity providers only