The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

nzrealme - Tools for interacting with the New Zealand 'RealMe Login' service

SYNOPSIS

  nzrealme [options] <command> [args ...]

  Commands:

   make-meta   generate XML metadata for your Service Provider (SP)
   make-certs  generate certificate/key-pair files (see example below)
   make-bundle generate a zip archive of metadata and certificate files
   make-req    generate a SAML AuthnRequest, encoded as a URL
   dump-req    dissect the provided URL and dump the XML
   resolve     resolve an artifact to an FLT
   version     print module version number and exit
   help        detailed help message

  Options:

   --conf-dir <path>  pathname of directory containing metadata & cert files
   --type <name>      service type: "login" (default) or "assertion"
   --acs-index <num>  index number of ACS RealMe should redirect response to
   --allow-create     can be used with 'make-req' to allow account creation
   --resolve-flt      get FLT for "assertion" service response
   --env <name>       target environment (must be: 'mts', 'ite' or 'prod')
   --org <name>       organisation/agency name, e.g.: "Department of Innovation"
   --org-unit <name>  organisational unit, e.g.: "Innovation Labs"
   --subject-suffix <detail> additional detail for certificate subject
   --domain <name>    agency site domain e.g.: innovation.govt.nz
   --self-signed      make self-signed certificates (not recommended)

DESCRIPTION

The nzrealme script and related modules from the Authen::NZRealMe distribution provide tools for interacting with the New Zealand RealMe Login service operated by New Zeand Post and the Department of Internal Affairs. These tools ARE NOT produced by nor endorsed by NZPost or DIA. They are merely an implemention of the published protocols.

COMMANDS

The following commands are available:

make-certs

Generate two certificate/key pairs - one for signing and one for mutual SSL encryption. This step is not required for integrating with the development environment ('MTS') since certficates will be provided to you. For integration with the test environment ('ITE') or with the production environment ('PROD') two CSRs (Certificate Signing Requests) will be generated which you will then use to get signed certificates issued from an approved CA (Certification Authority).

If no further options are provided, you will be prompted for the required certificate parameters. You can specify all the answers on the command-line:

  nzrealme make-certs --conf-dir . --env ite \
      --org "Department of Innovation" \
      --org-unit "Innovation Labs" \
      --domain innovation.govt.nz \
      --subject-suffix "/L=Wellington/ST=Wellington/C=NZ"
make-meta

Generate (or edit) a Service Provider metadata file and save it with a digital signature.

make-bundle

Create a ZIP file containing the metadata and certificate files needed by the Identity Provider.

make-req

Generate a URL containing a SAML AuthnRequest. The --type option should be used to generate either a "login" request (the default) or an "assertion" request.

Note: By default, an AuthnRequest to the "login" service will have the AllowCreate flag set to false (i.e.: the user must already have a RealMe Login associated with this SP). Use --allow-create if you want the request to allow a new account and FLT to be created.

dump-req <request URL>

Takes a URL containing a SAML AuthnRequest; decodes it; and dumps the XML. For example:

  nzrealme -c /etc/realme-conf make-req | nzrealme -c /etc/realme-conf dump-req

This utility can be used to dump AuthnRequests produced by any SAML implementation.

resolve <artifact> <request ID>

This command takes two arguments - an artifact (either the whole URL or just the SAMLart part from the query string) and the request ID which was output from the original 'make-req' command.

The command will decode the SAML artifact; generate a SAML ArtifactResolve request; send the request to the IdP using SOAP over the SSL back-channel; validate the resulting assertion; and extract the FLT (Federated Logon Tag) from the response.

Note: in practice a SAML artifact must be resolved very soon after it is generated or it will expire.

version

Print version number of Authen::NZRealMe module and exit.

help

Display this documentation.

OPTIONS

--conf-dir <directory> (alias -c)

Specify the path to the directory containing the metadata files and certificate/key-pair files for signing requests and encrypting SSL traffic. See perldoc Authen::NZRealMe for more information about config files.

--type <name>

Use this option to direct the request to either the "login" service (the default) or the "assertion" service to retrieve identity attributes.

--acs-index <num>

Use this option with the 'make-req' command to generate a request with a non-default value for the 'AssertionConsumerServiceIndex' parameter. If not specified, the ACS used will be the one marked with isDefault="true".

--allow-create

Use this option with the 'make-req' command to generate a request for the "login" service which will allow the user to create a new login for your site. By default, the AllowCreate flag will not be enabled in the request and logins will only be allowed from users who have used their RealMe account with the site previously.

--env <name>

This option can be used with the make-certs command and specifies the target environment for the certificates. Acceptable values are 'mts', 'ite' and 'prod'.

If you do not provide any certificate parameters, you will be prompted.

--org "<name>"

The service provider agency/organisation name which should be used in the certificates.

--org-unit "<name>"

The optional organisational unit name for use in the certificates.

--subject-suffix "<detail>"

Optional additional details to go on the end of the certificate subject field. The CN will be calculated for you based on --domain. The O and OU will be added based on --org and --org-unit. Prefix each fieldname with a forward slash (e.g.: --subject-suffix "/L=Wellington/ST=Wellington/C=NZ"). Certification Authorities have historically required these location fields when signing requests.

--self-signed

When running the 'make-certs' command this option allows generating self-signed certificates rather than generating Certificate Signing Requests (CSRs). It used to be possible to use self-signed certs in the ITE environment (not production) but this is no longer the case so this option should probably never be used.

--disable-ssl-verify

When using the resolve command, this option will skip verification of the SSL certificate presented by the IdP. This is useful if you have not yet configured the necessary CA certs or if you consider the digital signature on the assertion provides sufficient guarantee of authority.

--to-file <filename>

This option is a debugging aid. When using the resolve command, this option will cause the SAML assertion response from the login or assertion service to be saved in a file.

--from-file <filename>

This option is a debugging aid. When using the resolve command, instead of communicating with the login or assertion service, this option will cause the SAML assertion response to be loaded from a file (presumably one created using the --to-file option.

LICENSE AND COPYRIGHT

Copyright (c) 2010-2022 Enrolment Services, New Zealand Electoral Commission

Written by Grant McLean <grant@catalyst.net.nz>

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.