SAML Messages

Requirements for the SAML 2.0 connection of the Web Application

Issuing the SAML 2.0 AuthnRequest

The following chapter describes the structure of the SAML 2.0 AuthnRequest message. By means of this message, the application requests a SAML token from the eIAM with the information about the user.

Parameter	Definition
Assertion-Consumer-ServiceURL	For RP-PEPs MUST this be fixed and predefined via the metadata of the application. It MUST NOT be supplied in the AuthnRequest. For STS the AssertionConsumerServiceURL MAY be variable. It MUST NOT be predefined via the metadata of the application. If the value is not defined in the metadata, the AssertionConsumerServiceURL MUST be supplied with each AuthnRequest. The AssertionConsumerServiceURL MAY be supplied via the metadata of the application. In this case, it is set as a fixed value in the STS.
Destination	The Destination MUST have the value of the STS WebSSO AuthnRequest Consumer (Single Sign-On URL of the STS). Generally this has the https://<a FQDN>/auth/saml2/sso
IssueInstant	The IssueInstant MUST be set to the exact time when the AuthnRequest is issued.
ProtocolBinding	The ProtocolBinding MUST be "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST".
Issuer	The issuer MUST be a URI. The URI can be a URL in the scope of the issuing web application or a URN from the application's namespace.
Signature	For applications using RP-PEPs the AuthnRequest MUST NOT be signed. For applications using STS the AuthnRequest MUST be signed
Keyinfo	A KeyInfo to identify the key material for checking the SAML 2.0 AuthnRequest MUST be present if the AuthnRequest must be signed.
Conditions	The AuthnRequest MAY contain the element Conditions. However, the validity period of the assertion requested therein is not taken into account by the PEP as IdP for issuing the assertion.

Transmitting the SAML 2.0 AuthnRequest and receiving the response

Requirements for submitting the SAML 2.0 AuthnRequest using Form

Parameter	Definition
Binding	The transmission of the SAML 2.0 AuthnRequest MUST be done in the eIAM using HTTP-POST Binding. "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Destination	The Destination MUST have the value of the eIAM WebSSO AuthnRequest Consumer (SSO URL on the PEP). Example: Destination="https://www.gate.amt.admin.ch/auth/saml2/sso"
RelayState	The application MAY pass the AuthnRequest as a parameter to eIAM by means of the RelayState (return address to which the client is redirected after successful authentication by the application), which the client will return unchanged together with the SAML response. The value in the RelayState MUST be either a URI or a URL on the PEP. For applications outside the Federal Administration networks MUST it be a URI or a URL of the application. If the RelayState parameter is used, it MUST be encoded or encrypted. However, the application may also use a redirect to a fixed address after successfully creating the security context. Example: RelayState: FsWPanuIL9C19QxcpN2Bx4roAJwZiOh8NxcjAozlcQcAwVuAgSMLtKwjPt5Thga4YDeQpgJwshn/Ra3U/F329A== Note: It's important to be aware, that the RelayState is not protected by the Authentication Request signature and therefore needs additional measures on application side to avoid CSRF-attacks

The SAML 2.0 Response

Consuming the SAML 2.0 Response.
The application MUST be able to consume the response by eIAM in the form of a SAML 2.0 Response on the URL specified as the AssertionConsumerService Location. The SAML response contains either a SAML assertion or an error signalling of the SAML 2.0 protocol. In addition, the SAML 2.0 response is signed for integrity reasons. The XML structure of a response looks like this:

Parameter	Definition
ID	Unique identifier of the SAML response
Version	SAML version of the issued response. In eIAM always "2.0"
IssueInstant	Timestamp of the issuance of the SAML Response at the eIAM
Destination	Receiver URL of the SAML Response
Consent	Consent of the user to send the SAML assertion to the service provider. Currently always "unspecified" in eIAM, as this feature is not yet used.
InResponseTo	Identifier of the AuthnRequest of the application to which the eIAM responds with the present response. The application MUST validate that the SAML 2.0 response contains the ID of the previously sent AuthnRequest in the InResponseTo attribute.
xmlns:samlp	Used XML Namespace of the SAML Protocol In eIAM always "urn:oasis:names:tc:SAML:2.0:protocol"
Signature	Signature Information The response signed by the issuer serves as proof that only he could have signed the response. It also serves to guarantee the integrity of the response. It contains the signature technology used, the actual signature of the assertion and the public key of the signature certificate. This is used by the receiving system to identify the key material in its trust store. Note: The application MUST verify the signature. When the verification of the response was not not successful, then the content of the response MUST NOT be used by the application
Issuer	Issuing entity of the SAML 2.0 Response Identifies the entity of eIAM. A URI (can be a URL or a URN) The application MUST validate that the response contains the identifier of the eIAM as Issuer.
saml:Status	Status Code with which the eIAM sends the SAML 2.0 Response to the application. As a rule, any response that is not returned with the status "Success" signals an error. "urn:oasis:names:tc:SAML:2.0:status:Success" The application MUST validate that the response contains the status code "urn:oasis:names:tc:SAML:2.0:status:Success".

Abbreviated example SAML 2.0 Response:

The SAML 2.0 Assertion

The SAML assertion is part of the SAML response. The SAML assertion contains statements about the identity of the user, attributes of the user, and information about how the user was authenticated in the eIAM.

XML Element	Definition
ID	Unique identifier of the SAML assertion.
Version	SAML version of the issued SAML assertion. In eIAM always "2.0"
IssueInstant	Timestamp of the issuance of the SAML assertion by eIAM
xmlns	XML Namespace In eIAM always "urn:oasis:names:tc:SAML:2.0:assertion"
Issuer	Issuing entity of the SAML 2.0 response Identifies the entity of eIAM eIAM usually uses application specific issuers like "urn:eiam.admin.ch:pep:test-application"
ds:Signature	Contains information relevant to the digital signature of the SAML assertion.
ds:SignatureValue	The value of the digital signature calculated by the SAML assertion using the private key of the key pair of the as-sertion signer certificate.
KeyInfo	Contains information about the public key to be used for signature verification. For eIAM this is always the X509 certificate;
Subject	Contains information about the subject (accessing user).
Subject.NameID Format Subject.NameID	eIAM sets the format of the NameID to the value "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent". If the Relying Party is a specialised application of a specialised office, eIAM sets the NameID to the userExtId of the accessing user in the access client (office client). If the application is a dedicated application for a Federal Office, then the value of Subject.NameID will be the users ExtID of the access client. If this the application is used across Federal Offices, then the Subject.NameID will be the users loginId in the root client. The Relying Party SHOULD use the NameID value from the Subject to map the user in the application.
SubjectConfirmation Method	Method by which the eIAM confirms the determined subject to the application. In eIAM always "urn:oasis:names:tc:SAML:2.0:cm:bearer"
SubjectConfirmationData InResponseTo	Reference to the ID of the SAML AuthnRequest of the application to which this subject is confirmed.
SubjectConfirmationData NotOnOrAfter	Time stamp until when the confirmation of eIAM about the statements of the subject is valid.
SubjectConfirmationData Recipient	URL of the entity for which this confirmation of eIAM was issued.
Conditions	Defines conditions that the service provider MUST check to determine if it may consider the assertion valid.
Conditions NotBefore	Time stamp for the earliest time at which the SAML assertion may be validated as valid by the service provider. If this time has not yet been reached in this time stamp, the service provider MUST consider the SAML assertion invalid.
Conditions NotOnOrAfter	Time stamp for the latest time at which the SAML assertion may be validated as valid by the service provider. A SAML assertion that is older MUST be considered invalid by the service provider.
AudienceRestriction	Contains information about the group of recipients who are allowed to use this SAML assertion.
AudienceRestriction Audience	Entity(ies) that may use this SAML assertion. eIAM usually uses application specific issuers like "urn:eiam.admin.ch:pep:test-application". The application MUST check if it belongs to the audience of the SAML assertion. If it is not, it MUST consider the SAML assertion invalid.