# LDAP-Based JWT Authentication for REST APIs

yCrash supports LDAP / Active Directory–based authentication for REST API access using JWT (JSON Web Tokens).

With this feature enabled, users authenticate against their corporate directory (LDAP/AD). Upon successful authentication and authorization, yCrash issues a short-lived signed JWT token, which can be used to securely invoke protected REST APIs such as:

GC log analysis
Heap dump analysis
Thread dump analysis
Bundle upload

This eliminates the need for interactive browser login when integrating yCrash with:

Automation scripts
CI/CD pipelines
Monitoring platforms
Enterprise integrations

Authentication is centralized via LDAP/AD, ensuring compliance with enterprise identity governance policies.

# Key Features

Feature	Description
LDAP/AD bind	Authenticates users against your existing LDAP or Active Directory server
JWT Token Issuance	Returns a signed JWT for API consumption after successful authentication
Configurable Expiry	Token lifetime is configurable (default 15 minutes)
Group-based Authorization	User must match group filter for authorization
Secure Secret Handling	JWT secret can be supplied via environment variable/system property/config file (avoid storing in config files)
Non-Interactive Authentication	Designed for automation & integrations

# High-Level Architecture

	Client (Script / App / CI Pipeline)
				│
				│  POST /ldap/token
				│  { username, password }
				▼
			yCrash Server
				│
				│  LDAP Bind + Search
				▼
		LDAP/Active Directory
				│
				│  Success
				▼
		  JWT Token Issued
				│
				│  Authorization: Bearer <token>
				▼
		Protected yCrash REST APIs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Prerequisites

LDAP or Active Directory accessible from the yCrash server (network, firewall, ports)
LDAP configuration details:
- Server host and port (e.g. ldaps://ad.example.com:636)
- Bind format (e.g. %s@company.com for UPN)
- Search base and group filter for user lookup
JWT secret for signing tokens (recommended: environment variable YC_LDAP_JWT_SECRET)

# Configuration

This section describes how to configure LDAP JWT authentication in yCrash.

# Step 1 - Create `yc-sso-config.json`

Create a configuration file named yc-sso-config.json to define your LDAP authentication properties.

Place this file inside the yCrash upload directory.

If you are unsure where the upload directory is located in your installation, refer to the What is Upload Directory? (opens new window) documentation.

# Sample Configuration

{
  "ldap": {
    "ldapServer": "ldaps://ad.example.com",
    "ldapPort": 636,
    "clientSearch": "OU=Users,DC=company,DC=com",
    "bindFormat": "%s@company.com",
    "groupFilter": "(&(objectClass=user)(sAMAccountName=${username})(memberOf=CN=yc-app-users,OU=Groups,DC=company,DC=com))",
    "tokenExpiry": 900,
    "jwtSecret": "your-secret-min-32-chars",
    "connectTimeoutMs": 5000,
    "readTimeoutMs": 5000
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# Migrating from sso-authorized-groups.json

If you are currently using the legacy sso-authorized-groups.json file for SSO configuration, migrate to the unified yc-sso-config.json format.

Legacy format (sso-authorized-groups.json):

{
  "groups": ["Group10", "Group20", "Group30"]
}

1
2
3

New format (yc-sso-config.json):

The groups property in the legacy file corresponds to authorizedGroups in the new configuration. Add your LDAP settings under the ldap section:

{
  "authorizedGroups": ["Group10", "Group20", "Group30"],
  "ldap": {
    "ldapServer": "ldaps://ad.example.com",
    "ldapPort": 636,
    "clientSearch": "OU=Users,DC=company,DC=com",
    "bindFormat": "%s@company.com",
    "groupFilter": "(&(objectClass=user)(sAMAccountName=${username})(memberOf=CN=yc-app-users,OU=Groups,DC=company,DC=com))",
    "tokenExpiry": 900,
    "jwtSecret": "your-secret-min-32-chars"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12

Migration steps:

Create or update yc-sso-config.json in the yCrash upload directory.
Copy the values from your groups array into the authorizedGroups array.
Add the ldap section with your LDAP server details and JWT settings.
After verifying that the new configuration works, you can remove sso-authorized-groups.json. yCrash reads yc-sso-config.json first and falls back to sso-authorized-groups.json only if the new file is not found.

NOTE:

The legacy sso-authorized-groups.json file does not support LDAP configuration. To use LDAP JWT authentication for REST APIs, you must use yc-sso-config.json with the ldap section.

# Configuration Field Reference

Field	Required	Description
`authorizedGroups`	No	List of AD/IdP group names that are allowed to access yCrash. Users must belong to at least one of these groups. Used for SAML SSO and LDAP JWT. If omitted, all users who pass LDAP bind and group filter are authorized.
`ldap.ldapServer`	Yes	LDAP server URL (e.g. `ldaps://ad.example.com` or `ad.example.com`). If no scheme, `ldaps://` is assumed.
`ldap.ldapPort`	Yes	Port (e.g. 389 for LDAP, 636 for LDAPS). Must be 1–65535.
`ldap.clientSearch`	Yes	Search base DN for user lookup (e.g. `OU=Users,DC=company,DC=com`).
`ldap.bindFormat`	Yes	Format for principal during bind. Use `%s` for username (e.g. `%s@company.com` for UPN).
`ldap.groupFilter`	Yes	LDAP filter for user search. Use `${username}` for username substitution.
`ldap.tokenExpiry`	Yes	JWT expiry in seconds (e.g. 900 = 15 minutes). Must be positive.
`ldap.jwtSecret`	Yes	Secret for signing JWTs. Prefer `YC_LDAP_JWT_SECRET` env or `yc.ldapJwtSecret` system property.
`ldap.jwtIssuer`	No	Optional JWT issuer claim.
`ldap.jwtAudience`	No	Optional JWT audience claim.
`ldap.jwtSource`	No	Optional custom claim.
`ldap.connectTimeoutMs`	No	Connection timeout in ms (default 5000).
`ldap.readTimeoutMs`	No	Read timeout in ms (default 5000).

INFO:

jwtSecret can alternatively be set via environment variable YC_LDAP_JWT_SECRET or system property -Dyc.ldapJwtSecret.

# Step 2 - Configure REST API Authentication in yCrash

Enable REST API authentication by configuring the following JVM system property in the yCrash launch script.

Update the launch-yc-server.{sh | bat} file to include:

-Dyc.apiAuthEnabled=true

# LDAP Integration Design

# LDAP Bind

Bind is performed using:

bindDN = username + bindDNSuffix

Example:

jdoe@corp.t1-ad.com

# User Search

Search Base:

clientSearch

Example:

OU=Users,DC=corp,DC=t1-ad,DC=com

# Group Authorization

Filter example:

(&(objectClass=user)
 (sAMAccountName=${username})
 (memberOf=CN=yc-app-users,OU=Groups,DC=corp,DC=t1-ad,DC=com))

1
2
3

Purpose:

Ensures user exists
Ensures user belongs to authorized group

# JWT Token Design

# Signing Algorithm

HS256 (HMAC-SHA256)

# Token Claims

Example payload:

{
  "sub": "jdoe",
  "displayName": "John Doe",
  "userName": "jdoe",
  "email": "jdoe@company.com",
  "iat": 1700000000,
  "exp": 1700000900
}

1
2
3
4
5
6
7
8

INFO:

Optional claims (iss, aud, source) are included when configured in yc-sso-config.json.

# Token Expiry

Configured via:

tokenExpiry (seconds)

# Token API

# Endpoint

POST https://your-ycrash-server/ldap/token
Content-Type: application/json

1
2

# Request Body

{
  "username": "jdoe",
  "password": "password"
}

1
2
3
4

Field	Required	Description
`username`	Yes	LDAP/AD username (e.g. `sAMAccountName` or UPN prefix).
`password`	Yes	User's password.

# Success Response (200 OK)

{
  "username": "jdoe",
  "displayName": "John Doe",
  "email": "jdoe@company.com",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900
}

1
2
3
4
5
6
7

Field	Description
`username`	User’s LDAP username.
`displayName`	Display name from LDAP (if available).
`email`	Email from LDAP (if available).
`token`	JWT string for use in `Authorization: Bearer <token>`.
`expires_in`	Token lifetime in seconds.

# Error Response (4xx / 5xx)

All errors return JSON with code and message:

{
  "code": "LDAP_INVALID_CREDENTIALS",
  "message": "Invalid username or password."
}

1
2
3
4

# Error Codes

Code	HTTP Status	Description
`LDAP_INVALID_CREDENTIALS`	401	Invalid username or password.
`LDAP_USER_NOT_FOUND`	401	User not found or does not match group filter.
`LDAP_ACCOUNT_DISABLED`	401	Account is disabled.
`LDAP_PASSWORD_EXPIRED`	401	Password has expired.
`LDAP_SERVER_UNAVAILABLE`	500	LDAP server unreachable, timeout, or network error.
`LDAP_CONFIG_INVALID`	500	LDAP configuration missing or invalid.
`LDAP_JWT_SECRET_MISSING`	500	JWT signing secret not configured.
`LDAP_AUTH_FAILED`	401	Generic authentication failure.
`LDAP_TOKEN_GENERATION_FAILED`	500	Auth succeeded but token generation failed.
`REQUEST_VALIDATION_FAILED`	400	Invalid request (missing/invalid body or fields).

# Using the Token with yCrash REST APIs

After obtaining a token, include it in the Authorization header of all protected API requests. You can get the API URL from the yCrash dashboard page.

# Required Parameters

Authorization header: Authorization: Bearer <token>
ou parameter: Query parameter ou with the value for your team. When you copy the API URL from the yCrash dashboard, you will find this parameter is already appened to the API URL.

# Example: cURL

# 1. Obtain token
TOKEN=$(curl -s -X POST https://your-ycrash-server/ldap/token \
  -H "Content-Type: application/json" \
  -d '{"username":"jdoe","password":"your-password"}' \
  | jq -r '.token')

# 2. Call protected API (e.g. GC analysis)
curl -X POST --data-binary @./my-app-gc.log "https://your-ycrash-server/analyzeGC?ou=YOUR_ORG_UNIT" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain"

1
2
3
4
5
6
7
8
9
10

# Troubleshooting

# LDAP bind fails with error code 49 or data 52e

Cause: Invalid credentials.
Action: Verify username and password. Ensure bindFormat matches your AD/LDAP principal format (e.g. UPN vs DN).

# LDAP bind fails with error code 49, data 773

Cause: User must change password at next logon (AD flag).
Action: User logs in interactively once via web/AD to change password, or admin clears the flag in AD.

# LDAP bind fails with error code 49, data 533

Cause: Account is disabled.
Action: Re-enable the account in AD/LDAP.

# User not found or not matching group filter

Cause: groupFilter doesn’t match the user’s group membership.
Action: Verify groupFilter and that the user is in the expected group(s). Ensure memberOf or equivalent attribute matches your LDAP schema.

# JWT secret not configured

Cause: jwtSecret is missing in config and no env or system property is set.
Action: Set YC_LDAP_JWT_SECRET or yc.ldapJwtSecret, or add ldap.jwtSecret in config.

# 401 Unauthorized when calling protected APIs

Cause: Token expired, invalid, or missing; or ou missing or invalid.
Action: Obtain a new token; include Authorization: Bearer <token> and valid ou in the request.

REST API Authentication — Overview of all authentication methods
Basic Authentication
API Key Authentication

← API Key Authentication Basic Authentication →