Skip to Content

OAuth security provider in Jitterbit App Builder

The OAuth security provider enables support for OAuth 2.0. The security provider is responsible for authorizing web service requests. The following data source types support OAuth:

  • REST

  • OData

  • RDBMS (limited to supported CData providers)

In addition, it is possible to configure an OAuth security provider as an external authentication provider. See below for additional information.

OAuth 2.0 grants

The OAuth security provider supports the following OAuth 2.0 grants:

Authorization code

The OAuth 2.0 Authorization Code grant provides delegated, user-level authorization. This grant is defined in RFC 6749.

In the Authorization Code flow, App Builder redirects the user agent (browser) to the authorization server. Once the user has successfully signed in and approved the authorization request, the authorization server redirects the user agent back to App Builder. The redirect includes an authorization code. App Builder makes a back-channel request to the authorization server, exchanging the authorization code for an access token. The access token can then be used to authorize requests to web services.

In and of itself, OAuth provides authorization, not authentication. Therefore, OAuth security providers are not typically used as external authentication providers: they are used to authorize requests to a compatible data provider such as OData or REST. However, if the OAuth security provider publishes an endpoint which provides the user identity, the OAuth security provider can be used as an external authentication provider. See the User Info Endpoint for additional details.

Client credentials

The OAuth 2.0 Client Credentials grant provides client-level authentication, akin to a service account. In this flow, the OAuth client credentials are exchanged for an OAuth access token. The Client Credentials grant is defined in RFC 6749.

Resource owner password credentials

The OAuth 2.0 Resource Owner Password Credentials grant is defined in RFC 6749. However, the grant has since been deprecated.

Important

The resource owner password credentials grant MUST NOT be used.

As originally conceived, the OAuth 2.0 Resource Owner Password Credentials grant provides user-level authorization. The user supplies his or her user name and password to a trusted client. The trusted client exchanges the credentials for an access token.

App Builder provides partial support for the OAuth 2.0 Resource Owner Password Credentials grant. App Builder does not prompt the user for their credential. Instead, a single credential is used to authorize all users. In this way, the grant is functionally equivalent to a service account.

SAML 2.0 bearer assertion

The OAuth 2.0 SAML 2.0 Bearer Assertion grant provides user-level, data source authentication. In this flow, SAML assertions are exchanged for OAuth access tokens. The OAuth 2.0 SAML 2.0 Bearer Assertion grant is defined in RFC 7522.

JWT bearer token

The OAuth 2.0 JWT Bearer Token grant provides user-level, data source authentication. In this flow, JSON Web Tokens (JWTs) are exchanged for OAuth access tokens. The OAuth 2.0 JWT Bearer Token grant is defined in RFC 7523.

Configuration

Configuration varies based on the OAuth grant. At a minimum, OAuth requires:

  • Client identifier (client_id) and client secret (client secret).

  • Token endpoint.

Individual OAuth grants will require additional configuration as indicated below.

Authentication

The authentication properties determine the OAuth grant and authentication schemes.

  • Authentication Type: OAuth

  • OAuth Grant: Select a supported OAuth grant.

  • OAuth Client Authentication: Determines the OAuth 2.0 client authentication scheme RFC 6749 Section 2.3. Options include:

    • None: Indicates that the client should not be authenticated. (none.)

    • Basic: Indicates that the Client Password scheme will be used. The credentials will be supplied using HTTP Basic authentication. (client_secret_basic.)

    • Post: Indicates that the Client Password scheme will be used. The credentials will be supplied as form parameters in the request body. (client_secret_post.)

  • OAuth Resource Authentication: Determines the resource request authentication scheme. Options include:

    • Bearer: Bearer authentication scheme. Default.

    • Form: Append access token to form url-encoded body.

    • Query: Append access token to query string.

  • Token Owner: Determines whether tokens are issued to individual users or to the client system. Options include:

    • User: Tokens are issued to individual users.

    • Client: Tokens are issued to the client system.

  • Token Delete On Sign Out: When enabled, App Builder deletes the stored token when the user logs out. Default: Disabled.

Token

The following grants generate tokens which are exchanged for OAuth access tokens:

  • SAML 2.0 Bearer Assertion.

  • JWT Bearer Token.

SAML 2.0 bearer assertion

  • Issuer: The SAML assertion issuer.

  • Audience: The SAML assertion audience restriction. Though the SAML specification indicates that the audience is a URI, many implementations do not honor this. Consequently, App Builder does not require the audience to be a URI.

  • Recipient: The SAML assertion recipient URI (e.g. http://example.com/service).

JWT bearer token

Endpoints

Type Grants Description
Authorization Endpoint Authorization Code OAuth 2.0 authorization endpoint URL. RFC 6749
Token Endpoint All OAuth 2.0 token endpoint URL. RFC 6749
User Info Endpoint Authorization Code Endpoint that supplies the user identity. Required when treating OAuth as an external authentication provider. Not part of the OAuth standard. The endpoint must return a JSON response which includes the user identity.

Credentials

Type Grants Description
Client All OAuth 2.0 client identifier (client_id) and secret (client_secret). RFC 6749
Resource Owner Resource Owner Password Credentials OAuth 2.0 resource owner user name (username) and password (password). RFC 6749

Certificates

Type Grants Description
Signing SAML 2.0 Bearer Assertion The SAML 2.0 Bearer Assertion grant requires an X.509 certificate with private key in a password-protected PKCS#12 (.pfx) container.
JWT Bearer Token The JWT Bearer Token grant requires a PEM-encoded, PKCS#1 RSA private key (RSA PRIVATE KEY).

Properties

The OAuth security provider supports the following additional parameters:

Parameter Default
BearerSchemeIdentifier Bearer Authorization scheme when using the Bearer resource authentication.
ExpiresIn Access token expiry in seconds. Can be used if the token endpoint does not provide an expiry and the the resource server does not return a 401 Unauthorized response when the access token has expired.
IgnoreTlsErrors False Indicates whether App Builder should ignore TLS errors when making back-channel requests to the token endpoint. This should only be used for development and testing.
Scopes White space delimited list of OAuth 2.0 access token scopes. RFC 6749
SingleUseAccessToken False Indicates whether the access token can only be used once.
Token Endpoint Parameters Parameters passed to the OAuth token endpoint. By default, App Builder will generate the appropriate parameters based on the OAuth flow. Only use this setting for non-conformant or otherwise unsupported OAuth APIs. The parameters should be specified in form URL encoded format (application/x-www-form-urlencoded). If the parameter list begins with an ampersand (&), the parameters will be merged into the generated parameters. If a parameter has the same name as a generated parameter, the generated parameter will be overwritten. If a supplied parameter does not have a value, e.g. &grant_type&username=user&password=password, the generated parameter will be removed. Otherwise, the supplied parameter is appended to the generated parameters. The parameter list supports string interpolation. Expressions may reference dynamic parameters, e.g username={{ client_id }}&password={{ client_secret }}. This is useful when integrating with third-party APIs that do not use standard parameter names.
RefreshRequiresScopes False Indicates whether the scopes (scope) should be included in the request body sent to the token endpoint when refreshing the access token.

Authorization code

The following additional properties apply to the Authorization Code grant.

Parameter Default
BackchannelAuthorization False Indicates whether an authorization code can be acquired via a backchannel (server-to-server) request. This is a non-standard extension to the Authorization Code grant.

SAML 2.0 bearer assertion

The following additional properties apply to the SAML 2.0 Bearer Assertion grant.

Parameter
SamlSingleSignOnProvider Name of an App Builder SAML security provider. This parameter only applies to the SAML 2.0 Bearer Assertion grant.

JWT bearer token

The following additional properties apply to the JWT Bearer Token grant.

Parameter Default
JwtClaimSet { "scope": "{{ scope }}" } Authorization servers may require custom claims. For example, Google requires a scope claim matching the OAuth scope parameter. The JwtClaimSet parameter allows administrators to supply additional claims. The value takes the form of a JSON template. The following values may be substitued into the template:
  • client_id - OAuth
  • client_id parameter.
  • client_secret - OAuth client_secret parameter.
  • scope - OAuth scope parameter.
  • sub - JWT sub claim.
  • iss - JWT iss claim.
  • aud - JWT aud claim.
SigningAlgorithm RS256 JWT algorithm parameter as defined in RFC 7518. The only supported algorithm is RS256.

Rest

The following additional properties apply when the OAuth security provider is used to authenticate REST data sources. These are ignored for OAuth endpoints and other types of data sources, including OData and RDBMS.
Request Headers must be separated by a carriage return (appear on its own line).

Parameter Default Example
RequestHeaders X-Custom-Header: Value X-Another-Header: Value Custom HTTP headers appended to REST endpoint requests. The headers must be formatted according to RFC 7230. Line folding is not supported.

Protocol support

Refresh tokens

If the access token request includes a refresh token, App Builder will automatically attempt to use the refresh token to acquire a new access token after receiving a 401 Unauthorized response.

Authorization code

Authorization request

When constructing an authorization request, App Builder will include the client identifier (client_id), client secret (client_secret) and scopes (scope). In addition, App Builder will automatically append the following standard parameters:

  • redirect_uri: App Builder constructs the redirect_uri parameter from the current URL. It takes the form https://example.com/AppBuilder/signin-OAuth, where OAuth is the name of the OAuth security provider.

  • state: The state parameter is an encrypted, opaque payload. It includes a Cross-Site Request Forgery (CSRF) token as per RFC 6749.

Redirection endpoint

As defined in RFC 6749, the Authorization Code grant exposes a Redirection Endpoint. This endpoint listens for authorization responses on the address:

  • https://example.com/AppBuilder/signin-OAuth

Where https://example.com/AppBuilder is the absolute URL to the App Builder application root directory and OAuth is the URL-encoded, case-sensitive name of the security provider.

Most third-party applications will need to be configured with the redirection endpoint prior to authorizing any requests.

Using OAuth for external authentication

As noted above, OAuth is an authorization protocol, not an authentication protocol. However, some vendor implementations extend the OAuth protocol to include authentication. Typically, this is done by publishing an endpoint which identifies the user. App Builder refers to such an endpoint as the User Info Endpoint.

App Builder can be configured to query the User Info Endpoint to retrieve the user's identity. This allows an OAuth security provider to be used for external authentication. Note, however, that the endpoint must meet the following requirements:

  • The endpoint must be reachable by App Builder.

  • The endpoint must respond to an HTTP GET request that does not include a request body.

  • The endpoint must honor OAuth Basic client authentication (as described above).

  • The HTTP response must have a 200 status code.

  • The HTTP response must include a body with a Content-Type of application/json.

  • The JSON document must include a top-level property which identifies the user.

After acquiring the access token, App Builder will make a client authenticated request to the User Info Endpoint. App Builder will parse the response body as JSON, treating top-level properties as claims.

For instance, given the following sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_name": "arthur.dent",
    "name": "Arthur Dent",
    "email": "arthurdent@example.com"
}

The following claim types will be available:

  • user_name

  • name

  • email

In addition to specifying the User Info Endpoint, the developer must map the claim that identifies the user–in this case, the user_name claim–to the Name claim usage type.

SAML 2.0 bearer assertion

When using the SAML 2.0 Bearer Assertion flow, SAML assertions can be sourced in one of two ways:

  1. App Builder generates and signs the SAML assertions on demand. In which case, App Builder acts as the IdP.

  2. (Deprecated) a third-party identity provider (IdP) issues a SAML assertion during the SAML single sign-on (SSO) process. see the SAML provider type for more information.

Each source requires additional configuration.

Generate SAML assertions on-demand

To generate a SAML assertion on demand, configure the Token properties as described above. In addition, the SAML 2.0 Bearer Assertion grant requires a Signing certificate with a private key.

Source SAML assertions from an IdP

To source SAML assertions from a third-party IdP, set the SamlSingleSignOnProvider parameter.