Skip to Content

JWT SSO security provider in Jitterbit App Builder

The JWT SSO security provider is an implementation of a custom single sign-on (SSO) protocol. The protocol allows a trusted service to sign a user into App Builder. This is achieved by generating a JSON Web Token (JWT) and passing the token to an authentication endpoint by way of a client browser redirect.

Protocol

The JWT SSO protocol leverages the following standards:

Endpoints

The JWT SSO protocol defines two service endpoints.

  • Authentication Service - Hosted by App Builder.
  • Single Sign-On Service - Hosted by the trusted, third-party service.

Authentication service

The authentication service is responsible for:

  1. Authenticating a JWT.
  2. Signing the user into App Builder.

Example:

https://example.com/App Builder/signin-{Provider}

Where {Provider} is the App Builder security provider name. See Configuration.

Parameters

The authentication service endpoint defines the following parameters:

  • jwt – JSON Web Token. Required.
  • return_to – Relative URI. Optional.
JWT

The jwt parameter contains the JSON Web Token. JWTs are URL safe, so no additional encoding is required.

JWTs must meet the following requirements:

  • The JWT must be signed using the RS256 algorithm (RSA, SHA-256).
  • The JWT must not be encrypted.
  • The JWT must include the following registered claims.
Claim Name Type Purpose
iss Issuer StringOrURI App Builder will match the issuer to the security provider's configured issuer, performing a case-sensitive comparison.
sub Subject StringOrURI App Builder will match the subject to an App Builder user account.
aud Audience URI App Builder will match the audience to the security provider's configured audience. Example: https://example.com/App Builder
exp Expiration Time NumericDate App Builder will validate that expiration date is less than the current date, taking into account clock skew.
nbf Not Before NumericDate App Builder will validate that current date and time is greater than the Not Before value, taking into account clock skew.
iat Issued At NumericDate App Builder will use the Issued At value to determine the age of the JWT. App Builder will limit the window in which a token is accepted to, e.g., 5 minutes.
jti JWT ID NumericDate App Builder will use the JWT ID to prevent replay attacks.

The JWT registered claims are described in Section 4.1 of the JSON Web Token standard.

The JWT may contain additional claims. As with all App Builder security providers, the claims can be:

  • Used to provision user accounts and supply security group membership
  • Mapped to user account properties such as the user name, email address or phone number.
  • Accessed by business rules using the mvSQL claim() runtime function.

Example of a JWT payload:

{
  "jti": "918b6e73-400d-479c-baa1-8e12f5fd78f4",
  "iss": "example.com",
  "aud": "https://example.com/App Builder",
  "sub": "Arthurd.Dent",
  "iat": 1652473593,
  "exp": 1652473893,
  "groups": [
    "Users",
    "Employees",
    "Sales"
  ]
}
return_to

The return_to parameter consists of a URI. The URI is relative to the App Builder application root directory. It must be prefixed with a leading slash.

Example:

/app/Sales/Leads?LeadId=1234

App Builder will validate the URI to guard against open-redirect attacks.

Methods

Post

By default, the authentication endpoint will accept a form post:

POST /App Builder/signin-JWTSSO HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 31

jwt={jwt}&return_to={return_to}
Get

As an alternative, the authentication endpoint may also be configured to accept GET requests:

GET /App Builder/signin-JWTSSO?jwt={jwt}&return_to={return_to} HTTP/1.1
Host: example.com

When using the GET method, the JWT security token is passed in the URL query string.

Consider the following before using GET:

  • GET poses additional risk as query strings are often written to web server log files. This can be mitigated by ensuring security tokens have a short lifespan and cannot be replayed.
  • URLs are subject to length restrictions, typically in the vicinity of 2,000 characters. This can be mitigated by limiting the number of claims.
  • The return_to parameter may contain double-URL-encoded values. Such requests can be blocked by firewalls.

Single sign-on service

The Single Sign-On Service is the endpoint that App Builder will redirect users to when a challenge is issued. The Single Sign-On Service is responsible for:

  1. Authenticating the user.
  2. Generating a JWT.
  3. Redirecting the user to the Authentication Service.

The Single Sign-On Service endpoint is optional.

Configuration

Settings

  • Name: Security provider name. The name appears in the Authentication Service URL. It may also appear on the login form.
  • Type: JWT SSO

Tokens

  • Audience: Audience. URI. Used to validate the JWT aud claim. Example: https://example.com/App Builder.
  • Issuer: Issuer name. String, URI recommended. Used to validate the JWT iss claim. Case-sensitive.

Endpoints

Type Description
Single Sign-On Service Location that users will be redirected to when a challenge is issued to the JWT SSO security provider. Optional, absolute URI.

Certificates

Usage Type Description
Signature Validation X.509 Certificate RSA Public Key Used to validate the JWT signature.

Properties

The OAuth security provider supports the following additional parameters:

Parameter Default Description
AllowHttpGet False Indicates that the authentication endpoint should allow HTTP GET requests.
ClockSkew 5 Number of minutes. Positive integer. Used when validating the JWT iat, nbf and exp claims.
MaxLifetime 5 Number of minutes. Positive integer. Used to validate the iat claim
SigningAlgorithm RS256 JWT signing algorithm RS256 is the only algorithm currently supported.