Skip to Content

SAML security provider in Jitterbit App Builder

SAML Single Sign-On (SSO) authentication is defined in the following documents:

In a SSO scenario, there are three roles:

  • Principal - The user accessing a restricted service.
  • Service Provider (SP) - Provides access to restricted services.
  • Identity Provider (IdP) - Authenticates users.

App Builder can be configured as either an SP or IdP using the appropriate security provider. This document covers the SAML security provider, which is used for the SP role. In this role, App Builder delegates authentication to a third-party IdP. Supported IdPs include:

For the IdP role, see the SAML identity provider.

Flows

The SAML Single Sign-On (SSO) specification defines several flows. The SAML security provider supports the following SAML SSO flows:

  • Service Provider (SP) initiated
  • Identity Provider (IdP) initiated

Service provider (SP) initiated

In the Service Provider (SP) initiated flow, a user navigates to App Builder and attempts to access a restricted page. App Builder redirects the user to the Identity Provider (IdP) via the SAML Redirect binding (HTTP GET). Once authenticated, the IdP redirects the user back to App Builder using the SAML Post binding (HTTP POST). App Builder validates the SAML Response, maps the name identifier to a local App Builder user account, and grants the rights associated with the user account.

Note that, before redirecting the user to the IdP, App Builder records the URL of the page that the user attempted to access. Once the user has authenticated, App Builder redirects the user back to the originally requested page. This enables deep linking.

Identity provider (IdP) initiated

In the Identity Provider (IdP) flow, a user navigates directly to the IdP. Once authenticated, the user is redirected to App Builder via the SAML Post binding (HTTP POST). As with the SP Initiated flow, App Builder validates the SAML Response, maps the name identifier to a local App Builder user account, and grants the rights associated with the user account.

Typically, App Builder will redirect the user to their home page upon successful sign-in. However, the IdP may perform a deep link by passing the URI in the SAML Response RelayState parameter. See the AllowRelayStateRedirects parameter below.

Configuration

Tokens

  • Issuer: The SAML assertion issuer. Defaults to the audience.
  • Audience: SAML assertion audience restriction. The value must be a syntactically valid URI.
  • Recipient: The SAML assertion recipient. This value must be a syntactically valid URI. Defaults to the Assertion Consumer Service URI (e.g. https://example.com/App Builder/signin-SAML).

Caution

For legacy reasons, Audience defaults to the application-root URL (e.g. https://example.com/App Builder/). It is strongly recommended that you explicitly set the Audience rather than rely on the default.

Endpoints

Type Description
Metadata Endpoint SAML Single Sign-On (SSO) service metadata endpoint. This parameter is required if the Request Redirect Endpoint or SigningCertificate parameters are undefined.
RelayState URI Allowed RelayState redirect URI for a SAML Identity Provider (IdP) initiated request. See the AllowRelayStateRedirects parameter for additional information.
Request Redirect Endpoint SAML Single Sign-On (SSO) authentication request endpoint for the Redirect binding. This parameter is required if the Metadata Endpoint is undefined.

Certificates

Purpose Type Format Description
Signature Validation X.509 Certificate
  • PEM (CERTIFICATE)
  • PKCS#12 (PFX), base64-encoded
X.509 certificate used to validate SAML Single Sign-On (SSO) response signatures.

The signature validation certificate is required if the Metadata Endpoint is undefined.

Properties

The SAML security provider defines the following additional parameters:

Parameter Default Description
AllowRelayStateRedirects False Indicates whether a SAML Identity Provider (IdP) initiated sign-on may include a redirect URI in the RelayState parameter. The redirect URI is the location that the user will be redirected to after signing in.

By default, the RelayState parameter may not contain a redirect URI. Set to True to allow redirect URIs in the RelayState parameter.

To guard against open relay attacks, the URI must match the RelayState URI endpoint.
IgnoreTlsErrors False Indicates whether App Builder should ignore HTTPS certificate errors when making back-channel requests to retrieve the service metadata.

This setting is for setup and testing purposes only. Do not enable this setting on a running system.
SignatureRequirement AssertionOrResponse Indicates whether the SAML response, assertion or both most be signed. Options include: - AssertionOrResponse - Either the assertion or response must be signed. - Assertion - The assertion must be signed. - Response - Only the response must be signed. The assertion inherits the response signature. - AssertionAndResponse - Both the assertion and the response must be signed.
LogPII False Indicates that personally identifiable information (PII) should be logged. This setting takes effect on startup.

Claims

SAML assertions contain attributes. Attributes are multi-valued key/value pairs. App Builder treats SAML assertion attributes as claims. The attribute name maps to a claim identifier.

For example, given a SAML assertion with the following attribute:

<Attribute AttributeName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
  <AttributeValue>Arthur.Dent</AttributeValue>
</Attribute>

Mapping the identifier http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name to the Name property will set the user name to "Arthur.Dent" when the user account is provisioned.

The following table describes the default claim mappings:.

Identifier Purpose Description
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier Name Identifier Unique, immutable identifier used to map the third-party identity to an App Builder user.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name Name User name.
http://schemas.xmlsoap.org/claims/Group Group Security group membership.
http://schemas.zudy.com/identity/claims/fullname Full Name Full name.
http://schemas.zudy.com/identity/claims/displayname Display Name Friendly name.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress Email Address Email address.
http://schemas.zudy.com/identity/claims/phonenumber Phone Number Phone number.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/thumbprint X.509 certificate thumbprint.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/x500distinguishedname X.509 certificate distinguished name.
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dns X.509 certificate DNS name.

Integration

Assertion consumer service

The SAML security provider exposes a single endpoint. The endpoint receives SAML Responses. This is referred to as the Assertion Consumer Service. An App Builder Assertion Consumer Service URL might look something like this:

https://example.com/App Builder/signin-SAML

The URL is composed of the following parts:

Component Description
https://example.com/App Builder/ Absolute URL of the App Builder application-root directory.
SAML URL-encoded, SAML security provider name. The value is case-sensitive.

Troubleshooting

Error "The AudienceRestrictionCondition was not valid because the specified Audience is not present in AudienceUris."

This error indicates that the audience URI does not match. Ensure that the Audience property has been explicitly set. If not set, it will default to the current URL, which may vary by user. The value is case-sensitive.

Known issues and limitations

The App Builder SAML Single Sign-On (SSO) security provider has the following limitations:

  • Only a single audience restriction may be validated.
  • The Artifact resolution protocol is not supported.
  • The Logout protocol is not supported.