SAML security provider in Jitterbit App Builder
SAML Single Sign-On (SSO) authentication is defined in the following documents:
- Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0
- SAML Version 2.0 Errata 05
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 |
| 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.