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, [email protected]. 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 [email protected]. 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 [email protected] 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 [email protected] 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

21 TLS 7. Enter a Challenge Phrase. This is similar to a password and you ll need it to renew or revoke the certificate via the GDS certificate authority web portals. Ensure you keep a record of it. You may want to revoke a certificate if you suspect that the private key has been compromised, so that GOV.UK Verify no longer accepts it. Caution: If you think that a private key has been compromised, you must contact GDS immediately. 8. Click Submit to send the certificate request to the GDS CA. GDS contacts the requester to verify that they ve made the request. If GDS approves the request, they send the signed certificate file to the address you specified when submitting the request. You can submit the same certificate signing request file many times, but it will be rejected if you have already used it to request a currently valid certificate. Step 6: Request access to the integration environment The integration environment is a controlled and restricted environment for security reasons. To access this environment, you must fill in the Request access to an environment form, available from your engagement lead. You must obtain the necessary signed test certificates before completing the form. The required content for each field on the form is explained below to help you to complete it: 1. service entity id - entity id of the service you want to connect to the integration environment. This will be a globally unique identifier for your service and for the environment. It s typically in URL format, for example If you have multiple environments, you ll need to ensure they have unique entity ids, for example 2. matching service entity id - as a unique integrating party within the federation, your matching service also needs an entity id, which must be different from your service entity id (supplied in the first field of the form), for example You can use the same matching service across multiple connections 3. matching service URL - fully qualified URL to which the hub makes making service requests, for example 4. requested cycle 3 attribute name - any additional fields that you need to be sent if cycle 1 matching fails. Ensure that the engagement team pre-approves this field as it requires development effort by the hub team. You need to provide the name of the attribute to be used for cycle 3 matching, for example driving licence. Note: If you ve made a special arrangement with the Policy and Engagement Team, please indicate this by entering previously arranged 5. service home page URL - URL of your service home page, ie the URL used to access your service 6. service display name - name that appears to the user throughout their hub journey. It should be in the form of a sentence starting with a verb (View your driving licence details) rather than a title (Driving licence details) 7. other ways to display name - text that appears on the Other ways to... page, that is the page that appears if the user is unable to continue the journey, for example they don t have a passport or driving licence. An example is View your driving licence online. If you don t provide this, we ll default it to the service display name 8. other ways to complete the transaction - HTML field that displays on the Other ways to access and Unlikely to succeed pages of the hub. It must be valid HTML and inform the user of alternative methods of using your service 9. assertion consumer service HTTPS (URL) - location to which responses from the hub are sent. It must be a fully qualified URL, for example matching service user account creation URL - fully qualified URL to which the hub makes unknown user attribute query requests. This is optional and only required if you wish to enable user account creation when matching fails

22 account creation when matching fails 11. service signature validation certificate - must be a valid X509 certificate signed by either the GDS Test or GDS Production Certifying Authority. The certificate is used to validate the digital signature present on all messages sent from your service and must correspond with the private key generated for your service. See step 5 for more information on obtaining and requesting certificates 12. matching service signature validation certificate - must be a valid X509 certificate signed by either the GDS Test or GDS Production Certifying Authority. The certificate is used to validate the digital signature present on all responses sent from the Matching Service Adapter (MSA) and must correspond with the private key generated for use by the MSA. You can retrieve this, and other details, from your MSA by accessing /matching-service/saml2/metadata. See step 5 for more information on obtaining and requesting certificates 13. SAML Encryption Certificate (Service) - SAML encryption certificate (service) - must be a valid X509 certificate signed by either the GDS Test or GDS Production Certifying Authority. The certificate is used to encrypt the assertions within a response sent from the hub and is decrypted by the corresponding private key generated for use by your service. See step 5 for more information on obtaining and requesting certificates 14. SAML Encryption Certificate (Matching Service) - must be a valid X509 certificate signed by either the GDS Test or GDS Production Certifying Authority. The certificate is used to encrypt the assertions within a request sent from the hub to your MSA. It s decrypted by the private key generated for use by your MSA. You can retrieve this, and other details, from your MSA by accessing /matching-service/saml2/metadata. See step 5 for more information on obtaining and requesting certificates 15. user account creation attributes - check the box if you have implemented the user creation flow within your service (creating new user accounts when no match is found) and have the appropriate version of the MSA. User account creation is optional. The list of attributes that can be sent back to your service.then display: FIRST_NAME MIDDLE_NAME SURNAME DATE_OF_BIRTH CURRENT_ADDRESS CYCLE_3 Select the attributes you want to be sent back to your service All of the above don t have to be unique for each connection you request with the integration environment. It s appreciated that you send all the details with each request to ensure that each connection has the correct details. The only fields that must be unique are entity id and assertion consumer service URL. Step 7: Test the whole user journey in the integration environment You need to ensure the end-to-end authentication and matching process works before you move on to running a live service in the production environment. The integration environment enables you to do this. Here you can test complete user journeys, both happy path and failure scenarios. You use the integration environment for: testing end-to-end user journeys user demos showcases providing evidence of successful testing for the Stage 4 gate review Caution: If you carry out penetration testing (pen testing) on your end-to-end system, you must not extend this to the hub domain. You must only penetration test your own system. Even if you think you have a valid reason for penetration testing the hub domain, you must not do so without first consulting the GOV.UK Verify team at [email protected]. Supply metadata

23 You must supply the GOV.UK Verify team with metadata for: your service your matching service Matching Service Adapter (MSA). You can generate metadata via the metadata endpoint on the MSA itself based on how you ve configured the software To create the metadata file, access: /matching-service/saml2/metadata You send the metadata for your service and your matching service to the GOV.UK Verify team via including information such as: entity id public certs response endpoint matching process matching service adapter entity id attributes required for account creation (optional) The support team then uploaded the metadata to the federation hub service. Create test users Real user data is not allowed in the integration environment as it s not accredited for this and has no links to identity providers. Because of this you have to create dummy (test) users. Do this in one of the following ways: Access the stub-idp users pages to see existing users and create new ones. To do this, you must: Request IP whitelisting for your machine from [email protected] Send us some details so we can set up a username and password for you to access these pages. Follow the procedure described in Authentication for managing users Create users in bulk, for example from scripts that perform an http POST with a JSON document containing the user data. For more information, see Creating users by http POST Note: This format is correct for the stub-idp but is not necessarily correct for the matching service interface. You only need to create test users once for each environment you use. Note: If you ve previously received URIs to create/update/delete users, you can continue to use them until you ve migrated to our new environment Authentication for managing users After you ve requested IP whitelisting for your machine, follow the steps below so that we can set up a username and password for you: 1. go to the password generation page: 2. remember or securely store the password and us the hash, along with a username of your choice. Don t us the password, just the hash and your chosen username We ll use this username and hash to configure your access details to the stub-idp users pages. You

24 We ll use this username and hash to configure your access details to the stub-idp users pages. You don t have to provide authentication to access the normal stub-idp pages (for a user s authentication journey from the hub). To view existing users, go to the relevant stub-idp page. The URL is something like: For example: The users are returned in JSON format. You ll need to provide your basic auth credentials. Creating users by http POST You can also create users in bulk, using scripts that do an http POST with a JSON document containing the user data. This format is correct for the stub-idp, for example fake post-office, but not necessarily for the matching service interface. To create users, POST a JSON document containing an array of user data to the users URI (you ll need to include your authentication credentials): For example: (the same one that lists existing users on http GET). The user fields are (currently): String PID (optional) String username String password SimpleMdsValue<String> firstname (optional) SimpleMdsValue<String> middlenames (optional) List<SimpleMdsValue<String>> surname SimpleMdsValue<Gender> gender (optional) SimpleMdsValue<Date> dateofbirth (optional) Address address (optional) String levelofassurance An example JSON payload, with a list containing just a single user is shown below (don t forget to set the Content-Type header to application/json ):: [{ "pid": " f-4d94-b0db-cb1f7eb3fd84", "username": "user1", "password": "password", "firstname": { "value": "Fred", "verified": true }, "dateofbirth": { "value": " ", "verified": true }, "address": {

25 "address": { "verified": true, "postcode": "WC2B 6NH", "lines": [ "Aviation House", "London" ] }, "levelofassurance": "LEVEL_2", "surnames": [{ "value": "Smith", "verified": true }] }] Possible values are shown in the following table. Attribute Value Level of assurance must be 1 of the following values: LEVEL_X Level of assurance LEVEL_1 LEVEL_2 LEVEL_3 LEVEL_4 Simple MDS Value consists of the following fields: value (variable type) SimpleMdsValue DateTime from (the time when this value started - eg changed name to this - Optional) DateTime to (The time after which this value ended - eg changed name from this - Optional) boolean verified Gender must be one of: Gender FEMALE MALE NOT_SPECIFIED Address consists of: boolean verified DateTime fromdate Address DateTime todate (Optional) String postcode (Optional) List<String> lines String internationalpostcode (Optional) String uprn (Optional) Deleting a user by http POST You can delete users from the stub IDP by posting a JSON document containing the usernames you want to delete to the following URI with Content-Type header set to application/json (you need to provide authentication credentials): For example:

26 For example: Example JSON: { } "username": "user1" When you ve successfully completed testing in the integration environment, you must provide the outputs required to complete this stage before moving on to Stage 5 Production Onboarding. Stage 5: Production onboarding Purpose of this stage Deploy your end-to-end service in a live production environment, confirm operational readiness and go live. Prerequisites before entering this stage See required outputs from Stage 4 What s expected from your service Request configuration of your GOV.UK Verify production environment by filling in the Request access to an environment form, available from your engagement lead or technical single point of contact Agree and sign a memorandum of understanding (MOU) Share a communication plan for the launch in conjunction with the GOV.UK Verify team Share an ongoing communication plan with the GOV.UK Verify team for your operational service Share your end-user support model with the GOV.UK Verify team Share your operational support model with the GOV.UK Verify team Share contact details for your operations team and escalations Outputs required to complete this stage Your service has been configured in the GOV.UK Verify production environment A signed memorandum of understanding (MOU) for the use of GOV.UK Verify between Cabinet Office and your department Your communications team have an agreed plan for launching An ongoing communication plan is in place for your operational service Confirmation that both parties understand and can work with the actual implementation of the end user support model Confirmation that both parties understand and can work with the actual implementation of the operational support model A go/no-go assessment to confirm that your end-to-end service is ready to go live Stage 6: In beta Purpose of this stage You re developing against the demands of a live environment, understanding how to build and scale while meeting user needs. You may choose to make your service available to a subset of users (private) or make it available to all users (public). Prerequisites before entering this stage See required outputs from Stage 5

27 See required outputs from Stage 5 Outputs required to complete this stage No outstanding onboarding issues Head of operations for GOV.UK Verify confirms that support from the engagement lead is no longer required Regular service review meetings between your service and the GOV.UK Verify operations team are taking place Glossary of terms assertion (identity provider assertion) A package of data that an identity provider or matching service sends in response to a request from the hub service. Data in an assertion is signed by the creator of the assertion (eg an identity provider) and encrypted for the recipient (eg the hub service). assured identity An identity that s been verified to the required level of assurance. attributes The data linked to an identity. This data may be used by a relying party to indicate entitlement or complete a transaction on behalf of the individual who has authenticated. authentication The process by which a system confirms the user is known to that system, usually through the use of one or more credentials. authentication request The request sent by a relying party when it requires identification of the individual trying to access it. Relying parties make these requests to the hub service. The hub service is the only entity able to make authentication requests directly to identity providers. certificate A file containing a public key. Only certificates that have been approved by a GDS certificate authority (CA) can be used with GOV.UK Verify. certificate authority (CA) A service that signs and subsequently verifies the authenticity of digital certificates. certificate signing request (CSR) file A file that contains all the information a certificate authority (CA) requires in order to issue a signed certificate. compliance tool Enables services to carry out SAML interoperability testing before testing complete user journeys in the integration environment. It allows isolated testing of both the connection from the service to the hub and the connection from the hub to the Matching Service Adapter. credentials An identity provider issues credentials to a user to allow the user to be authenticated when accessing a government service. Examples of credentials are usernames, passwords and security codes. cycle 0/1/2/3 Cycle numbers refer to the sequence of attempts made to find a matching account or local identifier

28 Cycle numbers refer to the sequence of attempts made to find a matching account or local identifier for a particular verified identity as expressed in an assertion of matching data from an identity provider. cycle 0 Cycle 0 allows the matching service to match the hashed PID for a user to hashed PIDs held in the matching service against previous matches. This cycle is a short cut for full matching, ie cycles 1/2/3. cycle 1 Checks to see if there s a match for the user s identity in the transaction s local store, using the matching data set to try and achieve a match. cycle 2 Additional matching cycle where attributes gained from attribute providers are used to enhance the matching process. Note: this is currently not supported by GOV.UK Verify. cycle 3 Asks the user for some additional information to be sent to the matching service to complete a match. This cycle is defined in the service provider policy and may not be required for all matches. data matching The process of finding a local identifier through matching that s useful to the relying party when completing a transaction, for example confirming a National Insurance number so the user can amend their tax records. Data Protection Act (DPA) 1998 The Data Protection Act controls how personal information is used by organisations, businesses or the government. Read more about the Data Protection Act. document checking service (DCS) A service supplementary to GOV.UK Verify that allows an identity provider to validate user documents against government records. dynamic KBV A process where the user is required to provide answers to questions relating to the claimed identity. encryption certificate 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. Good Practice Guides (GPGs 44, 45, 46 and 56 in relation to identity assurance) Documents that have been developed collaboratively with HMG departments, private sector representatives and the UK National Technical Authority for Information Assurance (CESG) to ensure that the business, technical and security demands across the sectors can be met. The guides are intended to ensure that the delivery of trusted online user transactions will take place in accordance with the Identity Assurance Principles. hashed PID The hashed PID (persistent identifier) is unique to a single user identity, as managed by a single identity provider, used to access a specific service (relying party). This ensures that identifiers for user identity are unique to specific services and can t be correlated across multiple services. hub (hub service, GOV.UK Verify hub)

29 The infrastructure that manages interaction between users, relying parties, identity providers and matching services for the purpose of authentication to a service connected to GOV.UK Verify. Provides a clear divide between the identity providers and service providers, avoiding a complex manymany integration. It protects privacy and ensures security during authentication transactions. identity In the case of identity assurance, this is the description of who or what an entity is, defined by a collection of attributes. identity assurance The ability for a party to determine, with some level of certainty, that an electronic credential representing an entity (human or a machine) with which it interacts to effect a transaction, can be trusted to actually belong to the entity. Proving you are who you say you are to a certain level of confidence. Identity Assurance Principles The principles that set out how the government s identity assurance approach should be configured to meet the privacy and consumer expectations of its users. They are published by the Privacy and Consumer Advisory Group and are amended or replaced from time to time. identity provider Private sector organisations, paid by the government, to verify a user is who they say they are and assert verified data that identifies them to the relying party. The organisations are certified as meeting relevant industry security standards and identity assurance standards published by the Cabinet Office and CESG (the UK s national technical authority). integration environment A production-sized deployment of the entire identity assurance hub environment. This allows services to test full end-to-end flows and to showcase a working system including happy path and failure scenarios. knowledge based verification (KBV) A process of testing a user s knowledge about the claimed identity to verify that they are who they claim to be. level of assurance (LOA) The degree of confidence the relying party requires that a user is who they say they are. level of assurance 1 Used when a relying party needs to know that it s the same user returning to the service but doesn t need to know who that user is. level of assurance 2 Used when a relying party needs to know on the balance of probabilities who the user is and that that they are a real person. level of assurance 3 Used when a relying party needs to know beyond reasonable doubt who the user is and that that they are a real person. level of assurance 4 As level of assurance 3, but with a biometric profile captured at the point of registration.

30 local matching service (LMS) Part of the relying party matching service that stores a hashed persistent identifier against a local identifier. matching data set (MDS) The minimum data set of name, address, date of birth and gender sent by the identity provider to the relying party matching service for the purpose of matching. matching service The service that matches data from the identity provider to the transaction s local data store in order to tie the user s identity to their transaction account. Matching Service Adapter A product provided by the GOV.UK Verify service that s installed within the service provider s security domain that handles SAML requests for matching queries, cryptography as required by the SAML profile and responses to the hub service. onboarding The process through which new relying parties and identity providers acquire the necessary knowledge, technical skills and integration environment to become part of the identity assurance federation. persistent identifier (PID) A unique identifier for a user as registered with a single identity provider. Persistent identifiers generated by identity providers must be constructed using pseudo-random values that have no discernible correspondence with the subject s actual identifier, for example username. Privacy and Consumer Advisory Group (PCAG) Established to help government develop an approach to identity assurance and develop the Identity Assurance Principles. private beta The first version of the service available to a small number of selected users so we can test and develop it further. private key A long string of data used in cryptography. Generating a certificate signing request (CSR) creates a corresponding public key. public beta The service is available to users of approved relying party services without the need for pre-approved tokens or a personalised invitation. public key A long string of data derived from a private key. Data encrypted with a public key can only be decrypted with the corresponding private key, and vice versa. public key infrastructure (PKI) A set of hardware, software, people, policies and procedures needed to create, manage, distribute, use, store and revoke digital certificates. [1] registration The process of collecting the required data to enable an identity provider to begin the proofing process.

31 relying party A government service such as Check or update your company car tax (HMRC) or Claim your redundancy payment (BIS), that needs proof of a person s identity to complete a transaction. In SAML specifications, a relying party is an entity that depends on receiving assertions from an asserting party (a SAML authority) about a subject, for example an assertion of identity from an identity provider. SAML (Security Assertion Markup Language) An Extensible Markup Language (XML) open standard for the exchange of authentication and authorisation data between parties such as identity providers and relying parties. OASIS governs the SAML standards. A SAML profile derived from core SAML standards is used for the purposes of signing in to government services under identity assurance. SAML profile A profile for the use of SAML assertions and request-response messages to be used between participants in the GOV.UK Verify federation architecture. This profile is derived from core SAML profiles as defined by OASIS. service provider matching service (SPMS) A service nominated by the service provider that responds to matching requests from the hub service. See matching service. services (government services) Agencies provided by government that work to help and provide for the people living within its jurisdiction. Shibboleth A standards based, open source software package for web single sign-on. signing certificate 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. static KBV Where a secret has been previously exchanged between 2 parties. One party uses the secret to verify that they are the other party with whom the secret was originally exchanged. Also referred to as a shared secret. transaction The thing the user wants to do or get from a government service. An individual online service that a government service offers, for example renew a passport. TLS (Transport Layer Security) A protocol used to provide secure communications across the internet, to websites or between services. A site using TLS has a URL beginning URI (Uniform Resource Identifier) A character string that identifies a resource, for example an electronic document, an image, a source of information or a service. A URI could be a name, a location or both. URL (Uniform Resource Locator) A character string that identifies a resource by its location. A URL is typically a web address, particularly

32 A character string that identifies a resource by its location. A URL is typically a web address, particularly when used with http. A URL is held to be a subset of a URI, as it provides a way of identifying the resource by describing how to locate it (eg its network location). user The person accessing the government service on GOV.UK. whitelist (for IP addresses) A list or register of those permitted access. Whitelisting is the reverse of blacklisting, the practice of identifying those that are denied access, typically used in spam filters in applications. A whitelist of IP (Internet Protocol) addresses allows data-traffic from / to those IP-addresses to access a network by appropriate firewall configuration. Footnotes [1] Version history A summary of what has changed, and when, to help you find new content. Version Date Comments nd February 2015 New MSA documenatation (.pdf) rd January 2015 New pages for Needs Analysis guidance th January 2015 Guidance on how a service moves through the process and how to create a proposal th December 2014 Stage 1 changed to Proposal ; steps 2 & 3 of Stage 4 expanded th December 2014 New page for Stage 3 share your plans th December 2014 New content added for Stage th October 2014 New content added for Stages 5 and th October 2014 New content added for Stage rd September 2014 New pages added for Stages nd September 2014 Version history added st September 2014 New landing page; 7 stage process st August 2014 Technical onboarding guide published