NAME

nzigovt - Tools for interacting with the New Zealand 'igovt Logon Service'

SYNOPSIS

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

  Commands:

   make-meta   generate XML metadata for your Service Provider (SP)
   make-certs  generate certificate/key-pair files
   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
   --allow-create     can be used with 'make-req' to allow account creation
   --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 <detail> additional detail for certificate subject
   --domain <name>    agency site domain e.g.: innovation.govt.nz

DESCRIPTION

The nzigovt script and related modules from the Authen::NZigovt distribution provide tools for interacting with the New Zealand 'igovt logon service' operated by the Department of Internal Affairs. These tools ARE NOT produced by nor endorsed by the Department of Internal Affairs. 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') two self-signed certificates will be generated. For integration 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).

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 - for initiating a logon.

Note: By default, the AuthnRequest will have the AllowCreate flag set to false (i.e.: the user must already have an igovt logon 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:

  nzigovt -c /etc/igovt-conf make-req | nzigovt -c /etc/igovt-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 SML artifact must be resolved very soon after it is generated or it will expire.

version

Print version number of Authen::NZigovt 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::NZigovt for more information about config files.

--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 "<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 /L=Wellington/ST=Wellington/C=NZ).

LICENSE AND COPYRIGHT

Copyright (c) 2010-2011 the New Zealand Electoral Enrolment Centre

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.