Core steps for technical integration

This page describes the core technical steps required for a basic Service Provider integration to the ITE or Production environments of the RealMe login service or the RealMe assertion service.

Prerequisites

The prerequisites for integration into the ITE environment include:

  • Successful integration with the respective Message Testing Service (MTS) environment. For most SAML SP solutions, this is required to test exception flows as well as assist with SAML component development.
  • Perform an NTP synchronisation and set up a schedule to regularly update the time on the integrating server; security controls for SAML messaging include timestamp checking. Find out more.
  • An identity risk assessment has been completed for a RealMe login service integrations, or a private sector organisation is qualified as a participating agency for a RealMe assertion service integration.
  • Business processes reviewed by the RealMe integration team.

The prerequisites for Production integration include:

  • Successful integration into the respective ITE environment, including RealMe approved application design and co-branding decisions.
  • Consideration for how to synchronise the time of the production server, as per ITE.
  • Deployment (go-live) criteria has been met.
  • Production scheduling agreed with the RealMe integration team.

Core integration steps

1. Create certificates for the online service

For a SAML POST binding integration, a valid certificate is required for signing and encryption. Generally an additional certificate is not required for a subsequent online service for the same business context.

The certificates must meet the RealMe certificate requirements. The certificates produced must be signed by a RealMe compatible trusted Certificate Authority and must comply with the RealMe certificate naming convention.

It is also expected that the online service will have an additional certificate to support https webpage content.

2. Import the RealMe IdP metadata file

Import the RealMe login service SAML v2.0 metadata file and create an association with the appropriate RealMe login service environment.

Download the required ITE or Production metadata file:

ITE login service IdP metadata [ZIP, 2.3 KB]

Production login service IdP metadata [ZIP, 2.2 KB]

3. Export the online service SP metadata file

Export the organisation’s SP SAML v2.0 metadata file from the SAML v2.0 component. The key components to check for compliance with RealMe metadata requirements are:

  • EntityID
  • Endpoints (Attribute Consumer Service)
  • Public X.509 cert
  • Organisation info and Contact info.
4. Complete the integration checklist

Download and complete the required ITE or Production checklist:

ITE login checklist [DOC, 142 KB]

Production login checklist [DOC, 143 KB]

Upload the completed checklist to your project folder on the Shared Workspace - https://see.govt.nz/realme/realme/default.aspx (external link)  and notify your RealMe integration project manager. Remember to also upload the co-branding image file and the SP metadata file created in the previous step.

For the ITE environment, in particular, it is recommended that you arrange a walkthrough meeting with the RealMe integration team.

1. Create certificates for the online service

For a SAML POST binding integration, a valid certificate is required for signing and encryption. Generally an additional certificate is not required for a subsequent online service for the same business context.

The certificates must meet the RealMe certificate requirements. The certificates produced must be signed by a RealMe compatible trusted Certificate Authority and must comply with the RealMe certificate naming convention.

It is also expected that the online service will have an additional certificate to support https webpage content.

2. Import the RealMe IdP metadata file

Import the RealMe assertion service SAML v2.0 metadata file and create an association with the appropriate RealMe assertion service environment.

Download the required ITE or Production metadata file:

ITE assertion service IdP metadata [ZIP, 2.3 KB]

Production assertion service IdP metadata [ZIP, 2.2 KB]

3. Export the online service SP metadata file

Export the organisation’s SP SAML v2.0 metadata file from the SAML v2.0 component. The key components to check for compliance with RealMe metadata requirements are:

  • EntityID
  • Endpoints (Attribute Consumer Service)
  • Public X.509 cert
  • Organisation info and Contact info.
4. Complete the integration checklist

Download and complete the required ITE or Production checklist:

ITE assertion checklist [DOC, 244 KB]

Production assertion checklist [DOC, 244 KB]

Upload the completed checklist to your project folder on the Shared Workspace - https://see.govt.nz/realme/realme/default.aspx (external link)  and notify your RealMe integration project manager. Remember to also upload the co-branding image file and the SP metadata file created in the previous step.

For the ITE environment, in particular, it is recommended that you arrange a walkthrough meeting with the RealMe integration team.

Post-integration checks

The RealMe integration team will notify you when the integration has been completed.

To test connectivity and completeness of the configuration, you should send an AuthnRequest to the login service. Check that components such as the co-branding logo, login page text and other items are as expected. Also check that the online service is handling SAML exceptions as expected by confirming user triggered conditions for AuthnFailed and Timeout. If the online service required a Login Attributes Token, the receipt of this should also be tested.

Contact the RealMe integration team if any integration configuration problems are identified.

Subscribe