Issue

Attempts to configure Box as a web storage provider in Pega Platform fail with a validation error on the Target Folder field. The error is a downstream symptom of an incomplete or misconfigured OAuth 2.0 authentication profile — the folder browser cannot load until authentication succeeds. 

Symptoms and Impact 

The following errors appear depending on which grant type is configured: 

With JWT Bearer grant type: 

• Exception while retrieving OAuth2.0 profile: Unable to obtain access token for client details in authentication profile configured for connector. 
• Unable to fetch access token: As per the authentication profile configuration you need to login with OIDC authentication service. 

With Client Credentials grant type: 

• BEARER authentication error: No access token available 

After authentication is resolved but folder browse is attempted with an incorrect token type: 

• (Pega-API-Storage-Folder) The specified file/folder does not exist in the target repository. 

UI validation error (surface symptom): 

• Target folder — This field may not be blank. 

The integration cannot be completed. Attachments cannot be stored in Box. 

Steps to reproduce 

1. Open the Application Definition rule.
2. Click the Integration tab.
3. In the Content storage section, select Store in web storage provider.
4. In the Provider list, select Box.
5. Select or enter an Authentication Profile. 
6. Click Browse next to Target folder.
   • The folder browser fails to load, or an OAuth error is thrown.
   • The Target folder field remains empty, blocking save. 

Root Cause

The Target Folder field and folder browser require a valid OAuth 2.0 access token from Box before they can render. The errors are caused by one or more of the following configuration gaps: 

1. The JWT assertion in the Authentication Profile is set to "Use token from active SSO session" instead of "Use JWT generation profile." This causes the OIDC error. 
2. The JWT Token Generation Profile is missing required Box claims (iss, sub, aud, box_sub_type), or the claims are misconfigured. 
3. The Keystore is missing, the wrong key password is used (the key password inside the JKS differs from the keystore password), or the public key uploaded to Box does not match the private key in the Pega keystore. 
4. The token endpoint is incorrect or the "Suppress generation of Key ID (kid) header" option is not enabled, both of which Box requires. 

Box requires the JWT Bearer grant type for server-to-server (enterprise) authentication. Client Credentials without a valid JWT assertion is not sufficient. 

Solution

Configure the full OAuth 2.0 + JWT Bearer chain before attempting to browse the Target Folder. The configuration involves four artifacts created in the following order:

Keystore → JWT Token Generation Profile → Authentication Profile → Application Definition. 

Local Change (Configuration) 

Step 1 — Create the Keystore 

In your Box Developer Console, either generate a key pair and download the config.json file, or create your own key pair using a keystore management tool (such as KeyStore Explorer). 

In Pega Platform™: 

1. Navigate to Records > SysAdmin > Keystore and create a new record. 
2. Upload the JKS file. 
3. Set Keystore Type to JKS. 
4. Enter the keystore password (the password protecting the JKS file itself). 
5. Save. 

Note: The keystore password and the key password are separate values. The key password is the passphrase for the private key entry inside the JKS. If you used a Box-provided key, this passphrase is in the config.json file under passphrase. 

Step 2 — Create the JWT Token Generation Profile 

1. Navigate to Records > Security > Token Profile and create a new Generation profile. 

2. Configure Registered Claims: 

3. Add a Custom Claim: 

   1. Name: box_sub_type 
   2. Value: enterprise 

4. Configure Signature: 

   1. Type: Asymmetric 
   2. Algorithm: RS256 (or the algorithm used when creating the key pair) 
   3. Keystore: select the keystore created in Step 1 
   4. Alias: select from the dropdown 
   5. Password: enter the key password (not the keystore password) 
   6. Enable: Suppress generation of Key ID (kid) header 
   7. Token Lifetime: 60 seconds 

5. Save. 

Step 3 — Create the Authentication Profile 

1. Navigate to Records > Security > Authentication Profile and create a new OAuth 2.0 profile. 
2. Set OAuth 2.0 Provider to Box. 
3. Set Grant Type to JWT Bearer. 
4. Enter the Client Identifier and Client Secret from Box. 
5. In the JWT Assertion section, select Use JWT generation profile and choose the profile created in Step 2. 
6. Expand Advanced configuration: 
   1. Authentication Scheme: Client Secret 
   2. Method: POST 
7. Save. 

Step 4 — Configure the Application Definition 

1. Open the Application Definition rule and click the Integration tab. 
2. In Content storage, select Store in web storage provider. 
3. Set Provider to Box. 
4. In Authentication profile, select the profile created in Step 3. 
5. Click Browse next to Target folder and select the desired folder. 
6. Save.

References

Configuring a Box repository 

Creating an OAuth 2.0 profile with a JWT bearer  

Access tokens (server authentication) (Box Developer Documentation) 

How to set Box as a repository  (Pega Forums)