Client authentication in Jitterbit App Builder

App Builder can operate as an OpenID Connect (OIDC) authorization server. The authorization server allows client applications, including other instances of App Builder, to authenticate users. The OIDC sign-in process produces an access token that allows the client application to access protected resources on the user's behalf. Protected resources include App Builder-hosted REST and Webhook APIs, as well as App Builder Connector data sources.

Protocol support

The OIDC protocol is defined by the OpenID Connect Core 1.0 standard. OIDC is an identity layer built on top of the OAuth 2.0 authorization framework, which is defined by RFC-6749. Together, these standards describe:

• Flows - A flow is a process by which the client retrieves identity and access tokens. For this reason, flows are also referred to as grants.
• Endpoints - Each flow involves one or more HTTP requests to well-known URLs.
• Scopes - Client applications may request one or more scopes. Scopes determines which tokens are issued (identity, refresh), what's included in those tokens (claims), and which APIs can be accessed with those tokens.
• Claims - As described by the standard, the identity token is fundamentally a JSON Web Token (JWT). JWTs are claims-based. The requested scope determines which claims are included in the identity token.

Supported flows

The App Builder authorization server supports the following, base OAuth 2.0 flows:

• Authorization Code. The Authorization Code flow allows the client to acquire an access token, which allows the client to access protected resources on the user's behalf. The Authorization Code flow is an interactive flow: a user must be present to initiate the Authorization Code flow.
• Client Credentials. The Client Credentials flow allows the client application to acquire an access token on behalf of itself. This is a server-to-server flow, typically operating as a service account.
• Refresh Token. The Refresh Token flow allows the client to request a new access token once the current token has expired. This is sometimes referred to as "offline access." The refresh token flow can be used in combination with either the Authorization Code or Client Credentials flows. The offline_access scope enables the Refresh Token flow (see below).

As noted above, OIDC is built on the OAuth 2.0 authorization framework. OIDC leverages OAuth 2.0 flows, using the scope parameter to opt into OIDC-specific functionality. The App Builder authorization server supports the following OIDC flows:

• Authorization Code. When the openid scope is specified, the Authorization Code flow allows the client to authenticate a user by returning an additional identity token. Additional scopes determine which claims are included in the token.
• Refresh Token. The Refresh Token flow operates the same in OIDC as it does in OAuth 2.0.

The authorization server does not support either the OIDC Implicit or Hybrid flows. The OAuth 2.0 Client Credentials flow is not an OIDC flow.

The Authorization Code flow can be used with or without the Proof Key for Code Exchange (PKCE) extension, as defined by RFC-7636.

Supported endpoints

The App Builder authorization server publishes the following endpoints:

Supported scopes

The App Builder authorization server supports the following scopes:

Supported claims

As noted above, the identity token is a claims-based, JWT token. The client may determine which claims are included in the identity token by specifying scopes.

For a description of each of these claims, see section 5.1 Standard Claims of the OIDC standard. Any standard claim not explicitly listed above is unsupported.

Configuration

To make use of the authorization server, the App Builder administrator must first:

1. Enable the authorization server.
2. Register a client application.
3. Configure the client application.

Enable the authorization server

To enable the authorization server, start by signing into App Builder as an administrator:

1. Click the IDE link.
2. Click the Security Providers button.
3. In the User Authentication panel, locate the Authorization Server security provider and click the Details icon (Chevron).
4. Click the Edit button.
5. Check the Enabled option.
6. Click the Save button.

Register a client application

Each client application that intends to authenticate users or access protected resources must be registered. To register a client application, start by signing into App Builder as an administrator, then follow these steps:

1. Click the IDE link.
2. Click the User Management button.
3. Click the Clients button.
4. Click the +Client button to register a new client application.

5. Provide the following:

   • Name: A descriptive, friendly name for the client application.
   • Description: An optional description.
   • User: Select the service user account. Required for the Client Credentials flow. Otherwise, leave blank.
   • Authentication Provider: Select a provider or leave blank.
   • Enabled: Enable or disable the client application.

6. Click the Save button.

7. (Optional) Click More, then Advanced. The Advanced Settings dialog opens. It contains two tabs:

   • Properties: Set the following settings, as required:

     • Requires PKCE: When selected, the client must use the PKCE extension. This only applies to the Authorization Code flow, and is required for public clients.

     • Public: When selected, the client is public and secrets cannot be stored securely. When unselected, the client is confidential and can store secrets securely.

   • Token Lifetimes: Enter values for the following fields, as required:

     • Access Token: Access token expiry time, in minutes. Default: 60.

     • Refresh Token: Refresh token expiry time, in minutes. Default: 20160 (14 days).

     • Identity Token: Identity token expiry time, in minutes. Default: 20.

     • Authorization Code: Authorization code expiry time, in minutes. Default: 5.

Generate a client secret

The client application must supply its own credentials when requesting an access token. The client credentials consist of the client ID and a client secret. Client secrets can only be generated for confidential clients. The Secrets panel will be hidden for public clients.

To generate a client secret:

1. In the Secrets panel, click the +Secret button.

2. Provide the following:

   • Description: Optional client secret description.
   • Expires On: If the secret should expire, set the expiration date and time. Otherwise, leave this field blank.

3. Click the Save button.

4. Copy the Client ID and Client Secret.

WARNING: This is the only time that the secret will be visible.

Register client redirect URI

As noted above, the Authorization Code flow is an interactive flow. During this flow, the user is redirected to the authorization endpoint. Once the user has authenticated, they are redirected back to the client application.

The client application callback URL is referred to as the "redirect URI." Each redirect URI must be registered. Client redirect URIs must adhere to following restrictions:

• The client redirect URL must be an absolute URL.
• The client redirect URL should use the HTTPS protocol. However, the client redirect URL may use the HTTP protocol when redirecting to localhost.
• The client redirect URL may contain a query string.
• The client redirect URL must not contain a fragment.

To register a client redirect URI:

1. In the Redirects panel, click the +URL button.
2. Provide the URL.
3. Click the Save button.

Configure the client application

Any standards-compliant OIDC or OAuth 2.0 client application that supports either the Authorization Code or Client Credentials flows can utilize the App Builder authorization server. This includes App Builder itself: it is possible to configure a second instance of App Builder as a client.

To configure the App Builder client, you will need:

• App Builder authorization server root URL, e.g. https://example.com/App Builder.
• Client ID and secret (see above)

Start by signing into the client instance of App Builder as an administrator:

1. Click the IDE link.
2. Click the Security Providers button.
3. In the User Authentication panel, click the +User Authentication button.

4. Provide the following:

   • Name: Security provider name, e.g. App Builder.
   • Type: App Builder / OpenID Connect
   • Show On Login Form: Check this option to display the login option on the login form.
   • User Provisioning: Check this option to enable user provisioning.

5. Click the Save button.

6. In the Endpoints panel, click the +Endpoint button.

7. Provide the following:

   • Endpoint Type: OpenID Connect Issuer
   • URL. The App Builder authorization server root URL.

8. Click the Save button.

9. In the Credentials panel, click the +Credential button.

10. Provide the following:

    • Type: Client
    • User Name: The client ID (see above).
    • Password: The client secret (see above).

11. Click the Save button.

12. In the Provider panel, click the Edit button.
13. Check the Enabled option.
14. Click the Save button.

Once complete, users will be able to sign into the client App Builder instance using the App Builder authorization server.

Known limitations

The App Builder authorization server does not support the following

• User consent.
• OIDC Implicit or Hybrid flows