RealMe request parameters

In general, it can be expected that SAML v2.0 products and libraries conform with the mandatory requirements of the OASIS SAML v2.0 standard(external link). The New Zealand Security Assertion and Messaging Standard (NZSAMS) was published in 2008, and although this is occasionally still referenced, it is not directly useful for the purpose of integrating with the RealMe® services.

The RealMe Login Service Messaging Specification and the RealMe Assertion Service Messaging Specification, however, specify a narrower and more prescriptive set of requirements. There are aspects of SAML v2.0 interoperability that the OASIS SAML v2.0 standard does not specify, and the RealMe specification documents address this by defining the use of parameters and values that apply in the RealMe context. 

For purposes of procurement or new SAML component development, agencies should refer to the RealMe documents which should simplify the determination of specific requirements in the New Zealand context.

As the majority of integrations use products or code libraries that comply with the OASIS SAML v2.0 standard, developers should focus on the RealMe requirements that differ in some way from the OASIS Standard or have additional NZ specific constraints.

Refer to the following list of the key RealMe SAML message request parameters that are discussed and ordered to highlight the ones that are most likely to need close attention.

RealMe SAML request parameters

Issuer
  • This AuthnRequest parameter tells the IdP which Service Provider has sent the AuthnRequest.
  • OASIS SAML V2.0 requirement is: MUST be provided.
  • RealMe login service requirement is: MUST be provided.
  • Login service displays an error page if the Issuer is not recognised.
  • The value of the Issuer element SHOULD conform to this recommended three part format:
         https://www.agencyname.govt.nz/context/application-name
https://www.example.govt.nz/customerservices/first-application
  • It should be noted that the Issuer element:
         is a name, not a URL, and is not resolved
         does not need to be the same as the website domain 
         is exactly the same as the EntityID value supplied in the metadata
  • The first two parts are the "privacy domain", and the third part is a short name for the website application.
  • Recommendation: use this standard format unless this is not supported by your SAML component.
AllowCreate (within NameIDPolicy)
  • This AuthnRequest parameter informs the IdP whether the user is in the returning user process and must have previously completed the agency's registration process.
  • OASIS SAML V2.0 requirement is: MAY be provided; defaults to FALSE.
  • RealMe login service requirement is: MUST be provided.
  • Login service returns UnknownPrincipal if this is set to FALSE and there is no matching FLT for the requesting Service Provider for the user's login.
  • Recommendation: use AllowCreate and set to TRUE, unless there are distinct business processes for first time user and returning user.
Format (within NameIDPolicy)
  • This AuthnRequest parameter indicates the nameID format to the IdP. RealMe login service always returns persistent nameIDs.
  • OASIS SAML V2.0 requirement is: MAY be provided.
  • RealMe login service requirement is: MAY be provided. Value SHOULD be persistent, but unspecified allows the IdP to decide.
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  • Recommendation: use NameID format persistent.
RequestedAuthnContextClassRef (within RequestedAuthnContext)  
  • This AuthnRequest parameter tells the IdP which types of authentication credentials are required by the Service Provider.
  • OASIS SAML V2.0 requirement is: MUST be provided (or AuthnContextDeclRef), and contain standard specified values.
  • RealMe login service requirement is: MUST be provided; MUST contain an allowed value (custom list for RealMe login).
  • Login service returns NoAuthnContext if this is not provided; there is no specific error handling currently for RequestUnsupported 
  • Recommendation: use one of the following allowed values:
urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:LowStrength
urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:ModStrength
urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:ModStrength::OTP:Token:SID
AssertionConsumerServiceIndex
  • This AuthnRequest parameter indirectly informs the IdP where to return the AuthnResponse according to the corresponding values in the Service Provider's metadata.
  • OASIS SAML V2.0 requirement is: MAY be provided; 
  • RealMe login service requirement is: SHOULD be provided.
  • Login service will use the default value provided in the SP Metadata if this is not provided (and AuthnRequest does not contain AssertionConsumerServiceURL and Protocol Binding). Note: will use ACS where default = True (regardless of index) otherwise index = 0.
  • Normal login service configuration requires this information to be set at integration rather than use of instructions in each AuthnRequest.
  • Recommendation: use AssertionConsumerServiceIndex unless this is not supported by your SAML component.
Protocol Binding and AssertionConsumerServiceURL
  • These AuthnRequest parameter directly informs the IdP where to return the AuthnResponse.
  • OASIS SAML V2.0 requirement is: MAY be provided; 
  • RealMe login service requirement is: SHOULD NOT be provided.
  • Normal login service configuration requires this parameter to be set at integration rather than use of instructions in each AuthnRequest.
  • Recommendation: use AssertionConsumerServiceIndex unless this is not supported by your SAML component.
RelayState
  • This AuthnRequest parameter may be provided for private use by the Service Provider to maintain the session state.
  • OASIS SAML V2.0 requirement is: MAY be provided. MUST NOT exceed 80 bytes in length and SHOULD be integrity protected by the Service Provider.
  • RealMe login service requirement is: MAY be provided and will be ignored.
  • Recommendation: Can use to meet service provider specific requirements. 
Example Authentication Request
<samlp:AuthnRequest xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
 xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
 AssertionConsumerServiceIndex="0"
 Destination="https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_MTSLoginService/samlp/sso/login"
 ID="a958a20e059c26d1cfb73163b1a6c4f9"                     
 IssueInstant="2021-05-21T00:39:32Z"
 Version="2.0">
 <saml:Issuer>www.sample-client.co.nz/onlineservices/service1</saml:Issuer>
 <samlp:NameIDPolicy AllowCreate="true"
Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
 </samlp:NameIDPolicy>
 <samlp:RequestedAuthnContext> 
<saml:AuthnContextClassRef>urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:LowStrength
</saml:AuthnContextClassRef>
 </samlp:RequestedAuthnContext>
 </samlp:AuthnRequest>
Issuer
  • This AuthnRequest parameter tells the IdP which Service Provider has sent the AuthnRequest.
  • OASIS SAML V2.0 requirement is: MUST be provided.
  • RealMe assertion service requirement is: MUST be provided.
  • Assertion service displays an error page if the Issuer is not recognised.
  • The value of the Issuer element SHOULD conform to this recommended three part format:
         https://www.agencyname.govt.nz/context/application-name
https://www.example.govt.nz/customerservices/first-application
  • It should be noted that the Issuer element:
         is a name, not a URL, and is not resolved
         does not need to be the same as the website domain 
         is exactly the same as the EntityID value supplied in the metadata
  • The first two parts are the "privacy domain", and the third part is a short name for the website application.
  • Recommendation: use this standard format unless this is not supported by your SAML component.
AllowCreate (within NameIDPolicy)
  • This AuthnRequest parameter informs the IdP whether the user is in the returning user process and must have previously completed the agency's registration process.
  • OASIS SAML V2.0 requirement is: MAY be provided; defaults to FALSE.
  • RealMe assertion service requirement is: MAY be provided, but typically SHOULD NOT be provided.
  • Recommendation: do not use AllowCreate, but if present it will be ignored whether set to TRUE or FALSE.
Format (within NameIDPolicy)
  • This AuthnRequest parameter indicates the nameID format to the IdP. RealMe assertion service always returns transient nameIDs in the assertion. RealMe assert then login service always returns persistent nameIDs in the assertion.
  • OASIS SAML V2.0 requirement is: MAY be provided.
  • RealMe assertion service requirement is: MAY be provided. Value SHOULD be transient, but unspecified allows the IdP to decide.
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  • Recommendation: use NameID format transient.
RequestedAuthnContextClassRef (within RequestedAuthnContext)  
  • This AuthnRequest parameter tells the IdP which types of authentication credentials are required by the Service Provider.
  • OASIS SAML V2.0 requirement is: MUST be provided (or AuthnContextDeclRef), and contain standard specified values.
  • RealMe assertion service requirement is: MUST be provided; MUST contain an allowed value (currently only ModStrength for assertion).
  • Assertion service returns NoAuthnContext if this is not provided; or RequestUnsupported if the value is not in the set. NOTE there is no specific error handling currently for RequestUnsupported.
  • Recommendation: use one of the following allowed value:
urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:ModStrength
AssertionConsumerServiceIndex
  • This AuthnRequest parameter indirectly informs the IdP where to return the AuthnResponse according to the corresponding values in the Service Provider's metadata.
  • OASIS SAML V2.0 requirement is: MAY be provided; 
  • RealMe assertion service requirement is: SHOULD be provided.
  • Assertion service will use the default value provided in the SP metadata if this is not provided (and AuthnRequest does not contain AssertionConsumerServiceURL and Protocol Binding). NOTE: will use ACS where default = true (regardless of index) otherwise index = 0.
  • Normal assertion service configuration requires this information to be set at integration rather than use of instructions in each AuthnRequest.
  • Recommendation: use AssertionConsumerServiceIndex unless this is not supported by your SAML component.
Protocol Binding and AssertionConsumerServiceURL
  • These AuthnRequest parameter directly informs the IdP where to return the AuthnResponse.
  • OASIS SAML V2.0 requirement is: MAY be provided; 
  • RealMe assertion service requirement is: SHOULD NOT be provided.
  • Normal assertion service configuration requires this parameter to be set at integration rather than use of instructions in each AuthnRequest.
  • Recommendation: use AssertionConsumerServiceIndex unless this is not supported by your SAML component.
RelayState
  • This AuthnRequest parameter may be provided for private use by the Service Provider to maintain the session state.
  • OASIS SAML V2.0 requirement is: MAY be provided. MUST NOT exceed 80 bytes in length and SHOULD be integrity protected by the Service Provider.
  • RealMe assertion service requirement is: MAY be provided and will be ignored.
  • Recommendation: Can use to meet service provider specific requirements. 
Example Assertion Request
<samlp:AuthnRequest xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
 xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
 AssertionConsumerServiceIndex="0"
 Destination="https://mts.login.realme.govt.nz/4af8e0e0-497b-4f52-805c-00fa09b50c16/B2C_1A_DIA_RealMe_MTSLoginService/samlp/sso/login"
 ID="a958a20e059c26d1cfb73163b1a6c4f9"                     
 IssueInstant="2021-05-21T00:39:32Z"
 Version="2.0">
 <saml:Issuer>www.sample-client.co.nz/onlineservices/service1</saml:Issuer>
 <samlp:NameIDPolicy AllowCreate="true"
Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
 </samlp:NameIDPolicy>
 <samlp:RequestedAuthnContext> 
<saml:AuthnContextClassRef>urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:LowStrength
</saml:AuthnContextClassRef>
 </samlp:RequestedAuthnContext>
 </samlp:AuthnRequest>