SAML Meldungen

Anforderungen an die SAML 2.0 Anbindung der Webapplikation

Ausstellen des SAML 2.0 AuthnRequest

Das folgende Kapitel beschreibt den Aufbau der SAML 2.0 AuthnRequest Meldung. Mittels dieser Meldung fordert die Applikation vom eIAM ein SAML Token mit den Angaben über den Benutzer an.

Parameter	Definition
Assertion-Consumer-ServiceURL	Für RP_PEPs MUSS diese fix und über die Metadaten der Applikation vordefiniert sein. Sie MUSS NICHT im AuthnRequest mitgeliefert werden. Für STS KANN die AssertionConsumerServiceURL variabel sein. Sie MUSS NICHT über die Metadaten der Applikation vordefiniert sein. Ist der Wert nicht in den Metadaten definiert, so MUSS die AssertionConsumerServiceURL mit jedem AuthnRequest mitgeliefert werden. Die AssertionConsumerServiceURL KANN über die Metadaten der Applikation geliefert werden. In diesem Fall wird diese im STS fix gesetzt.
Destination	Die Destination MUSS den Wert des STS WebSSO AuthnRequest Consumers haben (Single Sign-On URL des STS) Im Allgemeinen hat dies den https://<a FQDN>/auth/saml2/sso
IssueInstant	Der IssueInstant MUSS auf den exakten Zeitpunkt, an dem der AuthnRequest ausgestellt wird, gesetzt sein.
ProtocolBinding	Als ProtocolBinding MUSS „urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST“ verwendet werden.
Issuer	Der Issuer MUSS ein URI sein. Der URI kann ein URL im Bereich der ausstellenden Webapplikation sein oder ein URN aus dem Namespace der Applikation.
Signature	Für Anwendungen, die RP-PEPs verwenden, darf die AuthnRequest NICHT signiert werden. Für Anwendungen, die STS verwenden, MUSS die AuthnRequest signiert sein.
KeyInfo	Eine KeyInfo zur Identifikation des Keymaterials zur Prüfung des SAML 2.0 AuthnRequest MUSS zwingend vorhanden sein, wenn der AuthnRequest signiert werden muss.
Conditions	Der AuthnRequest KANN das Element Conditions enthalten. Die darin angeforderte Gültigkeitsdauer der Assertion wird vom PEP als IdP jedoch nicht berücksichtigt für die Ausstellung der Assertion.

Übermittlung des SAML 2.0 AuthnRequest und Empfang der Response

Anforderungen an die Übermittlung des SAML 2.0 AuthnRequest mittels Form

Parameter	Definition
Binding	Die Übermittlung des SAML 2.0 AuthnRequest MUSS im eIAM mittels HTTP-POST Binding geschehen. „urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST“
Destination	Die Destination MUSS den Wert des eIAM WebSSO AuthnRequest Consumers haben (SSO URL auf dem PEP). Beispiel: Destination="https://www.gate.amt.admin.ch/auth/saml2/sso"
RelayState	Die Applikation KANN als Parameter mit dem AuthnRequest an eIAM mittels RelayState (Rücksprungadresse, an welche der Client nach erfolgter Authentifizierung durch die Applikation redirektet wird) übergeben, den dieser unverändert zusammen mit der SAML Response retournieren wird. Der Wert im RelayState MUSS entweder eine URI oder eine URL auf dem PEP sein. Bei Applikationen ausserhalb der Netze der Bundesverwaltung MUSS es ein URI oder ein URL der Applikation sein. Wird der RelayState Parameter verwendet, so MUSS der Parameter encoded oder verschlüsselt sein. Die Applikation kann jedoch auch nach dem erfolgreichen Erstellen des Security Kontext einen Redirect auf eine fixe Adresse verwenden. Beispiel: RelayState: FsWPanuIL9C19QxcpN2Bx4roAJwZiOh8NxcjAozlcQcAwVuAgSMLtKwjPt5Thga4YDeQpgJwshn/Ra3U/F329A== Bemerkung: Es ist wichtig zu wissen, dass der RelayState nicht durch die Authentication Request-Signatur geschützt ist und daher zusätzliche Maßnahmen auf der Anwendungsseite erforderlich sind, um CSRF-Angriffe zu vermeiden.

Die SAML 2.0 Response

Konsumieren der SAML 2.0 Response
Die Applikation MUSS die Antwort von eIAM in Form einer SAML 2.0 Response auf der als AssertionConsumerService Location angegebenen URL konsumieren können. Die SAML Response enthält entweder eine SAML Assertion oder eine Fehler Signalisation des SAML 2.0 Protokolls. Zudem wird die SAML 2.0 Response, aus Gründen der Integrität, signiert übermittelt. Das XML Gerüst einer Response sieht folgendermassen aus:

Parameter	Definition
ID	Einmaliger Identifikator der SAML Response
Version	SAML Version der ausgestellten Response. Im eIAM immer "2.0"
IssueInstant	Zeitstempel der Ausstellung der SAML Response auf dem eIAM
Destination	Empfänger URL der SAML Response
Consent	Einverständnis des Benutzers zum Senden der SAML Assertion an den Service Provider. Aktuell im eIAM immer „unspecified“, da dieses Feature noch nicht verwendet wird.
InResponseTo	Identifikator des AuthnRequest der Applikation auf welchen eIAM mit der vorliegenden Response antwortet. Die Applikation MUSS validieren, dass die SAML 2.0 Response im InResponseTo Attribut die ID des zuvor versandten AuthnRequest enthält.
xmlns:samlp	Verwendeter XML Namespace des SAML Protokolls Im eIAM immer "urn:oasis:names:tc:SAML:2.0:protocol"
Signature	Signatur Informationen Die vom Aussteller signierte Response dient als Beweis dafür, dass nur er die Response signiert haben kann. Und auch dazu, die Integrität der Response zu garantieren. Sie beinhaltet die verwendete Signatur Technologie, die eigentliche Signatur der Assertion sowie den public Key des Signaturzertifikats. Dieser dient dem empfangenden System zur Identifizierung des Schlüsselmaterials in ihrem Truststore. Bemerkung: Die Anwendung MUSS die Signatur überprüfen. Wenn die Überprüfung der Antwort nicht erfolgreich war, dann MUSS der Inhalt der Antwort von der Anwendung nicht verwendet werden.
Issuer	Ausgebende Stelle der SAML 2.0 Response Identifiziert die Entität des eIAM Ein URI (kann ein URL oder ein URN sein) Die Applikation MUSS validieren, dass die Response als Issuer den Identifier des eIAM enthält.
samlp:Status	Status Code mit welchem eIAM die SAML 2.0 Response an die Applikation schickt. In der Regel signalisiert jede Response ein Fehler, die nicht mit dem Status „Success“ zurückgegeben wird. "urn:oasis:names:tc:SAML:2.0:status:Success" Die Applikation MUSS validieren, dass die Response den Status Code „urn:oasis:names:tc:SAML:2.0:status:Success“ enthält.

Gekürztes Beispiel SAML 2.0 Response:

Die SAML 2.0 Assertion

Die SAML Assertion ist Teil der SAML Response. Die SAML Assertion enthält Aussagen über die Identität des Benutzers, Attribute des Benutzers und Informationen darüber, wie die Authentifizierung des Benutzers im eIAM durchgeführt wurde.

XML Element	Definition
ID	Einmaliger Identifikator der SAML Assertion.
Version	SAML Version der ausgestellten SAML Assertion. Im eIAM immer "2.0"
IssueInstant	Zeitstempel der Ausstellung der SAML Assertion von eIAM
xmlns	XML Namespace Im eIAM immer "urn:oasis:names:tc:SAML:2.0:assertion"
Issuer	Ausgebende Stelle der SAML 2.0 Response Identifiziert die Entität des eIAM eIAM verwendet in der Regel anwendungsspezifische Issuer wie "urn:eiam.admin.ch:pep:test-application".
ds:Signature	Enthält für die digitale Signatur der SAML Assertion relevante Angaben.
ds:SignatureValue	Der Wert der digitalen Signatur, welcher über die SAML Assertion unter Verwendung des Private-Keys des Schlüsselpaars des Assertion Signer Zertifikats errechnet wurde.
KeyInfo	Enthält Informationen über den Public-Key, der für die Prüfung der Signatur verwendet werden soll. Ist bei eIAM immer das X509 Zertifikat
Subject	Enthält Informationen über das Subjekt (zugreifender Benutzer).
Subject.NameID Format Subject.NameID	eIAM setzt das Format der NameID auf den Wert „urn:oasis:names:tc:SAML:2.0:nameid-format:persistent“. Ist die Relying Party eine Fachapplikationen eines Fachamtes, wird NameID von eIAM auf die userExtId des zugreifenden Benutzers im Access Mandant (Amtsmandant) gesetzt. Handelt es sich bei der Anwendung um eine spezielle Anwendung für ein Bundesamt, dann ist der Wert von Subject.NameID die ExtID des Benutzers im Zugriffs-Client. Wird die Anwendung in mehreren Bundesämtern verwendet, entspricht die Subject.NameID der LoginId des Benutzers im Root-Client. Die Relying Party SOLL den NameID Wert aus dem Subject verwenden, um den Benutzer in der Applikation zu mappen.
SubjectConfirmation Method	Methode, über welche eIAM der Applikation das ermittelte Subjekt bestätigt. Im eIAM immer "urn:oasis:names:tc:SAML:2.0:cm:bearer"
SubjectConfirmationData InResponseTo	Referenz auf die ID des SAML AuthnRequest der Applikation, auf welche dieses Subject bestätigt wird.
SubjectConfirmationData NotOnOrAfter	Zeit Stempel bis wann die Bestätigung des eIAM über die Aussagen des Subjekts Gültigkeit hat.
SubjectConfirmationData Recipient	Empfänger URL der Entität für welche diese Bestätigung vom eIAM ausgestellt wurde.
Conditions	Definiert Bedingungen, welche der Service Provider prüfen MUSS um festzustellen, ob er die Assertion als gültig ansehen darf.
Conditions NotBefore	Zeit Stempel für den Zeitpunkt, ab welchem die SAML Assertion frühestens vom Service Provider als gültig validiert werden darf. Ist dieser Zeitpunkt in diesem Zeit Stempel noch nicht erreicht, so MUSS der Service Provider die SAML Assertion als ungültig ansehen.
Conditions NotOnOrAfter	Zeit Stempel für den Zeitpunkt, ab welchem die SAML Assertion spätestens vom Service Provider als gültig validiert werden darf. Eine SAML Assertion die älter ist, MUSS vom Service Provider als ungültig angesehen werden.
AudienceRestriction	Enthält Informationen über den Kreis der Empfänger, welche diese SAML Assertion verwenden dürfen.
AudienceRestriction Audience	Entität(en) welche diese SAML Assertion verwenden dürfen. Ein URI. Kann ein URL oder ein URN sein. Die Applikation MUSS prüfen, ob sie zum Empfängerkreis der SAML Assertion gehört. Ist dies nicht der Fall, so MUSS sie die SAML Assertion als ungültig ansehen.