REALME REPLATFORMING AGENCY ENGAGEMENT PACK - ONBOARDING COMPONENT - REALME FOR DEVELOPERS
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
RealMe® Replatforming
Agency Engagement Pack
Onboarding Component
Version 1.1 (FINAL)
March 2021Agency Engagement Pack
Revision History
Version Date Description of changes
0.1 19 February 2020 Initial draft
0.2 9 March 2020 Updated timelines, moved FAQs to a
separate document.
0.3 16 April 2020 Updated to include revised schedule
0.4 24 April 2020 Updates to Opaque Token structure
0.5 25 September 2020 Added step to obtain Mutual SSL
certificates for services using Artifact
binding.
Amended Assert then Login flow.
Updated to reflect revised schedule.
0.6 16 December 2020 Added new endpoints
Updated SAML Assertion for HD Fed
RSA Token amendment
0.7 18 January 2021 Added ITE RealMe Replatforming
bundle links and information
0.8 17 February 2021 Added details of Artifact Resolution
and MTS endpoints
1.0 23 March 2021 Final version with key dates/times for
Production go live.
1.1 30 March 2021 Updated to provide links and
information about the Production
Onboarding bundle.
Onboarding Page 2 of 31Agency Engagement Pack
Table of Contents
1 BACKGROUND ............................................................................................................. 5
2 PURPOSE .................................................................................................................... 6
3 ROLES AND RESPONSIBILITIES........................................................................................... 7
4 ENGAGEMENT PLAN ...................................................................................................... 8
4.1 Agency Engagement Timeline ............................................................................................. 9
5 DETAILED TIMELINE..................................................................................................... 10
5.1 Early Integration Testing (EIT) ........................................................................................... 10
5.1.1 Implementation Tasks ............................................................................................... 10
5.1.2 Post-implementation Tasks....................................................................................... 11
5.2 Message Testing Site (MTS) .............................................................................................. 12
5.2.1 Implementation Tasks ............................................................................................... 12
5.2.2 Post-implementation Tasks....................................................................................... 12
5.3 Integration Testing Environment (ITE) .............................................................................. 13
5.3.1 Pre-implementation Tasks ........................................................................................ 13
5.3.2 Implementation Tasks ............................................................................................... 13
5.3.3 Post-implementation Tasks....................................................................................... 13
5.4 Production Environment ................................................................................................... 14
5.4.1 Pre-implementation Tasks ........................................................................................ 14
5.4.2 Implementation Tasks ............................................................................................... 14
5.4.3 Post-implementation Tasks....................................................................................... 15
6 IMPLEMENTATION OVERVIEW ........................................................................................ 16
6.1 Login and Assertion Services ............................................................................................. 16
6.2 Assert and Login Flow ....................................................................................................... 16
6.3 Help Desk .......................................................................................................................... 16
6.3.1 Web Application........................................................................................................ 16
6.3.2 Web Service .............................................................................................................. 17
6.4 RSA Tokens ........................................................................................................................ 17
7 IMPLEMENTATION GUIDE ............................................................................................. 18
7.1 Pre-requisites .................................................................................................................... 18
7.2 RealMe® Login Service and Assertion Service ................................................................... 18
Onboarding Page 3 of 31Agency Engagement Pack
7.3 RealMe Assertion Service – Assert and Login Flow .......................................................... 19
7.3.1 Assertion Subject Example ........................................................................................ 20
7.4 RealMe HelpDesk Web Application - Federation Flow ..................................................... 21
7.4.1 Overview ................................................................................................................... 21
7.4.2 Messaging Flow ......................................................................................................... 21
7.4.3 Integration requirements.......................................................................................... 22
7.4.4 Message requirements ............................................................................................. 22
7.4.5 Examples ................................................................................................................... 23
8 KEY CONTACTS .......................................................................................................... 26
9 APPENDIX ONE – ENDPOINT TEST ................................................................................... 27
9.1 Replatformed RealMe® Endpoints .................................................................................... 27
9.1.1 Artifact Binding Endpoints ........................................................................................ 27
9.2 Connectivity Test............................................................................................................... 28
9.2.1 Unix ........................................................................................................................... 28
9.2.2 Windows ................................................................................................................... 28
10 APPENDIX TWO - IDP METADATA ................................................................................... 29
10.1 Installation Steps ........................................................................................................... 29
10.2 Message Testing Site (MTS) .......................................................................................... 30
10.3 Integration Testing Environment (ITE) .......................................................................... 30
10.3.1 Certificate Information ............................................................................................. 30
10.3.2 RealMe Public Metadata ........................................................................................... 30
10.4 Production Environment ............................................................................................... 31
10.4.1 Certificate Information ............................................................................................. 31
10.4.2 RealMe Public Metadata ........................................................................................... 31
Onboarding Page 4 of 31Agency Engagement Pack 1 Background The authentication and identity verification service RealMe® was launched in 2013. RealMe is a secure and privacy protected way for New Zealanders to access online services, prove their identity and assert personal information online. RealMe provides two key services, the login service and the identity verification, or assertion, service. The login service is an authentication service that allows a returning customer to reuse their login across multiple services. RealMe login currently provides access to 131 services from 40 organisations. Up to 2.5 million logins occur monthly and approximately 60-80% of logins are used to access more than one service. The RealMe Assertion service provides a person with an online identity, allowing them to prove (with their consent) that they are who they say they are online. The pieces of information belonging to a person are called attributes. Attributes are currently provided by the Department of Internal Affairs Identity Verification Service (verified identity – name, date of birth, place of birth and gender) and the New Zealand Post Address Verification Service (residential address). Providing the verification services separately ensures that a person’s attributes are not stored within RealMe itself. The RealMe Assertion service currently provides identity services to 17 public and private sector clients. There is over 820,000 verified identities and the service undertakes over 30,000 successful identity transactions per month. The current RealMe platform is hosted ‘on premise’ and requires significant three-yearly capital investment to upgrade expiring platform components. After consideration of the ongoing costs required to maintain the current platform, the government and DIA’s strategic direction to consider ‘cloud first’ technology options and the potential benefits of a cloud based platform in terms of faster development, improved security and reduced costs, DIA made a decision to move the RealMe service to an offshore, cloud based platform. DIA selected Microsoft Azure Active Directory B2C as the new platform. DIA has an existing enterprise cloud services agreement with Microsoft, which includes its use of the Azure platform. This agreement incorporates the standard Online Services Terms (which includes a separate Data Protection Addendum) that apply to DIA’s use of Azure. In late 2019 DIA underwent an RFP process to procure an implementation partner, and in December 2019 engaged Unify Solutions NZ Ltd (UNIFY) to carry out this transition, as well as provide ongoing service support. The goal is to have RealMe moved to the new platform early in the second quarter of 2021. Onboarding Page 5 of 31
Agency Engagement Pack
2 Purpose
The purpose of the Agency Engagement Pack is to provide agencies with a good understanding of
the purpose, objective, approach, timelines, process and mechanism for integrating applications to
the new RealMe® platform.
The intended audience for this pack includes agency business owners, business analysts, developers
and vendor representatives.
This is the second of three artefacts which, together, form the Agency Engagement Pack:
Artefact Contents
Agency Readiness Pack • Solution Overview
• Roles and Responsibilities
• Pre-requisites
• Engagement Plan (high level)
Agency Onboarding Pack (this • Engagement Plan (revised)
document) • Configuration Items
• Integration and User Acceptance Testing
• Rollout across Higher Environments
Service Management Pack • Service Transition
• Service Operation
• Frequently Asked Questions
A draft of this document was presented to the second RealMe Replatforming workshop on 19
February 2020.
Onboarding Page 6 of 31Agency Engagement Pack
3 Roles and Responsibilities
The following roles and responsibilities regarding agency engagement have been defined:
Responsible Role
DIA • Lead interactions with agencies
• Facilitate integration workshops
• Lead/manage the integration process in all environments
• Complete Certification and Assurance for the replatformed RealMe® service
and provide related documentation and guidance to agencies
• Complete a Privacy Impact Assessment and share relevant aspects with the
agencies
• Complete Performance and Penetration Testing in the RealMe Integration Test
Environment (ITE) and share results with the agencies.
• Provide technical documentation, including the Solution Architecture Design
document, to the agencies
UNIFY • Participate in agency workshops and follow up meetings as required
• Support DIA in delivering the processes to implement and test agency
integrations
• Provide troubleshooting assistance and advice to support successful agency
integrations
Agencies • Participate in integration workshops and follow up meetings as required
• Integration and Testing of applications using the RealMe ITE and, optionally,
the Message Testing Site (MTS)
• Production implementation
• Complete any Certification and Assurance as required as assessed by your
agency
Onboarding Page 7 of 31Agency Engagement Pack
4 Engagement Plan
DIA commenced formal engagement with the agencies in early February 2020. The first two
workshops have been held as planned and draft versions of the Readiness and Onboardings packs
were presented.
Date Purpose
5 February 2020 (workshop #1) Initiate discussions regarding the application onboarding
exercise and walkthrough the first draft of the ‘Agency
Readiness Pack’.
19 February 2020 (workshop #2) A follow up from Workshop #1 to provide an update on the
action items and inputs from previous workshop, a
walkthrough of the Engagement and an update on the
timelines and overall engagement plan.
30 October 2020 (showcase via A showcase of the replatformed RealMe®, in particular:
video) • RealMe Login and Assertion flows
• RealMe Assert and Login flow
• RealMe HelpDesk Web Application
• RealMe ‘Manage my Login’
The final version of the Agency Engagement Pack will be issued in early January 2021 to coincide
with ITE Replatforming, however, there may be updates to these documents prior to this. Agencies
will be notified when significant updates are available, and these will be published on the RealMe®
Developer's Website.
For those agencies with more complex integrations, additional workshops may be required to ensure
all parties understand the changes required to support the replatformed RealMe service.
If you have any questions regarding any aspect of the Engagement Plan and/or the replatforming of
RealMe please email integrations@realme.govt.nz.
Onboarding Page 8 of 31Agency Engagement Pack
4.1 Agency Engagement Timeline
The following diagram and table depict a high-level view of the agency engagement timeline.
Agencies will be notified should there be any change to the timeline.
For a detailed timeline of the tasks required to integrate with the replatformed RealMe, please refer
to the Detailed Timeline section on page 10 of this document.
Key Agency Dates
Date Purpose
25 September 2020 Issue updated Agency Engagement Pack (including the Service
Management Pack)
16 October 2020 Publish Security and Privacy information for agencies
9 November 2020 Early Integration Testing for complex agencies1
30 November 2020 MTS build complete
26 January 2021 to 26 March 2021 Agency Integration Testing (ITE) and drop in workshops
1 March 2021 Help Desk Material available
25 March 2021 Issue final Agency Engagement Pack
25 March 2021 Agency C&A Session with Quantum
29 March 2021 Production Onboarding Bundles published plus minor update to
Onboarding Pack to provide reference to the new bundle.
11 April 2021 Agency Replatforming
1
Complex agencies are deemed to be those who have services which use the Assert then Login flow and/or
run their own RealMe Help Desk. This environment will not be available post go-live.
Onboarding Page 9 of 31Agency Engagement Pack
5 Detailed Timeline
This section provides a list of the tasks required for replatforming in each RealMe® environment
along with indicative dates for each task based on the high-level view of the agency engagement
timeline.
5.1 Early Integration Testing (EIT)
Agencies with complex integrations, i.e. those who have services which use the Assert then Login
flow and/or run their own RealMe Help Desk are expected to integrate to the EIT environment.
The RealMe EIT was made available to agencies in November 2020 for testing. The replatformed
RealMe EIT is a temporary development environment that will be decommissioned once the
replatforming of RealMe is complete.
Date Responsible Action
23 Oct 20 DIA Publish Agency Onboarding Pack and RealMe EIT Bundle
30 Oct 20 Agency 1. Review the Agency Readiness and Onboarding packs.
2. Collect the ‘RealMe Replatforming Bundle’ from the RealMe Developers
website
3. Test endpoint availability, refer to Appendix One – Endpoint Test on page
28 of this document.
4. Ensure this change is in your forward schedule of change.
5. Ensure appropriate resources are available to implement and test the
replatformed RealMe
6. Confirm to DIA via integrations@realme.govt.nz you are ready to
proceed.
7. Amend the SP metadata provided in the bundle to reflect your service’s
endpoints.
8. Provide your SP metadata and, for Artifact Binding integrations, Mutual
SSL certificate to DIA.
5.1.1 Implementation Tasks
Date Responsible Action
6 Nov 20 UNIFY Deployment and Agency Configuration Complete
6 Nov 20 DIA Notify agencies that deployment is successful and integration tasks can
commence.
9 Nov 20 to Agencies Complete integration tasks. For further detail regarding the required tasks,
18 Dec 20 refer to the Implementation Guide on page 18 of this document.
Smoke test application.
Confirm connectivity to integrations@realme.govt.nz.
9 Nov to DIA DIA team will be available to support agencies in need of assistance with the
20 Jan 21 integration exercise.
20 Jan 21 Agencies Participating agencies have confirmed integration or have requested
replatforming support.
Onboarding Page 10 of 31Agency Engagement Pack 5.1.2 Post-implementation Tasks Date Responsible Action 22 Jan 21 DIA RealMe EIT deployment post implementation review. Completed DIA Decommission EIT RealMe. Onboarding Page 11 of 31
Agency Engagement Pack
5.2 Message Testing Site (MTS)
Agencies may optionally integrate to the replatformed MTS environment. Information regarding this
environment will be published on the RealMe Developers website.
Once initial integration testing in EIT has been completed successfully, optional ‘self-service’
integration to MTS will be available for all agencies (to be confirmed but likely to be mid January).
This will run in parallel with the existing RealMe MTS. The existing RealMe MTS will be made
unavailable once the replatforming of RealMe is complete.
Date Responsible Action
Complete DIA Publish Agency Onboarding Pack and RealMe MTS Replatforming Bundle to
the RealMe Developers website.
Complete Agency 1. Review the Agency Readiness and Onboarding packs.
2. Collect the ‘RealMe Replatforming Bundle’ from the RealMe Developers
website.
3. Test endpoint availability, refer to Appendix One – Endpoint Test on
page 27 of this document.
4. Ensure this change is in your forward schedule of change (if required).
5. Ensure appropriate resources are available to implement and test the
replatformed RealMe
6. Confirm to DIA via integrations@realme.govt.nz you are ready to
proceed.
7. Amend the SP metadata provided in the bundle to reflect your service’s
endpoints and upload via MTS.
5.2.1 Implementation Tasks
Date Responsible Action
Complete UNIFY Replatforming Complete
Complete DIA Notify agencies that replatforming is successful and replatforming tasks can
commence.
Complete Agencies Complete integration tasks. For further detail regarding the required tasks,
refer to the Implementation Guide on page 18 of this document.
Smoke test application.
Confirm connectivity to integrations@realme.govt.nz.
Complete DIA DIA team will be available to support agencies in need of assistance with the
replatforming exercise.
Complete Agencies All interested agencies have confirmed replatforming or have requested
replatforming support.
5.2.2 Post-implementation Tasks
Date Responsible Action
TBC DIA Decommission existing MTS RealMe.
(post go-
live)
Onboarding Page 12 of 31Agency Engagement Pack
5.3 Integration Testing Environment (ITE)
The replatformed RealMe ITE will be available to agencies in late January 2021 for integration
testing. This will run in parallel with the existing RealMe ITE. The existing RealMe ITE will be made
unavailable once the replatforming of RealMe is complete.
5.3.1 Pre-implementation Tasks
Date Responsible Action
11 Jan 21 DIA Publish Agency Onboarding Pack and RealMe ITE Replatforming Bundle
11 Jan 21 Agency 1. Review the Agency Readiness and Onboarding packs.
2. Collect the ‘RealMe Replatforming Bundle’ from the RealMe Developers
website (to be confirmed)
3. Test endpoint availability, refer to Appendix One – Endpoint Test on page
28 of this document.
4. Ensure this change is in your forward schedule of change.
5. Ensure appropriate resources are available to implement and test the
replatformed RealMe
6. Confirm to DIA via integrations@realme.govt.nz you are ready to
proceed.
5.3.2 Implementation Tasks
Date Responsible Action
18 Jan 21 UNIFY Replatforming and delta data migration(s)
25 Jan 21 DIA Notify agencies that replatforming is successful and replatforming tasks can
commence.
26 Jan 21 Agencies Complete replatforming tasks. For further detail regarding the required
to tasks, refer to the Implementation Guide on page 18 of this document.
18 Mar 21
Smoke test application.
Confirm connectivity to integrations@realme.govt.nz.
26 Jan 21 DIA DIA team will be available to support agencies in need of assistance with the
to replatforming exercise.
18 Mar 21
26 Mar 21 Agencies All agencies have confirmed replatforming or have requested replatforming
support.
5.3.3 Post-implementation Tasks
Date Responsible Action
29 Mar 21 RealMe RealMe ITE Replatforming post implementation review.
TBC DIA Decommission existing ITE RealMe.
(Post go-
live)
Onboarding Page 13 of 31Agency Engagement Pack
5.4 Production Environment
The Production go-live will be a ‘single’ cutover, i.e. the replatformed RealMe environment will be
stood up for services to integrate with during a specific change window and the existing RealMe
environment will be made unavailable. This approach has been determined to be the best option
primarily due to the sheer volume of data that needs to be migrated from one fundamentally
different system to another. Further information regarding the data migration process is available on
the RealMe Developer’s website.
5.4.1 Pre-implementation Tasks
Date Responsible Action
23 Mar 21 DIA Publish Agency Onboarding Pack and RealMe Replatforming Bundle
7 Apr 21 Agency 1. Review the Agency Readiness and Onboarding packs.
2. Collect the ‘RealMe Replatforming Bundle’ from the RealMe Developers
website (to be confirmed).
3. Test endpoint availability, refer to Appendix One – Endpoint Test on
page 27 of this document.
4. Ensure this change is in your forward schedule of change.
5. Ensure appropriate resources are available to implement and test the
replatformed RealMe
6. Confirm to DIA via integrations@realme.govt.nz you are ready to
proceed.
5.4.2 Implementation Tasks
Date Time Responsible Action
6 Apr 21 17:00 DIA First go/no-go decision.
DIA to provide initial go/no-go notification to agencies.
Should an unforeseen event cause a no-go decision to be
made, the replatforming of RealMe will be rescheduled.
9 Apr 21 17:00 DIA Second go/no-go decision
DIA to provide replatform go/no-go notification to agencies
Should an unforeseen event cause a no-go decision to be
made, the replatforming of RealMe will be rescheduled.
9 Apr 21 21:00 DIA Outage – Replatforming Occurring
Send agencies a reminder that replatforming will be
commencing at 21:00.
11 Apr 21 07:00 DIA/UNIFY Replatforming Complete
Existing RealMe environments to be taken offline.
11 Apr 21 07:30 DIA Notify agencies that replatforming was successful and
replatforming tasks can commence at 9:00.
Agencies will not be able to connect with RealMe until their
replatforming tasks are completed.
Onboarding Page 14 of 31Agency Engagement Pack
Date Time Responsible Action
11 Apr 21 09:00 Agencies Complete replatforming tasks. For further detail regarding
the required tasks, refer to the Implementation Guide on
page 18 of this document.
Smoke test application.
Confirm connectivity to integrations@realme.govt.nz.
11 Apr 21 09:00 DIA DIA team will be available to support agencies in need of
assistance with the replatforming exercise.
11 Apr 21 10:00 DIA Final go/no-go decision
DIA to provide final replatform go/no-go decision based on
success of the initial agency replatforming activities.
Should an unforeseen event cause a no-go decision to be
made, the replatforming of RealMe will be rescheduled.
Agencies who have already replatformed will need to roll
back their changes and reintegrate with the existing
RealMe environment.
11 Apr 21 17:00 Agencies All agencies have confirmed replatforming or have
requested replatforming support.
30 Apr 21 DIA RealMe replatforming heightened support period ends
5.4.3 Post-implementation Tasks
Date Time Responsible Action
7 May 21 RealMe RealMe Production Replatforming post implementation
review.
8 May 21 DIA Decommission existing Production RealMe.
Onboarding Page 15 of 31Agency Engagement Pack
6 Implementation Overview
6.1 Login and Assertion Services
The process for replatforming an application which uses either the Login Service or the Assertion
Service will require the application to be updated to use a new Identity Provider (IdP) metadata file.
This file will contain a new certificate and new endpoints for RealMe® services. Depending on your
network configuration, some agencies may also require amended firewall rules2 to allow their
application to access the new endpoints. For further detail regarding this process, please refer to
the RealMe® Login Service and Assertion Service section on page 18 of this document.
There will be no requirement to supply new Service Provider metadata files for the ITE and
Production environments as these will be migrated as part of the replatforming exercise.
Note: agencies integrating to the MTS and EIT environments will be expected to provide an
amended Service Provider metadata file using the template which will be available in the ‘RealMe
Replatforming Bundle’ for that environment.
Agencies who are using Artifact binding will be requested to supply their Mutual SSL certificates for
both the ITE and Production environments. This is because the current RealMe utilises the
certificate thumbprint only whereas the replatformed RealMe uses the entire certificate.
6.2 Assert and Login Flow
The process for onboarding an application which use either the igovt Context Mapping Service
(iCMS) or the RealMe Context Mapping Service (RCMS) will require a minor code change.
Applications which use the Assert and Login flow are no longer required to interact with iCMS/RCMS
and will no longer be required to decrypt an Opaque Token as per earlier versions of this document.
Instead, the RealMe Assertion Service will issue the user’s FLT for agency as the NameID within the
Subject of the Assertion. This is the same method that is currently used by the Login service. For
further detail regarding this change, please refer to the RealMe Assertion Service – Assert and Login
Flow section on page 19 of this document.
Agencies who use these services will be contacted as part of the engagement process to ensure that
all parties understand the changes required to support the replatformed service. We will support
you throughout the change process.
6.3 Help Desk
Agencies who use either the Help Desk Web Application or Web Service will be contacted as part of
the engagement process to ensure that all parties understand the changes required to support the
replatformed service. We will support you throughout the change process.
6.3.1 Web Application
The existing RealMe Help Desk application will be decommissioned and replaced with a new web
application which will provide the same functionality as the existing RealMe Help Desk web
application.
Agencies who use the Help Desk application will need to federate their internal active directory to
the new RealMe Helpdesk Federation hub. This will streamline the setup of Help Desk users, allow
2
This will be based on DNS based routing or mutual SSL authentication between applications and RealMe services.
Onboarding Page 16 of 31Agency Engagement Pack agencies to provide their own internal governance and remove the need for the use of RSA tokens. For further detail regarding this change, please refer to the RealMe HelpDesk Web Application - Federation Flow on page 21 of this document. 6.3.2 Web Service The Helpdesk Web Service will be decommissioned. Agencies who use this service will be contacted as part of the engagement process to support you through the change process and to ensure that all parties understand the changes required to support the replatformed service. We will support you throughout the change process. 6.4 RSA Tokens DIA has assessed the use of RSA Tokens and the decision has been made to integrate the replatformed RealMe with the existing RSA Token Server. Agencies who currently use RSA Tokens for applications other than the RealMe Help Desk will not need to take any further action. Onboarding Page 17 of 31
Agency Engagement Pack
7 Implementation Guide
7.1 Pre-requisites
All agencies should test the endpoints prior to integration to ensure they are accessible. For
further information regarding this process, please refer to Test endpoint availability, in Appendix
One – Endpoint Test on page 27 of this document.
If the endpoints are not accessible, then either:
- update firewall rules to use DNS based whitelisting or
- remove the existing firewall rules and rely on mutual SSL based authentication/access.
Note: Whitelisting the IP Address range for Azure AD B2C is not the preferred approach. This is
because Microsoft cannot guarantee that the IP Address ranges will remain fixed. If you wish to
discuss this, please contact us via integrations@realme.govt.nz.
7.2 RealMe® Login Service and Assertion Service
Agencies who use the RealMe Login Service (basic login flow) or the RealMe Assertion Service (assert
only flow) will need to update their applications to use a new Identity Provider (IdP) metadata file.
SAML v2.0 Binding Code Changes Configuration Changes
Post Binding No code changes are required to Install the new RealMe Login Service IdP
integrate with the replatformed metadata into your application, for further
RealMe Login service. information refer to Appendix Two - IdP
Metadata, on page 29 of this document.
Artifact Binding As per POST Binding. Provide a copy of your Mutual SSL
certificate to
integrations@realme.govt.nz.
Ensure the new endpoint is accessible, for
further information refer to Appendix One
– Endpoint Test on page 28 of this
document.
Install the new RealMe Login Service IdP
metadata into your application, for further
information refer to Appendix Two - IdP
Metadata, on page 29 of this document.
Onboarding Page 18 of 31Agency Engagement Pack
7.3 RealMe Assertion Service – Assert and Login Flow
Agencies who use the RealMe Assert and Login Flow are no longer required to interact with
iCMS/RCMS. The table below lists the changes which are required to integrate your application to
the new RealMe Service.
SAML v2.0 Binding Code Changes Configuration Changes
Post Binding Agencies who are currently Install the new RealMe Login Service IdP
integrated with iCMS or RCMS metadata into your application, for further
redeem an opaque token to information refer to Appendix Two - IdP
obtain the user’s FLT. This call is Metadata, on page 29 of this document.
no longer required for the
replatformed RealMe services.
Instead the agencies will obtain
the user’s FLT for agency from
the Subject element of the
Assertion. This is the same
method that is currently used by
the Login service.
For further detail, refer to
Assertion Subject Example
section (below).
Artifact Binding As per POST Binding. Provide a copy of your Mutual SSL
certificate to
integrations@realme.govt.nz.
Ensure the new endpoint is accessible, for
further information refer to Appendix One
– Endpoint Test on page 28 of this
document.
Install the new RealMe Login Service IdP
metadata into your application, for further
information refer to Appendix Two - IdP
Metadata, on page 29 of this document.
Onboarding Page 19 of 31Agency Engagement Pack
7.3.1 Assertion Subject Example
The current Subject element returned by the Assert then Login flow provides a transient NameID
and the service must use the Opaque Token to call RCMS and obtain the user’s FLT for the agency.
d31aefd7f40818a0bec68a79779a397f
The replatformed Subject element returned by the Assert then Login flow will provide a persistent
NameID as the user’s FLT for the agency. There is no need to call RCMS or to decrypt an Opaque
Token.
WLG776CB3AB8CD92CC4E040007F01004085
Onboarding Page 20 of 31Agency Engagement Pack
7.4 RealMe HelpDesk Web Application - Federation Flow
7.4.1 Overview
The following are the key business objectives for the RealMe helpdesk solution:
• to provide a better experience for service desk operators and
• a standards-based integration approach to reduce development cost for agencies
7.4.2 Messaging Flow
The diagram below provides a high-level overview of the Federation Flow.
Agency Service Desk
1. Access RealMe
HD Web app
DIA MBIE IR MSD
Agency Service Desk
Operator
2. SAML IdP Initiated SSO
Azure AD B2C SAMLv2.0 SP Agency IdP
Metadata
Configuration
HD Operators
RealMe Helpdesk Federation Hub Credentials Store
3. redirect with operator token
RealMe
Front Door RealMe
Azure AD B2C
4. HD Landing Page
Get User Details Graph API
RealMe Azure RealMe Helpdesk
Resources Webapp
implements
Recover username Reset password Search user User summary
Update contact Update 2FA
Transaction details details Methods
RealMe Helpdesk Business Functions
Figure 1 - Federation Flow
The key points regarding the messaging flow are as follows:
1) The agency service desk operator is authenticated using their agency enterprise credentials. The
service desk operator receives a call from the user for RealMe support. The service desk
operator:
• validates the user and may identify the user if they are an existing agency customer.
• triggers the RealMe support process from the agency service desk application.
2) The agency service desk application redirects the operator to the agency IAM product to initiate
a seamless single sign-on process with the RealMe Helpdesk Web Application. The agency IAM
product:
• creates a SAMLv2.0 assertion with the service desk operators email address as the name id
and the user’s FLT as an attribute if the service desk operator identifies the user.
Onboarding Page 21 of 31Agency Engagement Pack
• signs and encrypts the SAMLv2.0 assertion and creates a SAMLv2.0 response from the
SAMLv2.0 assertion.
• redirects the service desk operator to the RealMe Helpdesk Federation Hub with a SAMLv2.0
response using IdP initiated SSO.
3) The RealMe Helpdesk Federation Hub:
• decrypts the SAMLv2.0 assertion and verifies the signature of the SAMLv2.0 assertion.
• identifies the service desk operator based on operator identifier (name id). If no matching
service desk operator is found, then a new service desk operator account is created with the
operator email address and agency identifier, i.e. the SAML EntityID.
4) The RealMe Helpdesk Federation Hub creates an operator token (JWT) and redirects the service
desk operator to the RealMe Helpdesk web application. If the user’s FLT was included as an
attribute, the details of the associated user will be displayed.
7.4.3 Integration requirements
The agencies are required to complete the following tasks to enable federation with the RealMe web
application:
1. Enable SAMLv2.0 IdP functionality from within their IAM product.
2. Provide a SAMLv2.0 IdP metadata file to the RealMe team. The IdP metadata file must
contain a SAMLv2.0 signing certificate. Please refer to the Agency Service Desk IdP metadata
file section on page 23 of this document for a sample file.
3. Upload the RealMe Helpdesk SAMLv2.0 SP metafile file. Please refer to the section RealMe
Helpdesk SP metadata file on page 24 of this document for a sample file.
7.4.4 Message requirements
The following messaging requirements MUST be adhered to:
Requirement Description
Integration Standard SAMLv2.0
Profile IdP Initiated WebSSO profile
Binding POST Binding
In addition:
• The SAMLv2.0 Response MUST contain a SAMLv2.0 Assertion.
• The SAMLv2.0 Assertion MUST:
o be encrypted using the ReaMe HelpDesk SAML SP Certificate.
o set the NameID attribute to the service desk operators agency email address
• The SAMLv2.0 Assertion MAY include:
o the customer_flt attribute set to the user’s FLT
o the supported_service attribute to set the user’s Help Desk3
Please refer to the Agency Service Desk SAML Assertion section on page 25 of this document for a
sample SAML Assertion.
3
The supported_service attribute may be used when the agency operates more than one Help Desk across
multiple privacy domains. It allows the agency to specify which privacy domains and underlying services the
Help Desk Operator can view transactions for.
Onboarding Page 22 of 31Agency Engagement Pack
7.4.5 Examples
7.4.5.1 Agency Service Desk IdP metadata file
The following is an example of an Agency Service Desk IdP metadata file.
j/Ve4DSKtJvT+i7RMhGKYOSOOhY=
UJPcgxE+2LhYs2vbJ4IPuL9zycua6IVxGFQSTd8EnP+dKT6ha3RWwE7GfTdi2WFkq9V/n1Z3y07D
e52ZGUxhZ2BuqrCv1U6s7MfdvTIvRv8V7KuTU8D1q891SiZlPNKW52uC+wgpOMtc5VYAVBkA6IEqdUtJyXQCAePex0L/
Z1s=
CERT
CERT
Onboarding Page 23 of 31Agency Engagement Pack
7.4.5.2 RealMe Helpdesk SP metadata file
The following is an example of the RealMe HelpDesk Service Provider metadata file.
CERT
CERT
128
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Onboarding Page 24 of 31Agency Engagement Pack
7.4.5.3 Agency Service Desk SAML Assertion
The following is an example of an unencrypted SAMLv2.0 Assertion from an agency service desk:
https://dia.govt.nz/
joe.bloggs@dia.govt.nz
https://dia.govt.nz/
urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
test_supported_service
AZU7F05C7FEFEXC4199853CE2D139961130
Onboarding Page 25 of 31Agency Engagement Pack
8 Key Contacts
Name Role Contact Information Additional Information
RealMe® Technical Integration integrations@realme.govt.nz For any issues relating to the
Replatforming Support replatforming of your service
Technical Support
Also, for the confirmation of
connectivity following
replatforming.
RealMe Business Support business@realme.govt.nz For high level questions
Replatforming regarding the replatforming
Business Support process.
RealMe Escalation Support Phone number (to be For the escalation of any
Replatforming supplied prior to go-live) issues or in the event of an
Escalation issue with email.
Support
Please contact
integrations@realme.govt.nz
in the first instance.
Onboarding Page 26 of 31Agency Engagement Pack
9 Appendix One – Endpoint Test
Firewall changes can be applied prior to implementation. A simple telnet test should be completed
post firewall change and prior to the cut-over weekend to confirm connectivity to the environment.
9.1 Replatformed RealMe® Endpoints
The endpoints for the replatformed RealMe are below. Please note that these endpoints will not be
testable until each environment is deployed.
Environment Component EndPoint
MTS Login Service https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-
(POST Binding) 00fa09b50c16/B2C_1A_DIA_RealMe_LoginService/Samlp/sso/login
Login Service https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-
(Artifact Binding) 00fa09b50c16/B2C_1A_DIA_RealMe_LoginService_ArtifactBinding/Samlp/sso/
login
Assertion Service https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-
(POST Binding) 00fa09b50c16/B2C_1A_DIA_RealMe_AssertionService/Samlp/sso/login
Assertion Service https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-
(Artifact Binding) 00fa09b50c16/B2C_1A_DIA_RealMe_AssertionService_ArtifactBinding/Samlp/
sso/login
ITE Login Service https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-
(POST Binding) 9599b0d37348/B2C_1A_DIA_RealMe_LoginService/Samlp/sso/login
Login Service https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-
(Artifact Binding) 9599b0d37348/B2C_1A_DIA_RealMe_LoginService_ArtifactBinding/Samlp/sso
/login
Assertion Service https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-
(POST Binding) 9599b0d37348/B2C_1A_DIA_RealMe_AssertionService/Samlp/sso/login
Assertion Service https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-
(Artifact Binding) 9599b0d37348/B2C_1A_DIA_RealMe_AssertionService_ArtifactBinding/Samlp
/sso/login
Production Login Service https://login.realme.govt.nz/32179062-92f6-4eb0-89bc-
(POST Binding) df400a9e0367/B2C_1A_DIA_RealMe_LoginService/Samlp/sso/login
Login Service https://login.realme.govt.nz/32179062-92f6-4eb0-89bc-
(Artifact Binding) df400a9e0367/B2C_1A_DIA_RealMe_LoginService_ArtifactBinding/Samlp/sso/
login
Assertion Service https://login.realme.govt.nz/32179062-92f6-4eb0-89bc-
(POST Binding) df400a9e0367/B2C_1A_DIA_RealMe_AssertionService/Samlp/sso/login
Assertion Service https://login.realme.govt.nz/32179062-92f6-4eb0-89bc-
(Artifact Binding) df400a9e0367/B2C_1A_DIA_RealMe_AssertionService_ArtifactBinding/Samlp/
sso/login
9.1.1 Artifact Binding Endpoints
Environment EndPoint
ITE https://ite.nmapi.realme.govt.nz/v1.0/artifact/resolution
Production https://nmapi.realme.govt.nz/v1.0/artifact/resolution
Onboarding Page 27 of 31Agency Engagement Pack
9.2 Connectivity Test
1. Log on to the server which makes the backchannel calls
2. Run the following command:
telnet domain_name
This will check connectivity to the replatformed Realme endpoint. Note that you need to run a
connectivity test for each endpoint that your application uses in each of the environments.
A successful connection is as per the following sections. Note: the IP address shown in the example
below may differ as Azure AD B2C uses IP address ranges.
9.2.1 Unix
$ telnet domain_name 443
Trying NNN.NNN.NNN.NN ...
Connected to NNN.NNN.NNN.NN.
Escape character is '^]'.
^]
telnet> quit
Connection closed.
9.2.2 Windows
F:\>telnet domain_name 443
(blank screen should be shown – press CTRL+] to quit)
Onboarding Page 28 of 31Agency Engagement Pack
10 Appendix Two - IdP Metadata
10.1 Installation Steps
1. Install the new RealMe® Login Service IdP metadata into your service/application and, where
applicable:
a. Install the applicable RealMe public certificates into the agency certificate store(s)
b. Update the configuration of your application(s) to replace the necessary certificate
thumbprints.
Note: Make sure you replace the old thumbprints/aliases with the new ones, ensuring
the correct certificate thumbprint is used.
2. Restart your application.
3. Perform a series of smoke tests to ensure connectivity is achieved. This should include:
a. Successful login to the service/application and, where applicable, confirm the following
function as expected:
i. Co-branding
ii. Consent
iii. Verified Attributes
iv. Multi-factor authentication
v. RealMe Help Desk application
4. Confirm connectivity by emailing integrations@realme.govt.nz providing the service name(s)
and related EntityID(s) that have been successfully updated.
Onboarding Page 29 of 31Agency Engagement Pack
10.2 Message Testing Site (MTS)
For information regarding integration to MTS please refer to Try it out now | RealMe for Developers
and Integration Teams. The MTS RealMe Replatforming Bundle is available here.
Metadata and Certificates for Artifact binding are available on request for legacy support only.
10.3 Integration Testing Environment (ITE)
10.3.1 Certificate Information
Certificate File Name Thumbprint
Usage
Mutual SSL Back realme_mutual_tls.crt 10e565c5781469e7b6d984324889cb1022573f28
Channel Cert
SAML Signing Cert realme_signing.crt d32739d5559b24cf4fb3c4a4116a2be89bf3274f
10.3.2 RealMe Public Metadata
The ITE RealMe Replatforming Bundle is available here.
Important Note: unlike the existing RealMe the ITE RealMe Replatforming Bundle contains separate
SAML IdP metadata files for POST and Artifact binding. Please make sure you choose the correct one
for your implementation. If you are not sure which binding your service uses, please contact us on
integrations@realme.govt.nz for advice.
Service Metadata
Login Realme_IDP_Metadata_LoginService.xml
(POST Binding)
Login Realme_IDP_Metadata_LoginService_ArtifactBinding.xml
(Artifact Binding)
Assert Realme_IDP_Metadata_AssertionService.xml
(POST Binding)
Assert Realme_IDP_Metadata_AssertionService_ArtifactBinding.xml
(Artifact Binding)
Onboarding Page 30 of 31Agency Engagement Pack
10.4 Production Environment
10.4.1 Certificate Information
Certificate Usage File Name Thumbprint
Mutual SSL Back realme_mutual_tls.crt 168aa689bb7b7c3a6b54d3803c8eeb559a0d30e9
Channel Cert
SAML Signing Cert realme_signing.crt fbc46a64907691013039c8a01fb5e22b13e9d217
10.4.2 RealMe Public Metadata
The Production RealMe Replatforming Bundle is available here.
Service Metadata
Login Realme_IDP_Metadata_LoginService.xml
(POST Binding)
Login Realme_IDP_Metadata_LoginService_ArtifactBinding.xml
(Artifact Binding)
Assert Realme_IDP_Metadata_AssertionService.xml
(POST Binding)
Assert Realme_IDP_Metadata_AssertionService_ArtifactBinding.xml
(Artifact Binding)
Onboarding Page 31 of 31You can also read
