SAML Metadata Checklist and Recommendations - Digital-Platform-Services/My-NS-Account GitHub Wiki

Home

EntityDescriptor

ID - This globally unique identifier (GUID) must be a unique value, which cannot start with a number. Adding an underscore character to the beginning will ensure the metadata passes validation. GUIDs can be generated using an online tool, such as: Online GUID / UUID Generator.

entityID - each metadata must contain a unique entityID. It is recommended to include terms that name your app and environment. For example: ca.yourAppName.dev - including protocols such as "https" etc. are not required.

validUntil - the metadata must contain a validUntil expiry date. It is recommend to align the metadata expiry date to the expiry date of the certificates used to sign and encrypt (this will simplify renewal of certificates and metadata, as both will expire at the same time).

Example

<md:EntityDescriptor [...] 
ID="_6AF78AE6EB32451BBE2B7F9E9613346E" 
entityID="ca.yourAppName.dev"
validUntil="yyyy-mm-ddT00:00:00.000Z">

Services

These services must be included in the metadata:

SingleLogoutService (sign-out)

  • Required
  • Handled at the SingleLogoutService URL in the metadata file
  • Allows the user to logout of the service
  • Incites a federated logout which logs the user out of all authenticated applications
  • We do not require your application to log out on a federated logout that you do not initiate but do require you to return a message to My NS Account noting successful completion
  • Presently there are two Single Logout Bindings supported: SOAP and HTTP-Redirect. Choose one binding for SingleLogoutService and remove the other from the file, before signing

AssertionConsumerService (sign-in)

  • Required
  • Handled at the AssertionConsumerService URL in the metadata file
  • Allows the user to authenticate to a service
  • Leverages single sign on if the user has already authenticated

ChangeNotifyService (change notification)

  • Handled at the ChangeNotifyService URL in the metadata file
  • Informs your application if the user has changed their user information (username, name, email, etc.) in My NS Account
  • Your application is not required to support this service, but it must be included in your metadata file

ManageNameIDService (user revocation notification)

  • Handled at the ManageNameIDService URL in the metadata
  • Informs your application if the user chooses to revoke their access to your application in My NS Account
  • Your application is not required to support this service, but it must be included in your metadata file

NameIDFormat

  • The format of NameIDFormat must be set to "persistent":
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>

Certificates

  • Ensure your metadata includes both signing and encryption certificates
  • Ensure your signing and encryption certs match the correct parameter
<md:KeyDescriptor use="signing"> /* contains the signing certificate */
<md:KeyDescriptor use="encryption"> /* contains the encryption certificate */

General Recommendations

  • Encoding - ensure metadata files are saved in UTF-8 encoding, prior to attempting to sign and validate the metadata file using the Metadata Toolkit
  • Secure service endpoint URLs - ensure your service endpoint URLs are using secure protocol 'https' (communicating over port 443)