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: MUST 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
  • Login service returns RequestUnsupported if this is not one of the specified values.
  • 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; or RequestUnsupported if the value is not in the set.
  • 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
urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:ModStrength::OTP:Mobile:SMS
Comparison (within RequestedAuthnContext)  
  • This AuthnRequest parameter tells the IdP how to present the Service Provider's authentication credential requirement.
  • OASIS SAML V2.0 requirement is: MAY be provided and contain standard specified values EXACT, MINIMUM, MAXIMUM or BETTER - default EXACT.
  • RealMe login service requirement is: SHOULD be provided; SHOULD be EXACT, although MINIMUM is nominally supported for moderate strength - default EXACT
  • Recommendation: use Comparison parameter and set to EXACT.
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 returns RequestUnsupported if this is not provided (and AuthnRequest does not contain AssertionConsumerServiceURL and Protocol Binding).
  • 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.
ForceAuthn
  • This AuthnRequest parameter informs the IdP whether the user must enter their authentication credentials.
  • OASIS SAML V2.0 requirement is: MAY be provided; defaults to FALSE.
  • RealMe login service requirement is: MAY be provided; MUST NOT be set to FALSE; if not specified it will default to TRUE.
  • Login service returns RequestUnsupported if this is set to FALSE.
  • Login service does not support SSO with session management, therefore every AuthnRequest requires re-entry of credentials.
  • Recommendation: do not include ForceAuthn or set to TRUE.
IsPassive
  • This AuthnRequest parameter informs the IdP whether the user can be authenticated without any user interaction.
  • OASIS SAML V2.0 requirement is: MAY be provided; defaults to FALSE.
  • RealMe login service requirement is: MAY be provided; MUST NOT be set to TRUE; if not specified it will default to FALSE.
  • Login service returns NoPassive if this is set to TRUE.
  • Login service does not support SSO with session management, therefore user interaction is always required.
  • Recommendation: do not include IsPassive or set to FALSE.
ProviderName
  • This AuthnRequest parameter is used by RealMe login service to provide Service Provider co-branding in special circumstances.
  • OASIS SAML V2.0 requirement is: MAY be provided.
  • RealMe login service requirement is: MAY be provided.
  • If ProviderName does not match a known Issuer value, RequestUnsupported is returned.
  • Recommendation> do not use ProviderName unless pre-approved prior to integration.
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://realme.govt.nz/sso/SSORedirect/metaAlias/logon-idp"
  ID="a958a20e059c26d1cfb73163b1a6c4f9"                       
  IssueInstant="2012-05-21T00:39:32Z"
  ProviderName="Sample Service Provider"
  Version="2.0">
  <saml:Issuer>https://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:ModStrength 
    </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.
  • OASIS SAML V2.0 requirement is: MAY be provided.
  • RealMe assertion service requirement is: MUST 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
  • Login service returns RequestUnsupported if this is not one of the specified values.
  • 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 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.
  • Recommendation: use one of the following allowed value:
urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:ModStrength
Comparison (within RequestedAuthnContext)  
  • This AuthnRequest parameter tells the IdP how to present the Service Provider's authentication credential requirement.
  • OASIS SAML V2.0 requirement is: MAY be provided and contain standard specified values EXACT, MINIMUM, MAXIMUM or BETTER - default EXACT.
  • RealMe assertion service requirement is: SHOULD NOT be provided; MAY be provided and will be ignored.
  • Recommendation: do not use Comparison parameter and but if present any value will be ignored.
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 returns RequestUnsupported if this is not provided (and AuthnRequest does not contain AssertionConsumerServiceURL and Protocol Binding).
  • 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.
ForceAuthn
  • This AuthnRequest parameter informs the IdP whether the user must enter their authentication credentials.
  • OASIS SAML V2.0 requirement is: MAY be provided; defaults to FALSE.
  • RealMe assertion service requirement is: SHOULD NOT be provided; MAY be provided and will be ignored.
  • Recommendation: do not include ForceAuthn or if provided both TRUE or FALSE will be ignored.
IsPassive
  • This AuthnRequest parameter informs the IdP whether the user can be processed without any user interaction.
  • OASIS SAML V2.0 requirement is: MAY be provided; defaults to FALSE.
  • RealMe assertion service requirement is: MAY be provided; MUST NOT be set to TRUE; if not specified it will default to FALSE.
  • Assertion service returns NoPassive if this is set to TRUE.
  • Assertion service always requires user interaction.
  • Recommendation: do not include IsPassive or set to FALSE.
ProviderName
  • This AuthnRequest parameter is not used by RealMe assertion service.
  • OASIS SAML V2.0 requirement is: MAY be provided.
  • RealMe assertion service requirement is: SHOULD NOT be proviced; MAY be provided and will be ignored.
  • Recommendation> do not use ProviderName. 
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://realme.govt.nz/sso/SSORedirect/metaAlias/assert-idp" 
 ID="a958a20e059c26d1cfb73163b1a6c4f9" 
 IssueInstant="2012-05-21T00:39:32Z" 
 ProviderName="Sample Service Provider" 
 Version="2.0">
 <saml:Issuer>https://www.sample-client.co.nz/onlineservices/service1</saml:Issuer>
 <samlp:NameIDPolicy AllowCreate="true" 
 Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">
 </samlp:NameIDPolicy>
 <samlp:RequestedAuthnContext>
 <saml:AuthnContextClassRef>
 urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:ModStrength
 </saml:AuthnContextClassRef>
 </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>