agency engagement pack - realme · 2021. 1. 20. · agency engagement pack onboarding page 2 of 31...

RealMe® Replatforming Agency Engagement Pack

Onboarding Component

Version 0.7 (FINAL DRAFT)

January 2021

Agency Engagement Pack

Onboarding of 31

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


Onboarding of 31

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.3 Integration Testing Environment (ITE) .............................................................................. 13

5.3.1 Pre-implementation Tasks ........................................................................................ 13



5.4 Production Environment ................................................................................................... 14

5.4.1 Pre-implementation Tasks ........................................................................................ 14



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 of 31

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.2 Connectivity Test ............................................................................................................... 27

9.2.1 Unix ........................................................................................................................... 28

9.2.2 Windows ................................................................................................................... 28

10 APPENDIX TWO - IDP METADATA ................................................................................... 29

10.1 Installation Steps ........................................................................................................... 29

10.2 Early Integration Test (EIT) ............................................... Error! Bookmark not defined.

10.2.1 Certificate Information ................................................ Error! Bookmark not defined.

10.2.2 RealMe Public Metadata .............................................. Error! Bookmark not defined.

10.3 Message Testing Site (MTS) .......................................................................................... 30

10.3.1 Certificate Information ............................................................................................. 30

10.3.2 RealMe Public Metadata ........................................................................................... 30

10.4 Integration Testing Environment (ITE) .......................................................................... 30


10.4.2 RealMe Public Metadata ........................................................................................... 30

10.5 Production Environment ............................................................................................... 31


10.5.2 RealMe Public Metadata .............................................. Error! Bookmark not defined.


Onboarding of 31

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 of 31

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 document)

• Engagement Plan (revised)

• 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 of 31

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 of 31

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 video)

A showcase of the replatformed RealMe®, in particular:

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

https://developers.realme.govt.nz/realme-events/realme-login-and-assertion-service-re-platforming

mailto:[email protected]


Onboarding of 31

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.

27/03/2020

24/10/2019 30/04/2021Nov-19 Dec-19 Jan-20 Feb-20 Mar-20 Apr-20 May-20 Jun-20 Jul-20 Aug-20 Sep-20 Oct-20 Nov-20 Dec-20 Jan-21 Feb-21 Mar-21 Apr-21

AGENCY ENGAGEMENT TIMELINEAs at December 2020

30/11/2020MTS BuildComplete25/09/2020

Issue AgencyEngagement Pack

(final draft)

17/12/2019RealMe B2C

Agency Briefing

5/02/2020Agency Workshop

One

21/01/2021Issue Agency

Engagement Pack(final)

16/10/2020Publish Security

and Privacyinformation

26/01/2021 - 18/03/2021Agency Integration

Testing (ITE) anddrop in workshops19/02/2020

Agency WorkshopTwo

23/11/2019RealMe RePlatforming

Project Initiated

19/10/2020 - 13/11/2020Unify System Integration

Testing

6/11/2020EIT BuildComplete

15/05/2020 - 16/10/2020Unify Build Phase II

- data migration validation - requirement refinements- RSA Token

- MTS Development Tools

6/01/2020 - 15/02/2020Initiate Project

And Onboard Unify

16/11/2020 - 18/12/2020DIA Integration Testing (UAT)

17/02/2020 - 14/05/2020Unify Build Phase I- design- configure environments- development

- data migration

10/04/2021

AgencyReplatforming

12/04/2021Service Transition

Complete

11/11/2019 - 24/12/2019Unify Proof of Concept

1/03/21Help Desk

documentationavailable

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

21 January 2021 Issue final Agency Engagement Pack

26 January 2021 to 18 March 2021 Agency Integration Testing (ITE) and drop in workshops

1 March 2021 (to be confirmed) Help Desk guides / documentation available

10 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 of 31

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 [email protected] 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 18 Dec 20

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

9 Nov to 20 Jan 21

DIA DIA team will be available to support agencies in need of assistance with the integration exercise.

20 Jan 21 Agencies Participating agencies have confirmed integration or have requested replatforming support.




Onboarding of 31

5.1.2 Post-implementation Tasks Date Responsible Action

22 Jan 21 DIA RealMe EIT deployment post implementation review.

TBC DIA Decommission EIT RealMe.


Onboarding of 31

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

TBC DIA Publish Agency Onboarding Pack and RealMe MTS Replatforming Bundle to the RealMe Developers website.

TBC 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


proceed. 7. Amend the SP metadata provided in the bundle to reflect your service’s

endpoints and upload via MTS.


TBC UNIFY Replatforming Complete

TBC DIA Notify agencies that replatforming is successful and replatforming tasks can commence.

TBC Agencies Complete integration tasks. For further detail regarding the required tasks, refer to the Implementation Guide on page 18 of this document.



TBC DIA DIA team will be available to support agencies in need of assistance with the replatforming exercise.

TBC Agencies All interested agencies have confirmed replatforming or have requested replatforming support.


TBC DIA RealMe MTS Replatforming post implementation review.

TBC DIA Decommission existing MTS RealMe.




Onboarding of 31

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


proceed.


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 to 18 Mar 21

Agencies Complete replatforming tasks. For further detail regarding the required

tasks, refer to the Implementation Guide on page 18 of this document.



26 Jan 21 to 18 Mar 21

DIA DIA team will be available to support agencies in need of assistance with the replatforming exercise.

26 Mar 21 Agencies All agencies have confirmed replatforming or have requested replatforming support.


TBC RealMe RealMe ITE Replatforming post implementation review.

TBC DIA Decommission existing ITE RealMe.




Onboarding of 31

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

1 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


proceed.

5.4.2 Implementation Tasks Date Time Responsible Action

9 Apr 21 17:00 DIA First go/no-go decision.

DIA to provide final 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.

10 Apr 21 TBC DIA Outage – Replatforming Occurring

Send agencies a reminder that replatforming will be commencing at 22:00 (time to be confirmed).

10 Apr 21 TBC 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.

10 Apr 21 TBC UNIFY Replatforming Complete

Existing RealMe environments to be taken offline.

10 Apr 21 TBC DIA Notify agencies that replatforming was successful and replatforming tasks can commence.

Agencies will not be able to connect with RealMe until their replatforming tasks are completed.



Onboarding of 31

Date Time Responsible Action

11 Apr 21 TBC Agencies Complete replatforming tasks. For further detail regarding

the required tasks, refer to the Implementation Guide on

page 18 of this document.



10 Apr 21 to 11 Apr 21

TBC DIA DIA team will be available to support agencies in need of assistance with the replatforming exercise.

11 Apr 21 TBC Agencies All agencies have confirmed replatforming or have requested replatforming support.

11 Apr 21 TBC DIA Final go/no-go decision

DIA to provide replatform go/no-go decision.

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.

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 of 31

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 of 31

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 of 31

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

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

integrate with the replatformed RealMe Login service.

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.

Artifact Binding As per POST Binding. Provide a copy of your Mutual SSL certificate to [email protected]. 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 of 31

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

integrated with iCMS or RCMS redeem an opaque token to obtain the user’s FLT. This call is 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).

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.

Artifact Binding As per POST Binding. Provide a copy of your Mutual SSL certificate to [email protected]. 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 of 31

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.

<saml:Subject> <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" NameQualifier="https://realme.govt.nz/realme/assert-idp" SPNameQualifier="https://www.sample-client.co.nz/onlineservices/service1"> d31aefd7f40818a0bec68a79779a397f </saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml:SubjectConfirmationData InResponseTo="a958a20e059c26d1cfb73163b1a6c4f9" NotOnOrAfter="2012-05-21T00:49:45Z" Recipient="https://www.sample-client.co.nz/sso/ACS"> </saml:SubjectConfirmationData> </saml:SubjectConfirmation> </saml:Subject>

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. <saml:Subject> <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" NameQualifier="https://realme.govt.nz/realme/assert-idp" SPNameQualifier="https://www.sample-client.co.nz/onlineservices/service1"> WLG776CB3AB8CD92CC4E040007F01004085 </saml:NameID> <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml:SubjectConfirmationData InResponseTo="a958a20e059c26d1cfb73163b1a6c4f9" NotOnOrAfter="2012-05-21T00:49:45Z" Recipient="https://www.sample-client.co.nz/sso/ACS"> </saml:SubjectConfirmationData> </saml:SubjectConfirmation> </saml:Subject>


Onboarding of 31

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.

SAMLv2.0 SPAzure AD B2C

RealMe Helpdesk Federation Hub

Agency IdP Metadata

Configuration

HD OperatorsCredentials Store

Agency Service Desk

MBIEDIA IR MSD

2. SAML IdP Initiated SSO

RealMe Azure Resources

3. redirect with operator token

RealMe Helpdesk

Webapp

RealMe Front Door

Recover username Reset password Search user User summary

Transaction details

Update contact details

RealMe Helpdesk Business Functions

implements

Update 2FA Methods

Azure AD B2C

Graph API

RealMe

Get User Details

Agency Service Desk Operator

1. Access RealMe HD Web app

4. HD Landing Page

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 of 31

• 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 of 31

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.

<?xml version="1.0"?> <md:EntityDescriptor validUntil="2026-10-09T08:46:38Z" entityID="https://sampleagency.govt.nz/IdP" cacheDuration="P30DT0H0M0S" ID="id-ZfZy3D3rfBhZavO5itOnwe1qi5qx-VRixyFbseoL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:x500="urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query" xmlns:ns10="urn:oasis:names:tc:SAML:profiles:v1metadata" xmlns:mdext="urn:oasis:names:tc:SAML:metadata:extension" xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute" xmlns:enc="http://www.w3.org/2001/04/xmlenc#" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

<dsig:Signature> <dsig:SignedInfo>

<dsig:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/> <dsig:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <dsig:Reference URI="#id-ZfZy3D3rfBhZavO5itOnwe1qi5qx-VRixyFbseoL">

<dsig:Transforms> <dsig:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> <dsig:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>

</dsig:Transforms> <dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <dsig:DigestValue>j/Ve4DSKtJvT+i7RMhGKYOSOOhY=</dsig:DigestValue>

</dsig:Reference> </dsig:SignedInfo> <dsig:SignatureValue>UJPcgxE+2LhYs2vbJ4IPuL9zycua6IVxGFQSTd8EnP+dKT6ha3RWwE7GfTdi2WFkq9V/n1Z3y07De52ZGUxhZ2BuqrCv1U6s7MfdvTIvRv8V7KuTU8D1q891SiZlPNKW52uC+wgpOMtc5VYAVBkA6IEqdUtJyXQCAePex0L/Z1s=</dsig:SignatureValue> <dsig:KeyInfo>

<dsig:X509Data> <dsig:X509Certificate>CERT</dsig:X509Certificate>

</dsig:X509Data> </dsig:KeyInfo>

</dsig:Signature> <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAuthnRequestsSigned="true">

<md:KeyDescriptor use="signing"> <dsig:KeyInfo>

<dsig:X509Data> <dsig:X509Certificate>CERT</dsig:X509Certificate>

</dsig:X509Data> </dsig:KeyInfo>

</md:KeyDescriptor> <md:SingleSignOnService Location="https://sample.agency.govt.nz/idp/samlv20" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>

</md:IDPSSODescriptor> </md:EntityDescriptor>


Onboarding of 31

7.4.5.2 RealMe Helpdesk SP metadata file The following is an example of the RealMe HelpDesk Service Provider metadata file.

<?xml version="1.0" encoding="UTF-8" standalone="true"?> <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://www.logon.realme.govt.nz/helpdesk">

<SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAssertionsSigned="true" AuthnRequestsSigned="false">

<KeyDescriptor use="signing"> <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

<ds:X509Data> <ds:X509Certificate>CERT</ds:X509Certificate>

</ds:X509Data> </ds:KeyInfo>

</KeyDescriptor> <KeyDescriptor use="encryption">

<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data>

<ds:X509Certificate>CERT</ds:X509Certificate> </ds:X509Data>

</ds:KeyInfo> <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">

<xenc:KeySize xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">128</xenc:KeySize> </EncryptionMethod>

</KeyDescriptor> <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat> <AssertionConsumerService Location="https://www.logon.realme.govt.nz/sso/Consumer/metaAlias/helpdesk/sp" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" isDefault="true" index="0"/>

</SPSSODescriptor> </EntityDescriptor>


Onboarding of 31

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:

<saml:Assertion xmlns:samlp=\"urn:oasis:names:tc:SAML:2.0:protocol\" xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" ID=\"_3da2d918-8e82-47b9-915a-8ccc56a75309\" Version=\"2.0\" IssueInstant=\"2020-10-19T03:11:29.365Z\" xmlns:saml=\"urn:oasis:names:tc:SAML:2.0:assertion\"> <saml:Issuer>https://dia.govt.nz/</saml:Issuer> <saml:Subject> <saml:NameID>[email protected]</saml:NameID> <saml:SubjectConfirmation Method=\"urn:oasis:names:tc:SAML:2.0:cm:bearer\"> <saml:SubjectConfirmationData NotOnOrAfter=\"2020-10-19T03:13:29.392Z\" Recipient=\"https://b2cdiadev01rmhdodir.b2clogin.com/b2cdiadev01rmhdodir.onmicrosoft.com/B2C_1A_SAML_IdP_Initiated_SignUpSignIn_DIA/samlp/sso/assertionconsumer\" /> </saml:SubjectConfirmation> </saml:Subject> <saml:Conditions NotOnOrAfter=\"2020-10-19T03:13:29.392Z\"> <saml:AudienceRestriction> <saml:Audience>https://dia.govt.nz/</saml:Audience> </saml:AudienceRestriction> </saml:Conditions> <saml:AuthnStatement AuthnInstant=\"2020-10-19T03:11:29.365Z\"> <saml:AuthnContext> <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef> </saml:AuthnContext> </saml:AuthnStatement> <saml:AttributeStatement> <saml:Attribute Name=\"supported_service\"> <saml:AttributeValue>test_supported_service</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name=\"customer_flt\"> <saml:AttributeValue>AZU7F05C7FEFEXC4199853CE2D139961130</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion>


Onboarding of 31

8 Key Contacts Name Role Contact Information Additional Information RealMe® Replatforming Technical Support

Technical Integration Support

[email protected] For any issues relating to the replatforming of your service

Also, for the confirmation of connectivity following replatforming.

RealMe Replatforming Business Support

Business Support [email protected] For high level questions regarding the replatforming process.

To be confirmed For the escalation of any issues or any general enquiries relating to the replatforming.

Please contact [email protected] in the first instance.





Onboarding of 31

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 (POST Binding)

https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_LoginService/Samlp/sso/login

Login Service (Artifact Binding)

https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_LoginService_ArtifactBinding/Samlp/sso/login

Assertion Service (POST Binding)

https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_AssertionService/Samlp/sso/login

Assertion Service (Artifact Binding)

https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_AssertionService_ArtifactBinding/Samlp/sso/login

ITE Login Service (POST Binding)

https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-9599b0d37348/B2C_1A_DIA_RealMe_LoginService/Samlp/sso/login


https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-9599b0d37348/B2C_1A_DIA_RealMe_LoginService_ArtifactBinding/Samlp/sso/login


https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-9599b0d37348/B2C_1A_DIA_RealMe_AssertionService/Samlp/sso/login


https://ite.login.realme.govt.nz/12c36372-4b2d-4865-b1d1-9599b0d37348/B2C_1A_DIA_RealMe_AssertionService_ArtifactBinding/Samlp/sso/login

Production Login Service (POST Binding)

https://login.realme.govt.nz/32179062-92f6-4eb0-89bc-df400a9e0367/B2C_1A_DIA_RealMe_LoginService/Samlp/sso/login


https://login.realme.govt.nz/32179062-92f6-4eb0-89bc-df400a9e0367/B2C_1A_DIA_RealMe_LoginService_ArtifactBinding/Samlp/sso/login


https://login.realme.govt.nz/32179062-92f6-4eb0-89bc-df400a9e0367/B2C_1A_DIA_RealMe_AssertionService/Samlp/sso/login


https://login.realme.govt.nz/32179062-92f6-4eb0-89bc-df400a9e0367/B2C_1A_DIA_RealMe_AssertionService_ArtifactBinding/Samlp/sso/login

9.2 Connectivity Test

1. Log on to the server which makes the backchannel calls 2. Run the following command:

telnet domain_name


Onboarding of 31

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 of 31

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 [email protected] providing the service name(s) and related EntityID(s) that have been successfully updated.



Onboarding of 31

10.2 Message Testing Site (MTS)

10.2.1 Certificate Information Certificate Usage File Name Thumbprint Mutual SSL Back Channel Cert To be advised

SAML Signing Cert To be advised

10.2.2 RealMe Public Metadata

MTS RealMe Replatforming Bundle here (link, to be published)

Service Metadata

Login (POST Binding)

To be advised

Login (Artifact Binding)

To be advised

Assert (POST Binding)

To be advised

Assert (Artifact Binding)

To be advised

10.3 Integration Testing Environment (ITE)

10.3.1 Certificate Information Certificate Usage

File Name Thumbprint

Mutual SSL Back Channel Cert

realme_mutual_tls.crt 10e565c5781469e7b6d984324889cb1022573f28

SAML Signing Cert realme_signing.crt d32739d5559b24cf4fb3c4a4116a2be89bf3274f


ITE RealMe Replatforming Bundle 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 [email protected] for advice.

Service Metadata


Realme_IDP_Metadata_LoginService.xml


Realme_IDP_Metadata_LoginService_ArtifactBinding.xml


Realme_IDP_Metadata_AssertionService.xml


Realme_IDP_Metadata_AssertionService_ArtifactBinding.xml

https://developers.realme.govt.nz/assets/Uploads/ITE-RealMe-Replatforming-Bundle-Jan-2021.zip



Onboarding of 31

10.4 Production Environment

10.4.1 Certificate Information Certificate Usage File Name Thumbprint Mutual SSL Back Channel Cert To be advised

SAML Signing Cert To be advised


MTS RealMe Replatforming Bundle here (link, to be published)

Service Metadata


To be advised


To be advised


To be advised


To be advised

agency engagement pack - realme · 2021. 1. 20. · agency engagement pack onboarding page 2 of 31...

Documents