SAML

Security Assertion Markup Language (SAML) is an open standard for securely exchanging information about identities.

Your service must use a system to send SAML messages to the Verify Hub and receive SAML responses in return. This system is known as a Service Provider.

You can either:

• use a Service Provider built by Verify, known as the Verify Service Provider (recommended)
• configure an off-the-shelf product to use as a Service Provider
• build your own Service Provider

Whatever option you choose, you must run SAML compliance tests to check you can send and receive SAML messages successfully.

Verify Service Provider

Refer to the documentation on GitHub to find out how to download, configure and use the Verify Service Provider.

You can use the Verify Service Provider to:

• generate a SAML (AuthnRequest) request to send to the Verify Hub
• translate the SAML response from the Verify Hub into JSON

You must host the Verify Service Provider on your own infrastructure. You can connect multiple services to one instance.

To use the Verify Service Provider, you need to have:

• Java 8
• a working Matching Service Adapter

Use or build a different Service Provider

If you choose to configure an off-the-shelf product or build your own Service Provider, you should contact Verify before starting any development work.

You must:

• understand how SAML works with GOV.UK Verify
• decide how to add the SAML functionality to your service
• implement certain functionality to ensure smooth interoperability with Verify

This means you must:

• consume Verify Hub signing certificates directly from the Verify Hub metadata
• consume MSA signing certificates metadata from your Matching Service Adapter (MSA) metadata, or support multiple MSA signing certificates directly in your service
• support multiple encryption keys for your service

You must also follow:

• ‘Identity Assurance Hub Service SAML 2.0 Profile‘ – describes the SAML specifications you must respect to connect to the GOV.UK Verify hub
• ‘Identity Assurance Hub Service Profile – Authentication Contexts‘ – describes how the level of assurance is specified
• ‘Identity Assurance Hub Service Profile – SAML Attributes‘ – describes the matching dataset attributes and fraud event assertion attributes

The SAML profile used by GOV.UK Verify builds on the OASIS documentation for the SAML 2.0 standard.