nzrealme - Tools for interacting with the New Zealand 'RealMe Login' service
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)
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.
The following commands are available:
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"
Generate (or edit) a Service Provider metadata file and save it with a digital signature.
Create a ZIP file containing the metadata and certificate files needed by the Identity Provider.
Generate a URL containing a SAML AuthnRequest. The
--typeoption 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-createif 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.
Print version number of Authen::NZRealMe module and exit.
Display this documentation.
- --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::NZRealMefor 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".
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-certscommand 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.
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.
When using the
resolvecommand, 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
resolvecommand, 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
resolvecommand, 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
Copyright (c) 2010-2013 Enrolment Services, New Zealand Electoral Commission
Written by Grant McLean <email@example.com>
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.