Authentication

Authentication and session management for iDempiere web services

All iDempiere web service requests require authentication using the ADLoginRequest structure. The system validates credentials, role access, and establishes a session context for subsequent operations.

Authentication Flow

Login Request Structure

Every web service request includes an ADLoginRequest element containing authentication and context information.

ADLoginRequest Parameters

user · string · required

Username or email address. The system configuration determines whether to use username or email for login (controlled by USE_EMAIL_FOR_LOGIN system configuration).

WebService
[e-mail] (if email login enabled)

pass · string · required

User password in plain text. The password is validated against the AD_User table.

Always use HTTPS/TLS to encrypt credentials in transit.

lang · string · required

Language and locale code for the session. Affects date formats, decimal separators, and translated messages.

Common values:

• en_US - English (United States)
• es_MX - Spanish (Mexico)
• de_DE - German (Germany)
• fr_FR - French (France)
• zh_CN - Chinese (China)

ClientID · integer · required

The tenant/client ID (AD_Client_ID). System client is 0, but web services typically use a specific tenant.

The user must have access to this client.

RoleID · integer · required

The role ID (AD_Role_ID) to use for this session. The role must:

• Be assigned to the user
• Have RoleType of NULL or ‘WS’ (web service enabled)
• Have access to the specified organization
• Have access to the requested web service type

OrgID · integer · required

The organization ID (AD_Org_ID) for the session context. The role must have access to this organization through:

• IsAccessAllOrgs = 'Y', or
• AD_Role_OrgAccess entries, or
• AD_User_OrgAccess entries (if IsUseUserOrgAccess = 'Y')

WarehouseID · integer · required

The warehouse ID (M_Warehouse_ID) for the session. Can be 0 if no warehouse is required. The warehouse must belong to an organization accessible by the role.

stage · integer · required

Session expiry time in minutes. Common values:

• 9 - Standard session (recommended)
• 0 - Session expires immediately after request (not cached)
• 60 - 1 hour session
• 480 - 8 hour session

Sessions are cached based on: ClientID, OrgID, Username, RoleID, WarehouseID, Language, Password, and IP Address.

Authentication Examples

REST/JSON

{
  "ADLoginRequest": {
    "user": "WebService",
    "pass": "WebService",
    "lang": "en_US",
    "ClientID": 11,
    "RoleID": 50004,
    "OrgID": 11,
    "WarehouseID": 103,
    "stage": 9
  }
}

Session Management

Session Caching

iDempiere caches authenticated sessions to improve performance and reduce database load. Sessions are cached using a composite key:

String key = ClientID + "|" + OrgID + "|" + Username + "|" + 
             RoleID + "|" + WarehouseID + "|" + Language + "|" + 
             Password + "|" + IPAddress;

If any parameter changes (including IP address), a new session is created. This ensures security while allowing session reuse for repeated requests.

Session Expiry

Sessions expire based on the stage parameter (expiry time in minutes):

• Active Sessions: Refreshed on each successful authorization
• Expired Sessions: Automatically removed when connectCount == 0 and expiry time elapsed
• Session Cleanup: Sessions are logged out and removed from cache when expired

Context Variables

Authenticated sessions establish the following context variables:

#AD_Client_ID · integer

Current client/tenant ID

#AD_Org_ID · integer

Current organization ID

#AD_User_ID · integer

Current user ID

#AD_User_Name · string

Current user name

#AD_Role_ID · integer

Current role ID

#M_Warehouse_ID · integer

Current warehouse ID

#SalesRep_ID · integer

Sales representative ID (same as user ID)

#AD_Language · string

Session language code

#Date · timestamp

Current date for the session

Role Configuration

Web Service Enabled Roles

For a role to access web services, it must meet these requirements:

1. Role Type: Must be NULL or ‘WS’ in the AD_Role table
2. Active: Role must be active
3. User Assignment: Role must be assigned to the user
4. Organization Access: Role must have access to the specified organization

Web Service Type Access

Access to specific web service operations is controlled through WS_WebServiceTypeAccess:

SELECT IsActive 
FROM WS_WebServiceTypeAccess 
WHERE AD_Role_ID IN (
  SELECT AD_Role_ID FROM AD_Role WHERE AD_Role_ID = ?
  UNION 
  SELECT Included_Role_ID FROM AD_Role_Included WHERE AD_Role_ID = ?
) 
AND WS_WebServiceType_ID = ?

The query checks:

• Direct role access
• Included role access (role inheritance)
• Active status of the access record

Validation Hooks

iDempiere provides extension points for custom authentication logic through the IWSValidator interface.

Validation Timing

1. Before Login

   TIMING_BEFORE_LOGIN - Validate credentials before authentication

   Use cases:

   • IP whitelist validation
   • Rate limiting
   • Custom password policies
2. After Login

   TIMING_AFTER_LOGIN - Validate after successful authentication

   Use cases:

   • Audit logging
   • External system integration
   • License validation
3. On Authorization

   TIMING_ON_AUTHORIZATION - Validate service type access

   Use cases:

   • Service-specific authorization
   • Usage quota enforcement
   • Custom access control

Custom Validator Example

public class MyWSValidator implements IWSValidator {
  
  @Override
  public void login(ADLoginRequest loginRequest, Properties ctx, 
                    MWebServiceType webServiceType, int timing) 
                    throws IdempiereServiceFault {
    
    if (timing == TIMING_BEFORE_LOGIN) {
      // Validate IP address
      String ipAddress = ctx.getProperty("#IPAddress");
      if (!isAllowedIP(ipAddress)) {
        throw new IdempiereServiceFault(
          "Access denied from IP: " + ipAddress,
          new QName("IPValidation")
        );
      }
    }
    
    if (timing == TIMING_ON_AUTHORIZATION) {
      // Check usage quota
      if (isQuotaExceeded(webServiceType)) {
        throw new IdempiereServiceFault(
          "Usage quota exceeded for service type",
          new QName("QuotaValidation")
        );
      }
    }
  }
}

Common Authentication Errors

Error: User invalid

Cause: Username/password combination is incorrect.

Solution:

• Verify credentials in the AD_User table
• Check if email login is enabled (USE_EMAIL_FOR_LOGIN)
• Ensure user is active

Error: Tenant not allowed for this user

Cause: User doesn’t have access to the specified ClientID.

Solution:

• Verify user has a role in the specified client
• Check AD_User_Roles table

Error: Role not allowed for this user

Cause: Specified RoleID is not assigned to the user or not web service enabled.

Solution:

• Check AD_User_Roles for role assignment
• Verify role has RoleType NULL or ‘WS’
• Ensure role is active

Error: Org not allowed for this role

Cause: Role doesn’t have access to the specified OrgID.

Solution:

• Check AD_Role_OrgAccess table
• Verify IsAccessAllOrgs setting on role
• If using user org access, check AD_User_OrgAccess

Error: Warehouse not allowed for this org

Cause: Warehouse doesn’t belong to an accessible organization.

Solution:

• Verify warehouse exists (M_Warehouse)
• Check warehouse organization
• Try WarehouseID = 0 if no warehouse needed

Error: Login role does not have access to the service type

Cause: Role lacks permission for the specific web service type.

Solution:

• Add entry in WS_WebServiceTypeAccess
• Verify service type is active
• Check included roles if using role inheritance

Security Best Practices

Use HTTPS

Always use TLS/SSL encryption for web service communications to protect credentials and data in transit.

Dedicated Service Users

Create dedicated user accounts for web service integration rather than using personal accounts.

Least Privilege Roles

Assign roles with minimal required permissions. Create specific web service roles with restricted access.

Session Expiry

Use appropriate session expiry times. Shorter times for sensitive operations, longer for batch processing.

IP Whitelisting

Implement IP-based access control using custom validators or network-level restrictions.

Audit Logging

Implement custom validators to log all web service access for security auditing.

Testing Authentication

Test your authentication configuration:

1. Verify User Access

   Log in to iDempiere UI with the web service user credentials to ensure the account works.

2. Check Role Configuration

   Navigate to Role window and verify:

   • Role Type is NULL or WS
   • User is assigned to the role
   • Organization access is configured
3. Configure Service Type Access

   In Web Service Type Access window, create entries for:

   • Role ID
   • Web Service Type
   • IsActive = Y
4. Test with cURL

   Use a simple REST API call to verify authentication works end-to-end.