Skip to main content

Identity and Permissions: Bella OpenAPI's Authentication and Authorization System

Introduction: The Importance of Enterprise-Level Security Architecture​

In today's era of widespread AI services, API gateways must not only provide rich functionality but also establish strict identity authentication and access control mechanisms to ensure enterprise data security and compliant use. Bella OpenAPI successfully addresses this challenge through its multi-layered authentication and authorization system. This article will delve into the core design and implementation details of Bella OpenAPI's identity and permission management based on an in-depth analysis of its source code.

Diverse Authentication Mechanisms​

Through analysis of Bella OpenAPI's source code, we find that the system supports multiple authentication methods to meet the needs of different usage scenarios:

1. API Key Authentication​

API Key authentication is the core authentication mechanism of Bella OpenAPI, particularly suitable for system integration and automation scenarios:

// LoginFilter.java
if(StringUtils.isNotBlank(properties.getAuthorizationHeader())) {
 String auth = 
httpRequest.getHeader(properties.getAuthorizationHeader());
 if(StringUtils.isNotBlank(auth)) {
 chain.doFilter(request, response);
 return;
 }
}
// ApikeyService.java
public ApikeyInfo verifyAuth(String auth) {
 String ak;
 if(auth.startsWith("Bearer ")) {
 ak = auth.substring(7);
 } else {
 ak = auth;
 }
 String sha = EncryptUtils.sha256(ak);
 ApikeyInfo info = queryBySha(sha, true);
 // ...验证逻辑
 return info;
}

The system uses the Bearer Token format to transmit API Keys, mainly used for API call scenarios, and stores them using SHA-256 hashing to ensure that even in the event of a database leak, the original key will not be exposed.

2. OAuth Authentication and CAS Support​

For web interaction scenarios, the system supports OAuth 2.0 authentication flows and integrates multiple identity providers, while also supporting the connection of enterprise CAS services:

// ProviderConditional.java
@ConditionalOnOAuthEnable
@Conditional(ConditionalOnGoogleAuthEnable.GoogleAuthEnableCondition.class)
public @interface ConditionalOnGoogleAuthEnable {
 // Google OAuth 条件判定
}
@ConditionalOnOAuthEnable
@Conditional(ConditionalOnGithubAuthEnable.GithubAuthEnableCondition.class)
public @interface ConditionalOnGithubAuthEnable {
 // Github OAuth 条件判定
}

3. Parent-Child Relationship Design​

Through this parent-child relationship design, enterprise-level users can create sub-keys with different permission scopes, assign them to different teams or external partners, and ensure that each key can only access necessary resources.

// ApikeyService.java
@Transactional
public String createByParentCode(ApikeyCreateOp op) {
 ApikeyInfo apikey = EndpointContext.getApikey();
 if(!apikey.getCode().equals(op.getParentCode())) {
 throw new ChannelException.AuthorizationException("没有操作权限");
 }
 // 验证配额和安全级别
 Assert.isTrue(op.getMonthQuota() == null || 
op.getMonthQuota().doubleValue() <= 
apikey.getMonthQuota().doubleValue(), "配额超出 ak 的最大配额");
 Assert.isTrue(op.getSafetyLevel() <= apikey.getSafetyLevel(), 
"安全等级超出 ak 的最高等级");
 
 // 创建子密钥
 // ...
 
 // 验证权限范围
 if(CollectionUtils.isNotEmpty(op.getPaths())) {
 boolean match = op.getPaths().stream().allMatch(url -> 
apikey.getRolePath().getIncluded().stream().anyMatch(pattern -> 
MatchUtils.matchUrl(pattern, url))
 && 
apikey.getRolePath().getExcluded().stream().noneMatch(pattern -> 
MatchUtils.matchUrl(pattern, url)));
 Assert.isTrue(match, "超出 ak 的权限范围");
 // ...
 }
 return ak;
}

4. Permission Inheritance and Constraints​

The permissions of sub-keys are strictly constrained by their parent keys, reflected in multiple dimensions:

  • Path access constraints: The access paths of sub-keys must be a subset of their parent key's access paths
  • Quota constraints: The monthly quota of sub-keys cannot exceed that of their parent key
  • Security level constraints: The security level of sub-keys cannot be higher than that of their parent key

This design ensures the security of the permission delegation process, preventing the bypassing of permission restrictions through the creation of sub-keys.

Multi-Dimensional Authorization Control​

Bella OpenAPI implements a multi-dimensional authorization control mechanism to ensure fine-grained permission management:

1. Path-Based Access Control​

The system uses a dual mechanism of included paths and excluded paths to implement precise URL access control. This design allows administrators to flexibly define access scopes using wildcard patterns.

// ApikeyInfo.java
public boolean hasPermission(String url) {
 return getRolePath().getIncluded().stream().anyMatch(pattern 
-> MatchUtils.matchUrl(pattern, url))
 && 
getRolePath().getExcluded().stream().noneMatch(pattern -> 
MatchUtils.matchUrl(pattern, url));
}

2. Ownership Type Distinction​

The system distinguishes between different ownership types (personal, organizational, system) and implements different permission strategies accordingly, meeting the permission management needs of enterprises at different levels.

// ApikeyInfo.java
private String ownerType;
private String ownerCode;
private String ownerName;

Security Levels and Data Protection​

Bella OpenAPI introduces the concept of security levels to implement compliant control of data flow:

// ChannelRouter.java (参考之前的分析)
private Byte getSafetyLevelLimit(String dataDestination) {
 switch (dataDestination) {
 case EntityConstants.PROTECTED:
 return 10;
 case EntityConstants.INNER:
 return 20;
 case EntityConstants.MAINLAND:
 return 30;
 case EntityConstants.OVERSEAS:
 return 40;
 }
 return 40;
}

Different data flows require different security levels, ensuring that sensitive data only flows to compliant destinations:

  • Already filed (PROTECTED): Minimum security requirements, level 10
  • Internal (INNER): Moderate security requirements, level 20
  • Mainland (MAINLAND): Higher security requirements, level 30
  • Overseas (OVERSEAS): Highest security requirements, level 40

This mechanism is particularly important for enterprise users.

Resource Quotas and Usage Monitoring​

Bella OpenAPI implements a comprehensive resource quota and usage monitoring mechanism:

Usage Query​

The system provides a convenient usage query interface, allowing enterprises to analyze API usage and optimize resource allocation.

// ApikeyService.java
public List<ApikeyMonthCostDB> queryBillingsByAkCode(String 
akCode) {
 return apikeyCostRepo.queryByAkCode(akCode);
}

High-Performance Design​

Bella OpenAPI's authentication and authorization system considers performance factors while ensuring security:

1. Multi-Level Caching Strategy​

The system employs a multi-level caching strategy combining local and distributed caching, significantly reducing the latency of authentication operations:

// ApikeyService.java
@PostConstruct
public void postConstruct() {
 QuickConfig quickConfig = 
QuickConfig.newBuilder(apikeyCacheKey)
 .cacheNullValue(true)
 .cacheType(CacheType.LOCAL)
 .expire(Duration.ofSeconds(30))
 .localExpire(Duration.ofSeconds(30))
 .localLimit(500)
 .penetrationProtect(true)
 .penetrationProtectTimeout(Duration.ofSeconds(10))
 .build();
 cacheManager.getOrCreateCache(quickConfig);
}
@Cached(name = "apikey:cost:month:", key = "#akCode + ':' + 
#month", expire = 31 * 24 * 3600,
 condition = 
"T(com.ke.bella.openapi.utils.DateTimeUtils).isCurrentMonth(#month)")
@CachePenetrationProtect(timeout = 5)
public BigDecimal loadCost(String akCode, String month) {
 BigDecimal amount = apikeyCostRepo.queryCost(akCode, month);
 return amount == null ? BigDecimal.ZERO : amount;
}

The system employs a multi-level caching strategy combining local and distributed caching, significantly reducing the latency of authentication operations:

  • API Key validation results are cached for 30 seconds, reducing database pressure from frequent authentication
  • Usage statistics data employs different caching strategies based on time sensitivity
  • Cache penetration protection mechanisms ensure system stability under high concurrency

2. Asynchronous Processing​

Time-consuming operations in the system (such as recording usage, updating rate limiting counters) are processed asynchronously, without affecting the response time of the main request flow.

Application Value​

Based on our analysis of Bella OpenAPI's authentication and authorization system, we can summarize its core value in enterprise applications:

1. Security and Compliance​

  • Data sovereignty protection: Ensures compliant use of sensitive data through security levels and data flow control
  • Precise access control: Path-based fine-grained permissions ensure the principle of minimal resource access
  • Identity verification reliability: Multiple authentication mechanisms and secure key storage ensure reliable identity verification

2. Management Efficiency​

  • Hierarchical management: Simplifies large-scale permission management through parent-child key relationships
  • Resource visualization: Usage monitoring and quota management provide transparency in resource utilization
  • Flexible authorization: Supports the combined use of predefined roles and custom permission paths

3. System Integration​

  • Diverse authentication support: Simultaneously supports API Key, OAuth, and CAS, adapting to different integration scenarios
  • High-performance design: Caching and asynchronous processing ensure efficient execution of authentication and authorization operations
  • Extensible interfaces: Provides complete API Key management interfaces, facilitating integration with existing enterprise systems

Best Practices and Implementation Recommendations​

Based on our analysis of Bella OpenAPI's source code, we can extract the following implementation recommendations:

1. API Key Management Strategy​

  • Master key isolation: Create independent master keys for different business lines to avoid single points of failure
  • Regular rotation: Utilize the reset function to periodically update API Keys, reducing long-term exposure risks
  • Minimal privilege allocation: When creating sub-keys, only grant the minimum permissions required to complete specific tasks

2. Security Level Planning​

  • Data classification mapping: Establish mapping relationships between enterprise data classification standards and security levels
  • Regional compliance considerations: Consider data compliance requirements in different regions and set data flow constraints accordingly
  • Regular security audits: Periodically review key security level settings to ensure alignment with current business needs

3. Resource Quota Optimization​

  • Based on historical usage: Analyze historical usage patterns to set reasonable quotas for different business lines
  • Tiered allocation: Start with small quotas and gradually increase based on actual needs, avoiding resource waste
  • High-priority guarantees: Reserve sufficient quotas for critical business operations to ensure priority service during resource constraints

Conclusion: Balancing Security and Convenience​

Bella OpenAPI's authentication and authorization system demonstrates how a mature API gateway can achieve a balance between security and usability. Through multi-layered authentication, hierarchical key management, fine-grained permission control, and efficient performance optimization, the system meets both the strict security requirements of enterprise applications and provides a flexible, convenient user experience.

For enterprises planning to build their own AI capability gateway, Bella OpenAPI's authentication and authorization design provides a battle-tested reference model. Through similar design, enterprise users can ensure data security and compliance while opening up AI capabilities, laying the foundation for the healthy development of AI applications.

If you are interested in Bella OpenAPI's authentication and authorization system, we welcome you to visit the GitHub repository to explore its implementation details, or experience the power of this system through the online demo version.