Skip to main content
Version: 4.25.x.x LTS

Common aspects of SAML 2.0 AuthStates

The following SAML 2.0 AuthStates use OpenSAML 2.0 and have a common code base:

  • ServiceProviderState ")
  • AssertionRequestState ")
  • IdentityProviderState ").

These AuthStates have several common properties, which are described in the following chapters.

Configuration of input and output bindings

in.binding, out.binding​

SAML 2.0 bindings can be configured separately for input and output and for each type of a SAML message. The following example states that a response may be received in HTTP POST binding only, LogoutRequests may be received in any supported input binding, and all other message types must be received in HTTP redirect binding. All outgoing messages will use HTTP POST, except for LogoutResponse, which will use the same binding as the request message that initiated it.

<property name="in.binding"
 value="Response:http-post LogoutRequest:auto http-redirect" />
<property name="out.binding" value="http-post LogoutResponse:auto" />

Bindings​

The following bindings may be configured:

  • http-post: The HTTP POST binding as defined by the SAML 2.0 specification. This binding is supported for input and output bindings.
  • http-redirect: The HTTP redirect binding as defined by the SAML 2.0 specification. This binding is supported for input and output bindings.
  • http-artifact: The HTTP artifact binding in URL encoding as defined by the SAML 2.0 specification.
  • http-artifact-form: The HTTP artifact binding in POST encoding as defined by the SAML 2.0 specification.
  • internal: This pseudo-binding is used to issue and consume SAML messages without consideration of a specific transport mechanism. The SAML messages are consumed from the property in.internalBindingSource and output is placed to an OutArg variable with the name of the message type, prefixed with saml. (e.g., saml.SAMLResponse, saml.SAMLRequest)
  • internal-assertion: Same as internal binding, but issues and consumes assertions instead of responses. This may be used to handle assertions used in XML protocols such as WS-Security and WS-Federation.
  • http-post-deferred, http-redirect-deferred, http-artifact-deferred, http-artifact-form-deferred: These bindings prepare a HTTP POST, HTTP redirect or a HTTP artifact binding, respectively. However, instead of triggering the transfer, the generated OutArgs are prefixed with nevis.deferred-transfer instead of nevis.transfer, so that the SAML binding is not executed.
  • auto: This may be set to accept all input bindings and to send out responses with the same binding as the initiating requests.
  • none: Configuring this value disables input or output handling for the corresponding message types, for example to have an AuthState ignore incoming and previously consumed SAML messages or to make sure that no outgoing messages are ever generated.

Artifact resolution​

In case of the artifact binding, the SAML message is transmitted from one party to another in two steps: In the first step, a reference to the SAML message, a so-called artifact, is transmitted from party A to party B. In the second step, party B uses the information from the artifact to request the actual SAML message through a web service at party A.

This binding requires that the SAML message issuer caches the message until it is fetched from the other party to allow to fetch the actual SAML message. The following properties must be configured to allow artifact resolution as a server or as a client:

As a server:

  • out.binding http-artifact or http-artifact-form
  • out.artifactSourceId (optional)

As a client:

  • in.binding**http-artifact or http-artifact-form (or alternatively leave it at auto)
  • in.artifact_sources

See chapter for details on the properties.TheIdentity Provider and the Service Provider can both be server or client.

Signatures and signature validation

in.verify, out.sign​

To configure which SAML constructs should be signed and for which constructs valid signatures shall be required, list the message types in the properties in.verify and out.sign. In the following example, Assertions and ArtifactResponses must contain valid signatures to be consumed, and outgoing Responses, Assertions and AuthnRequests will be signed:

<property name="in.verify" value="Assertion ArtifactResponse" />
<property name="out.sign" value="Response Assertion AuthnRequest" />

out.sign.hashAlgorithm​

This parameter can be used to select a hash algorithm different from the default. The default hash algorithm used for SAML signatures in nevisAuth is SHA-1. nevisAuth supports: SHA1, SHA256, SHA384, and SHA512.

in.keystoreref, in.keyobjectref, out.keystore, out.keystoreref​

The credentials used for signature verification and for signing are configured using references to a keystore and a keyobject. For verification, in.keyobjectref may be ommitted if all credentials in the keystore are valid signers. The signer credential will then be searched among all keyobjects of the keystore. This mechanism can detect the correct credential by SKI, IssuerSerial or by direct match of a certificate embedded into the signature.

in.map_issuer_certificate​

In some cases, multiple federation partners are trusted. To make sure that no issuer can pose as another, this property may be activated. If this is the case, the ID of the keyobject used for verification must be identical to the issuer of the consumed message.

out.signatureKeyInfo​

The KeyInfo embedded into a signature informs a validator about the signer credential used. If only one credential is used by both the signer and the validator, no KeyInfo is neccessary. The KeyInfo to add to a signature is configured with the property out.signatureKeyInfo with one or several elements of the following list:

SKI, Certificate, CertificateChain, Subject, IssuerSerial, CRLs, SubjectDNAsKeyName, SubjectCNAsKeyName, KeyNames, EntityID, PublicKey​

The list is whitespace-/comma-separated and case-insensitive. The default value is SKI. Note that only configured fields defined in the signer certificate are actually added to a KeyInfo structure.

Installing multiple certificates to support certificate roll-over​

When certificates expire, they need to be replaced with new, valid certificates. This process is called certificate roll-over. In case of automatic certificate roll-over, the system will use the first valid certificate in the keystore for signature verification. Certificate roll-over scenarios are supported in the nevisAuth configuration.

For implementing roll-over scenarios we recommend using Java keystores as certificate store. In the SAML AuthStates we recommend setting the in.map_issuer_certificate property to true.

Example​

Suppose the following is the KeyStore configuration for a SAML AuthState:

<KeyStore name="IDPTrustStore">
 <KeyObject name="https://my.issuer.ch/saml" certificate="/var/opt/certs/my-issuer-ch.jks" / >
</KeyStore>

Then nevisAuth will perform automatic roll-over, if

  • the AuthState is configured to use this keystore for signature verification (in.keystoreref is set to "IDPTrustStore"),
  • in.map_issuer_certificate is set to true,
  • and a SAML message with issuer https://my.issuer.ch/saml is processed by the AuthState,

Thus, in terms of integration tasks for implementing certificate roll-over, all that is required is to add the new certificate to the appropriate store before the expiration date of the current one.

Encryption and decryption

Symmetric de/encryption​

To configure encryption, list the SAML structures to encrypt in out.encrypt and configure the symmetric key in out.encrypt.key in Base64 encoding. For decryption, configure the symmetric key in the same way in in.decrypt.key. The following example configures symmetric encryption of Assertions and symmetric decryption for all encrypted elements:

<property name="out.encrypt.key"
  value="MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZQo=" />
<property name="out.encrypt"
  value="Assertion" />
<property name="in.decrypt.key"
  value="MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZQo=" />

nevisAuth can encrypt and decrypt Assertions, Attributes and NameIDs. Enrcyption is disabled by default.

out.encrypt.algorithm​

Use out.encrypt.algorithm to configure the URI of the algorithm of the encryption. Algorithm URIs guaranteed to be supported are:

By default, nevisAuth uses AES256 for encryption.

Asymmetric encryption​

In asymmetric encryption, the symmetric key used for the encryption is encoded using the public part of an asymmetric key pair. This allows the exchange of encrypted messages without the need to share secret encryption keys.

out.encrypt.keystoreref, out.encrypt.keyobjectref, out.encryption_key_from_expression, in.encrypt.keystoreref, in.encrypt.keyobjectref​

The credentials used for asymmetric en-/decryption are configured with the properties out.encrypt.keystoreref, out.encrypt.keyobjectref, in.decrypt.keystoreref, and in.decrypt.keyobjectref. As usual, it is possible to omit in.decrypt.keyobjectref for decryption, so that all key objects of that keystore are considered for decryption. The out.encryption_key_from_expression property evaluates the expression as the public key, which can be used for encryption with the IdentityProviderState only. If present, this expression will ignore *out.encrypt.** credentials.

out.encrypt.keyInfo​

For asymmetric encryption, a KeyInfo structure may be generated to indicate the key that was used to encrypt the data. The property out.encrypt.keyInfo configures this generation. Its syntax, options and default are identical to out.signature.keyInfo (described in Signatures and signature validation]. Note that if only one credential is used by both the sender and the receiver, no KeyInfo is neccessary.

Input and output extensions

out.extension.*​

An output extender is a plug-in to a SAML AuthState that adds further structures to generated SAML messages. The syntax to configure an output extender is to declare the name and class of the extender with the property prefix out.extension. and to assign properties to that extender by referencing the declared name. The following example adds aSubjectConfirmation with a Bearer method:

<property name="out.extension.bearerSC"
 value="ch.nevis.esauth.auth.states.saml.extensions.SubjectConfirmationExtender" />
<property name="bearerSC.method" value="bearer" />

The properties configurable depend on the extension class and are listed in the documentation chapters of the AuthStates where they can be applied. You can find the configuration properties for the SubjectConfirmationExtender in chapter IdentityProviderState.

in.extension.*​

Input extenders can be used to extract specific data or to process extended structures that are not part of the SAML 2.0 specification. The configuration syntax is identical to that of output extenders. The implemented input extenders are listed with the AuthStates where they can be used.

Prospect verification

In some situations, an incoming SAML message cannot be verified definitively in one step. For such cases, the verification of particular elements can be loosened. In nevisAuth, this capability is called prospect verification (in the sense that verification is anticipated to be performed at a later stage).

Prospect verification can be configured for particular SAML elements by listing their names in the property in.prospectVerification. The following example relaxes verification of AuthnRequest elements.

<property name="in.verify" value="AuthnRequest" />
<property name="in.prospectVerification" value="AuthnRequest" />

The relaxing of the verification means that no trust validation is done for the signature that is being presented to the SAML AuthState. That is, while the SAML signature is validated as usual, the certificate and the certificate's chain of trust are not validated.

Obviously, this feature is intended only to delay proper verification of the SAML message, not to omit it completely.

Special case: "Prospect verification" of subject confirmation with "Holder of Key" profile​

The prospect verification feature also covers a narrow special case at the service provider side. This special case applies when a service provider consumes an assertion that contains a SubjectConfirmation element with the method "Holder of Key". In that case, first ordinary verification of the SubjectConfirmation as mandated by SAML is performed in any case (checking of not before and not on or after timestamps, recipient, etc.). Then, the certificate data in the SubjectConfirmation's KeyInfo element is compared to the data in the client certificate in the following order:

  1. X509Certificate
  2. X509SKI
  3. X509SubjectName
  4. X509IssuerSerial

If one of these elements is present and there is a match, SubjectConfirmation succeeds. If there is no match, the in.prospectVerification setting comes into play. If the in.prospectVerification property contains SubjectConfirmation, the assertion is accepted (the state is allowed to succeed notwithstanding failing verification).

In any case, if a subject confirmation is verified with the method "Holder of Key", the holder of key info is made available via the notes, for example for further processing in a subsequent AuthState. This happens regardless of whether verification succeeds or not.

Chapter ServiceProviderState lists the outgoing notes with the holder of key information.