SAML 2.0 information

Relevant SAML 2.0 protocol information

Choosing SAML 2.0 bindings

The Connectis Identity Broker supports three different mechanisms, known as bindings, to exchange messages:

  1. Redirect binding: This binding is most suitable for sending SAML Requests from your service to the Connectis Identity Broker. Since there is a maximal message size, it is not suitable for sending SAML Responses back from the Connectis Identity Broker to your service.

  2. POST binding: This binding is suitable for sending SAML Requests from your service to the Connectis Identity Broker, and SAML Responses from the Connectis Identity Broker to your service.

  3. Artifact binding: This binding is suitable for sending any SAML message via a machine-to-machine backchannel. To make this binding work, the service provider and the Connectis Identity Broker must be able to communicate directly. This could mean that firewalls, proxy servers, and/or client certificates need to be configured on your side, which makes setting up and debugging this binding more difficult. We therefore advise against using this binding if possible.

Our recommended setup is that you use Redirect binding to send SAML Requests to the Connectis Identity Broker, and POST binding to receive SAML Responses from the Connectis Identity Broker.

In case you opt for the SAML Artifact binding to receive responses, please be aware that this means that your service will have to be able to autonomously connect to the Connectis Identity Broker via a backchannel, so that it can retrieve the response from the Connectis Identity Broker. A commonly occurring problem is that the service provider’s firewall blocks the outgoing traffic to the Connectis Identity Broker, and hence the service cannot retrieve the response. Please take this into account when troubleshooting your connection to the Connectis Identity Broker via the SAML Artifact binding.

SAML 2.0 metadata

In SAML 2.0, metadata is exchanged between components (service providers, the Connectis Identity Broker, and identity providers) to configure how to connect and exchange messages between them. The metadata basically contains the following information:

  • Which urls to send SAML messages to.

  • Which bindings to use for exchanging messages.

  • Which certificates can be used for checking digital signatures against, to guarantee that the messages come from the appropriate party.

  • What algorithms will be used for calculating digital signatures.

SAML 2.0 metadata is stored as a (signed) XML file in a particular format. You can find the specifications online. The Connectis SAML 2.0 Adapter can automatically create metadata for you, see Connectis SAML 2.0 Adapter. Most SAML 2.0 enabled third party software can automatically generate the metadata as well. If you choose to implement the SAML 2.0 protocol yourself, you may however need to construct metadata by hand.

Example

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
ID="configuration id"
entityID="Entity id">
<ds:Signature>
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference URI="">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> <ds:DigestValue>I+hg07X8GD583Py/OhOI7iSaLbUzL7n9yCgVcpdMSsg=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>base64 signature value</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyName>signing key name</ds:KeyName>
</ds:KeyInfo>
</ds:Signature>
<md:SPSSODescriptor AuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo>
<ds:KeyName>signing certificate key name</ds:KeyName>
<ds:X509Data>
<ds:X509Certificate>signing certificate</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:KeyDescriptor use="encryption">
<ds:KeyInfo>
<ds:KeyName>encryption certificate key name</ds:KeyName>
<ds:X509Data>
<ds:X509Certificate>encryption certificate</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
Location="ARS endpoint"
index="0"
isDefault="true/false"/>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
Location="logout endpoint"/>
<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
Location="login endpoint"
index="1"
isDefault="true/false"/>
</md:SPSSODescriptor>
<md:Organization>
<md:OrganizationName xml:lang="en">Organization name</md:OrganizationName>
<md:OrganizationDisplayName xml:lang="en">Organization display anme</md:OrganizationDisplayName>
<md:OrganizationURL xml:lang="en">Website url</md:OrganizationURL>
</md:Organization>
<md:ContactPerson contactType="administrative">
<md:EmailAddress>support email</md:EmailAddress>
<md:TelephoneNumber>support phone no.</md:TelephoneNumber>
</md:ContactPerson>
</md:EntityDescriptor>

Example of SAML 2.0 messages

Login request

<samlp:AuthnRequest
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
AssertionConsumerServiceURL="url for response"
AttributeConsumingServiceIndex="service index value"
Destination="url of the Connectis Identity Broker"
ForceAuthn="true/false"
ID="message id"
IsPassive="true/false"
IssueInstant="issue instant"
Version="2.0">
<ds:Signature
xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod
Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference
URI="">
<ds:Transforms>
<ds:Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue>
base64 encoded digest value
</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>base64 encoded signature value</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyName>name of the signing key</ds:KeyName>
</ds:KeyInfo>
</ds:Signature>
<saml:Issuer>issuer</saml:Issuer>
<samlp:RequestedAuthnContext
Comparison="minimum">
<saml:AuthnContextClassRef>minimal LOA</saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

Login response

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
IssueInstant="2019-02-04T09:21:26Z" Version="2.0"
Destination="your endpoint"
ID="message id"
InResponseTo="message id of login request">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">issuer</saml:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod
Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference URI="#_0182d143-f204-3584-8a52-3c2aea597d2f">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
<ec:InclusiveNamespaces
xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"
PrefixList="xacml-saml"/>
</ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> <ds:DigestValue>digest value</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>base64 encoded signature value</ds:SignatureValue>
</ds:Signature>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
Version="2.0" ID="assertion id"
IssueInstant="assertion issue instant">
<saml:Issuer>assertion issuer</saml:Issuer>
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
NameQualifier="name qualifier">
</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData
NotOnOrAfter="2019-02-04T09:26:26Z"
InResponseTo="message id of login request"
Recipient="your endpoint">
</saml:SubjectConfirmationData>
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Conditions NotBefore="2019-02-04T09:21:26Z" NotOnOrAfter="2019-02-04T09:26:26Z">
<saml:AudienceRestriction>
<saml:Audience>the idp that responded</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
<saml:AuthnStatement AuthnInstant="2019-02-04T09:21:26Z">
<saml:AuthnContext>
<saml:AuthnContextClassRef>
urn:etoegang:core:assurance-class:loa2
</saml:AuthnContextClassRef>
<saml:AuthenticatingAuthority>
the idp that authenticated the user
</saml:AuthenticatingAuthority>
</saml:AuthnContext>
</saml:AuthnStatement>
</saml:Assertion>
</samlp:Response>

Logout request

<samlp:LogoutRequest
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
IssueInstant="2019-02-04T09:28:54Z"
Version="2.0"
Destination="idp logout endpoint"
ID="message id" >
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod
Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference
URI="">
<ds:Transforms>
<ds:Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue>FMCM4CvxJWw6+3ugte2VTy/V+
P6RnrA0YVd6cMTNr2s=
</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>base64 value of the signature</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyName>name of the key used to sign</ds:KeyName>
</ds:KeyInfo>
</ds:Signature>
<saml:Issuer>issuer</saml:Issuer>
<saml:NameID>id of the user that wants to logout</saml:NameID>
</samlp:LogoutRequest>

Logout response

<samlp:LogoutResponse xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
IssueInstant="2019-02-04T13:16:00Z" Version="2.0"
Destination="your logout endpoint"
ID="message id"
InResponseTo="message id of logout request">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
issuer
</saml:Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
</samlp:LogoutResponse>