Installation and Maintenance

The Security requirements of the MyAccount service require additional steps over and above the usual API worker installation and configuration.

General

To access the services of myaccount the worker requires the following to be in place

• Your organisation must register with the myaccount portal and agree to the terms and condition of service.
• Client and Server Digital Certificates. The Server certificates for both UAT and Production will be issued by the myaccount team, you will need to provide your own client certificate.
• Self Signed certificates are acceptable for UAT but not Production. The client certificates must satisfy the terms and conditions of service and have a SubjectKey Identifier extension.
• The IP address of the API server from where the services are being called must be fixed and known by the myaccount servers so that it can be white listed.
• Each call will require a Callertoken (username) that is issued by the myaccount team.
• You will need to ensure that the API server allows access to myaccount Test and Production wsdl urls and endpoints and to Certificate Revocation List and Policy Urls contained in the Server UAT and Production Certificates

Once you have your certificates you will need to make them available to the mygovscot worker. We do this by adding them to a keystore and sending it to the worker, the worker provides a number of methods that allow you to install and maintain the keystore but you will need to add the certificates locally. GOSS recommend you take a copy of the default cacerts ([APISERVER]\java\jre\lib\security\cacerts) as the basis for the worker keystore. You will need to add the server certificates provided by the myaccount team and your own client certificates. If you are happy using the Command line you can use the standard Java keytool Command if you are happier with a GUI then KeyStore Explorer is a good choice.

NB the Security requirements for mygovscot require 256 bit encryption which is stronger than allowed by the standard JVM. for version 10.0.4.0 of iCM you will need to install the Java Cryptography Extension (JCE) unlimited strength jurisdiction policy files these can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html future versions of iCM will include these files. once downloaded replace [APISERVER]\java\jre\lib\security\local_policy.jar and  [APISERVER]\java\jre\lib\security\export_policy.jar with those included in the download.

The worker configuration has five standard parameters

1. cacertsOverridePath: defaults to [APISERVER]/data/mygovscot/cacerts/cacerts, it must be a file accessible to the API server
2. cacertsKeyStorePassword:  defaults to null which means use the default password "changeit" you can of course change the password when you install the certificates
3. cacertsAliasPasswordProperties: defaults to [APISERVER]/data/mygovscot/cacerts/pw.properties,  it must be a file accessible to the API server (the file will be created automatically if it does nor exist
4. serverCertAlias: Alias of the myaccount certificate
5. clientCertAlias: Alias of your client certificate

if you have not changed the keystore password then the only additional elements you need to add to the api server config are 4 and 5.

Once the worker is configured and your keystore file is ready you can use the rest services provided by the worker to upload the store and set any certificate passwords.

The following sections assume you are running the API Server at http://localhost:5706.

Installing the Keystore

the worker has a rest method at /http/keystore that will except the keystore file from an HTTP Post. you could build a simple iCM form to perform the upload to http://localhost:5706/mygovscot/http/keystore or if you are happy with the command line and using cURL: 

curl -X POST -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -F "file=@/path/to/keystore.ks" "http://localhost:5706/mygovscot/http/keystore"

After the initial upload you can replace the keystore with a new version using the same command (you will need to do this when a certificate expires). if you wish to rollback to the previous version of the keystore you can call http://localhost:5706/mygovscot/http/rollback.

If the certificates have individual passwords you can add these by posting the alias and password http://localhost:5706/mygovscot/http/password again a simple iCM form containing two fields alias and password or using cURL:

curl -X POST -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -F "alias=certalias" -F "password=pass" "http://localhost:5706/mygovscot/http/password"

Again you can change the password at any time by re posting the form.

NB alias and password are case sensitive.

If you want to see the aliases of the certificates that are installed on the worker make a get request to http://localhost:5706/mygovscot/http/alias.