Skip to main content
Table of contents

Configure your MSA

Below is the test-config.yml file:

# Configure the matching service adapter's server settings here.
  # Ports on which to listen for normal connections.
  # See for information on HTTPS and TLS connections.
    - type: http
      port: 8080
  # Ports on which to listen for admin tasks.
  # This can probably be set to the above port+1.
    - type: http
      port: 8081

# Add information about your matching service adapter (MSA) here.
  # The entityId is used for SAML communication with Verify.
  entityId: my-entity-id
  # The externalUrl is the internet-facing URL for your MSA.

# Configure the URLs for your local matching service here.
  # The matchUrl is where the MSA should post user attributes on a successful match
  # The accountCreationUrl is where the MSA should post attributes for unknown users

# Configure the key pairs used by your MSA for signing SAML messages here.
  # The primary signing key is used to sign all messages to Verify.
      # The certificate (.crt) containing the primary public signing key:
      certFile: test_primary_signing.crt
      # The common name (CN) of that certificate:
      name: Test MSA Signing
      # The PK8 (.pk8) containing the primary private signing key:
      keyFile: test_primary_signing.pk8
  # The public part of the secondary signing key is published in the MSA's metadata
  # during key rollovers but is otherwise unused by the MSA.
      certFile: test_secondary_signing.crt
      name: Test Another MSA Signing
      keyFile: test_secondary_signing.pk8

# Configure the key pairs used by your MSA for encrypting and decrypting SAML
# messages here. You can configure up to 2 encryption keys at a time and the MSA
# will attempt decryption with both. Only the first key will be used for encryption.
  - publicKey:
      certFile: test_msa_encryption_1.crt
      name: Test MSA Encryption 1
      keyFile: test_msa_encryption_1.pk8
  - publicKey:
      certFile: test_msa_encryption_2.crt
      name: Test MSA Encryption 2
      keyFile: test_msa_encryption_2.pk8

# Settings for connecting with the hub can be configured here
# if necessary.

# Settings for obtaining Verify's metadata can be configured here.
  environment: INTEGRATION
    path: test_ida_metadata.ts
    password: puppet
# To override the `hub` and `idp` trust stores, i.e. for testing or manual modifications,
# you can extract them from the MSA JAR file to a local disk, modify them, and then un-comment the following section:
  # hubTrustStore:
    # path: test_hub.ts
    # password: puppet
  # idpTrustStore:
    # path: test_idp.ts
    # password: puppet

# This is a required section if your service needs to consume European identities.
  enabled: ${EUROPEAN_IDENTITY_ENABLED} # true or false
  hubConnectorEntityId: # The URL of the metadata for the node that requests and receives identities from European countries.
  # Configure metadata for European countries.
    trustAnchorUri: # The location of the trust anchor used to validate country metadata
    metadataSourceUri: # The location of the aggregated country metadata
    trustStore: # The location and password for the truststore
      path: test_ida_metadata.ts
      password: puppet

## Options to add additional logging. By default, logs will be output to console.
## See for more information.
#  level: INFO
#  appenders:
#    - type: file
#      currentLogFilename: apps-home/test-rp-msa.log
#      archivedLogFilenamePattern: apps-home/test-rp-msa.log.%d.gz
#      logFormat: '%-5p [%d{ISO8601,UTC}] %c: %X{logPrefix}%m%n%xEx'
#    - type: console
#      logFormat: '%-5p [%d{ISO8601,UTC}] %c: %X{logPrefix}%m%n%xEx'
## By default the MSA signs messages using SHA-256.
## Switch the flag below to `true` if you need to revert to SHA-1 signing:
#shouldSignWithSHA1: false

Adapt your configuration file

Make the following changes to the YAML configuration file according to the environment where you want to use the MSA. Variations are indicated for the SAML compliance tool and integration and production environments.


Enter port numbers for the server application (applicationConnectors) and admin ports (adminConnectors).

If the MSA will be handling SSL termination (typically this will be handled by a proxy or load balancer like HAProxy), or if you don’t trust the network between the SSL termination endpoint and the MSA, then specify https rather than http for the type of connection. For more information, see the guidance in the DropWizard configuration manual.


Enter the entityID for the MSA in entityId. This should reflect the name of your service, for example https://<service name>/MSA. It’s good practice to use the MSA’s URI (where the hub will send matching requests) as its entityID, but this isn’t mandatory.

Enter the URI for your MSA in externalUrl.


Enter the URI for your local matching service in matchUrl.

If you’re creating new user accounts when a match isn’t found (see create new user accounts, enter the user account creation URI in accountCreationUrl.


Enter the paths of the primary SAML signing keys and certificates for your MSA in primary.

You’ll use different keys and self signed certificates for the integration and production environments. Use your preferred method to generate a new private key and self-signed certificate pair.

Make sure the private key is PKCS #8 formatted and DER encoded.

The self-signed certificate must be:

  • valid for one year
  • in X.509 format and PEM encoded

See an example
You can use OpenSSL to generate your keys and self-signed certificates. Most Linux distributions and Mac OS versions have OpenSSL installed.

# generate your key and self-signed certificate
openssl req -x509 -newkey rsa:2048 -days 365 -nodes -sha256 \
   -keyout <private-key>.key -out <certificate>.crt

# convert your MSA key to use DER encoding
openssl pkcs8 -topk8 -nocrypt \ 
   -in <private-key>.key -out <private-key>.pk8 -outform DER

The terminal will prompt you for information. You must provide a Common Name. All other information is optional.

The Common Name is the part of the certificate metadata that helps you identify that certificate more easily. You can use the Common Name to check you’ve uploaded the right certificate when using the GOV.UK Verify Manage certificates service.

There is no mandatory naming convention for Common Name, but it’s useful during troubleshooting if you include the:

  • name of your service
  • name of the component the certificate is for
  • environment name you generated the certificate for
  • certificate type
  • version number for your certificate

Common Name must not contain underscores.

For example, the common name could be Universal-Credit-MSA-integration-signing-01.

To convert a private key to PKCS#8 DER format, run the following command:

openssl pkcs8 -topk8 -nocrypt -in server.key -out server.pk8 -outform DER


Enter the paths and names of the encryption keys and certificates for your MSA in encryptionKeys. The names are used to identify the certificates in the metadata so should be meaningful and unique, for example, signing_1 and encryption_1.


Edit the url value and specify the location where the MSA accesses the SAML metadata:

  • for the SAML compliance tool, use the default setting in the test-config.yml file

  • for the integration environment, enter: in the test-config.yml file

  • for the production environment, use the default setting in the prod-config.yml file

In trustStore.path, specify the path to your metadata truststore file for the appropriate environment:

  • for the SAML compliance tool and the integration environment, use the provided test_ida_metadata.ts file (this is the default setting in the test-config.yml file)

  • for the production environment, use the provided prod_ida_metadata.ts file (this is the default setting in the prod-config.yml file)

Optionally, if you need to override the hub and idp truststore path for testing in Integration, uncomment the hubTrustStore and idpTrustStore sections in test-config.yml.


Configure according to the needs of your service.

If your service needs to consume European identities, set enabled: true. You also need to configure the URLs for the environments you want to use, for example integration or production. Enabling your service to consume European identities also implies that it will be using the universal JSON matching schema. The schema will apply to datasets from both European countries, as well as GOV.UK Verify identity providers.

If if you need to disable European identities, set enabled: false in this section. This setting also implies your MSA will be using the legacy JSON matching schema.