IAM plugin documentation

SAML Access Cookie Identity Propagator

Description

An identity propagator that authenticates against another web application using a SAML 2.0 assertion and obtains one or more cookies and uses them for identity propagation.

This plugin performs a HTTP POST request with a SAML 2.0 assertion to an application and expects this application to set one or more access cookies. Those cookies are then added to the current response.

Type name

SamlAccessCookieIdentityPropagator

Class

com.airlock.iam.saml2.application.configuration.SamlAccessCookieIdentityPropagator

May be used by

Conditional Identity Propagator Authenticator-based One-Shot Target Application Chaining Identity Propagator

Properties

Access Cookie Source URL (accessCookieSourceUrl)

Description

The full URL of the application that provides the access cookies. A POST request is sent to this URL containing a SAML assertion.

Attributes

String

Mandatory

Example

http://someapp.somehost.com/auth/login

Example

https://securehost.com/login.php

HTTP Parameter SAML (httpParamSaml)

Description

The name of the HTTP parameter for the SAML assertion.

Attributes

String

Mandatory

Example

saml

Example

assertion

HTTP Parameters (httpParams)

Description

List of fixed (statically defined) HTTP parameters that are sent with the request when obtaining an access cookie.

In many cases, the submit button value must be sent to an application to make it think that the button has been pressed.

Attributes

Plugin-List

Optional

Assignable plugins

HTTP Parameter

Allow Only Trusted Certs (allowOnlyTrustedCerts)

Description

Only allow connections to servers whose certificate is trusted. See documentation of property "Trust Store Path" for more information about what certificates are trusted.

Security warning: Trusting all certificates allows connections to adversarial hosts. Only disable this property for testing and integration setups.

Attributes

Boolean

Optional

Default value

true

Verify Server Hostname (verifyServerHostname)

Description

Enables hostname verification, i.e. the actual hostname must be the same as in the server certificate.

Security warning: Not verifying the hostname may allow connections to adversarial hosts, e.g. if they employ DNS spoofing. Only disable this property for testing and integration setups.

Attributes

Boolean

Optional

Default value

true

Trust Store Path (trustStorePath)

Description

Keystore file name containing trusted certificate issuers (and trusted certificates).

If this property is not defined the following certificate issuers are trusted:

The list of issuers known to the Java VM if the system property "javax.net.ssl.trustStore" is not defined.
The list of issuers in a keystore referenced by system property "javax.net.ssl.trustStore" if defined in instance.properties using iam.java.opts

If this property is defined then the following certificate issuers are trusted:

The list of issuers in the referenced truststore file and no others.

This property is only relevant if the property "Allow Only Trusted Certs" is enabled.

Attributes

File/Path

Optional

Trust Store Type (trustStoreType)

Description

Identifies the type of the keystore.

Attributes

String

Optional

Default value

JKS

Allowed values

JKS, PKCS12

Trust Store Password (trustStorePassword)

Description

The password used verify the authenticity of the trust store.

Depending on the keystore type, leaving this property empty (or undefined) has a different effect:

In keystores like JKS, the keystore can be opened and used but the integrity of the keystore is not checked.
In keystores like PKCS12, the keystore cannot be opened an an error occurs.

Attributes

String

Optional

Sensitive

Connect/Read Timeout [s] (connectTimeout)

Description

The connection and read timeout in seconds. A timeout value of zero is interpreted as 60 seconds.

Attributes

Integer

Optional

Default value

Correlation ID Header Name (correlationIdHeaderName)

Description

When configured, all requests sent contain a header with the correlation ID with the configured name. If no value or an empty value is specified, the correlation ID header is not sent.

If the correlation ID is not defined, the correlation ID header is not included in sent requests.

Attributes

String

Optional

Validation RegEx: [a-zA-Z0-9_-]+

Suggested values

X-Correlation-ID

Proxy Host (proxyHost)

Description

The hostname of the HTTP proxy server (if any).

Attributes

String

Optional

Example

proxy.company.com

Proxy Port (proxyPort)

Description

The port of the HTTP proxy server (if any).

Attributes

Integer

Optional

Proxy Login User (proxyLoginUser)

Description

Username for the HTTP proxy if proxy authentication is used.

Attributes

String

Optional

Proxy Login Password (proxyLoginPassword)

Description

Password for the HTTP proxy if proxy authentication is used.

Attributes

String

Optional

Sensitive

Cookies (cookies)

Description

A list of cookies to expect and send back to the client.

Attributes

Plugin-List

Mandatory

Assignable plugins

Cookie Mapping

Issuer (issuer)

Description

The Issuer set in the SAML2 Assertion.

Attributes

String

Mandatory

Example

AirlockIAM

Example

AirlockIdp

Subject Template (subjectTemplate)

Description

The template used to insert the user's ID in the Subject element of the Assertion. The string "${userId}" gets replaced by the user's name.

Attributes

String

Optional

Default value

${userId}

Example

${userId}

Example

User_${userId}

Subject Confirmation Method (subjectConfirmationMethod)

Description

The subject confirmation method to use in the assertion.

Attributes

String

Optional

Default value

urn:oasis:names:tc:SAML:2.0:cm:sender-vouches

Suggested values

urn:oasis:names:tc:SAML:2.0:cm:sender-vouches, urn:oasis:names:tc:SAML:2.0:cm:bearer, urn:oasis:names:tc:SAML:2.0:cm:holder-of-key

Name Id Format (nameIdFormat)

Description

The NameID Format to use in the assertion.

Attributes

String

Optional

Default value

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Suggested values

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, urn:oasis:names:tc:SAML:2.0:nameid-format:transient

Sp Provided Id (spProvidedId)

Description

The SPProvidedId is an attribute of the NameID tag and refers to the actual name that was provided at authentication. If set, this attribute will be added to the assertion. The name of the attribute does not matter. Use @param:PROVIDED_USERNAME as "value" to refer to the username as provided by the user.

Attributes

Plugin-Link

Optional

Assignable plugins

Assertion Attribute

Attributes (attributes)

Description

Defines a list of attributes to be added to the issued assertion. The value of the attribute can either be statically configured or taken from the user.

Attributes

Plugin-List

Optional

Assignable plugins

Assertion Attribute

Assertion Validity Millis (assertionValidityMillis)

Description

The Assertion Validity time in milliseconds. This sets the NotOnOrAfter attribute to the specified instant in the future.

Attributes

Integer

Optional

Default value

30000

Assertion Not Before Skew Millis (assertionNotBeforeSkewMillis)

Description

The maximum number of milliseconds the clocks on the involved parties are allowed to be different. This sets the NotBefore attribute in the SAML assertion to the current time minus the specified number of milliseconds.

Attributes

Integer

Optional

Default value

5000

Xml Signature Algorithm (xmlSignatureAlgorithm)

Description

XML signature algorithm. Used for SAML XML signature generation.
The (deprecated) value "SHA1 (automatic RSA/DSA)" automatically chooses "http://www.w3.org/2000/09/xmldsig#rsa-sha1" or "http://www.w3.org/2000/09/xmldsig#dsa-sha1" depending on the type of the key found in the keystore. However please use a more secure hash instead, as SHA-1 is not considered to be secure.

Attributes

String

Optional

Default value

http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

Allowed values

http://www.w3.org/2001/04/xmldsig-more#rsa-sha512, http://www.w3.org/2001/04/xmldsig-more#rsa-sha384, http://www.w3.org/2001/04/xmldsig-more#rsa-sha256, http://www.w3.org/2000/09/xmldsig#rsa-sha1, http://www.w3.org/2000/09/xmldsig#dsa-sha1, http://www.w3.org/2000/09/xmldsig#hmac-sha1, http://www.w3.org/2001/04/xmldsig-more#rsa-ripemd160, http://www.w3.org/2001/04/xmldsig-more#rsa-md5, http://www.w3.org/2001/04/xmldsig-more#hmac-md5, http://www.w3.org/2001/04/xmldsig-more#hmac-ripemd160, http://www.w3.org/2001/04/xmldsig-more#hmac-sha256, http://www.w3.org/2001/04/xmldsig-more#hmac-sha384, http://www.w3.org/2001/04/xmldsig-more#hmac-sha512, SHA1 (automatic RSA/DSA)

Xml Signature Digest Method (xmlSignatureDigestMethod)

Description

XML signature digest method. Used for SAML XML signature generation and verification.

Attributes

String

Optional

Default value

http://www.w3.org/2001/04/xmlenc#sha256

Allowed values

http://www.w3.org/2001/04/xmlenc#sha512, http://www.w3.org/2001/04/xmlenc#sha256, http://www.w3.org/2000/09/xmldsig#sha1, http://www.w3.org/2001/04/xmlenc#ripemd160

Keystore File (keystoreFile)

Description

JKS Keystore file name containing the certificate and key used to sign the SAML2 Assertion.

Attributes

File/Path

Mandatory

Keystore Password (keystorePassword)

Description

The password used open the keystore.

Attributes

String

Mandatory

Sensitive

Signing Key Alias (signingKeyAlias)

Description

The alias of the key used to sign the Assertion.

Attributes

String

Mandatory

Example

medusaCert

Signing Key Password (signingKeyPassword)

Description

The password used to retrieve the key from the keystore. This password can be the same as the keystore password.

Attributes

String

Mandatory

Sensitive

Audience Restrictions (audienceRestrictions)

Description

If set, adds the given audiences to an AudienceRestriction element. This is usually not required. Each element of this list is included in the AudienceRestriction as a separate Audience.

e.g. If this list contains the Strings: {"https://1.airlock.com","https://2.airlock.com"} the resulting condition contains:


 
<saml:Conditions ...>
 
 <saml:AudienceRestriction>
 
 <saml:Audience>https://1.airlock.com</saml:Audience>
 
 <saml:Audience>https://2.airlock.com</saml:Audience>
 
 </saml:AudienceRestriction>
 
</saml:Conditions>

Attributes

String-List

Optional

Enable Subject Confirmation (enableSubjectConfirmation)

Description

If enabled, a SubjectConfirmation element is added to the Assertion. This should only be disabled if the receiver doesn't support this element.

Attributes

Boolean

Optional

Default value

true

Enable Authn Statement (enableAuthnStatement)

Description

If enabled, an AuthnStatement element is added to the Assertion. This should only be disabled if the receiver doesn't support this element.

Attributes

Boolean

Optional

Default value

true

YAML Template (with default values)


type: SamlAccessCookieIdentityPropagator
id: SamlAccessCookieIdentityPropagator-xxxxxx
displayName: 
comment: 
properties:
  accessCookieSourceUrl:
  allowOnlyTrustedCerts: true
  assertionNotBeforeSkewMillis: 5000
  assertionValidityMillis: 30000
  attributes:
  audienceRestrictions:
  connectTimeout: 10
  cookies:
  correlationIdHeaderName:
  enableAuthnStatement: true
  enableSubjectConfirmation: true
  httpParamSaml:
  httpParams:
  issuer:
  keystoreFile:
  keystorePassword:
  nameIdFormat: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  proxyHost:
  proxyLoginPassword:
  proxyLoginUser:
  proxyPort:
  signingKeyAlias:
  signingKeyPassword:
  spProvidedId:
  subjectConfirmationMethod: urn:oasis:names:tc:SAML:2.0:cm:sender-vouches
  subjectTemplate: ${userId}
  trustStorePassword:
  trustStorePath:
  trustStoreType: JKS
  verifyServerHostname: true
  xmlSignatureAlgorithm: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
  xmlSignatureDigestMethod: http://www.w3.org/2001/04/xmlenc#sha256