security-middleware-system
table-of-contents
- introduction
- project-structure
- core-components
- architecture-overview
- detailed-component-analysis
- dependency-analysis
- performance-considerations
- troubleshooting-guide
- conclusion
- appendix
introduction
this technical document is for system architects and security engineers, systematically explaining the design and implementation of the security middleware system, focusing on the following aspects:
- middleware architecture design and execution order
- error handling mechanisms and exception paths
- collaborative working mechanisms of jwt middleware, casbin middleware, and rsa middleware
- middleware configuration options, performance optimization strategies, debugging and monitoring methods
- middleware extension guide: custom middleware development, combination patterns and exception handling best practices
- practical deployment scenarios: multi-middleware chains, performance impact analysis, security audit log recording
project-structure
this project adopts a layered and responsibility-based organization approach, security-related capabilities are concentrated in the http middleware and authentication modules of the adapter layer, cooperating with the bootstrap layer to complete middleware assembly and runtime lifecycle management.
- jwt-middleware:-responsible-for-parsing-and-validating-bearer-tokens-from-request-headers,-extracting-user-identity-information-and-injecting-into-context.
- casbin-middleware:-executes-rbac-authorization-decisions-based-on-username-and-request-resource/action.
- rsa-middleware:-client-authentication-based-on-rsa-pss-signature-and-nonce-replay-prevention.
- authentication-context:-userclaims-and-principal-provide-jwt-claims-and-runtime-principal-information.
- rsa-configuration-and-implementation:-rsaauthconfig-abstracts-configuration,-memory*-implementations-provide-in-memory-high-performance-caching-and-deduplication.
middlewares-execute-in-chain-order-in-gin-engine,-typical-order-suggestion-is: 1)-rsa-client-authentication-(signature-and-replay-prevention) 2)-jwt-authentication-(token-parsing-and-principal-injection) 3)-casbin-authorization-(based-on-principal-and-resource/action)
jwt-middleware
- key-functional-points
- parse-bearer-token-from-authorization-header
- use-hs256-key-to-parse-and-validate-token,-distinguish-multiple-error-types-(format,-expiration,-invalid-signature,-etc)
- after-success-inject-principal-into-request-context-for-subsequent-middleware-and-business-to-use
- key-behaviors
- strictly-validate-header-format-and-signature-method
- use-v5-error-type-determination-to-precisely-return-error-information
- write-userid,-role-and-other-information-to-context-key-values
- typical-call-chain
- key-functional-points
- read-username-from-context-(injected-by-jwt-middleware)
- construct-resource-and-action-from-request-path-and-method
- call-casbin-enforcer-to-execute-authorization-decision
- key-behaviors
- return-403-on-authorization-failure
- return-500-on-authorization-check-exception
- continue-chain-after-pass
- typical-call-chain
- key-functional-points
- read-clientid,-signature,-nonce,-timestamp-from-request-headers
- validate-timestamp-window,-nonce-deduplication,-signature-verification-(rsa-pss-sha256)
- optional-signature-cache-to-improve-performance
- write-clientid-to-context-after-pass
- key-behaviors
- return-401-directly-if-required-headers-missing
- return-401-for-timestamp-out-of-bounds,-duplicate-nonce,-signature-failure
- write-random-number-to-storage-and-set-expiration
- skip-verification-if-cache-hit
- typical-call-chain
-
authorization-component-responsible-for-centralized-registration-and-naming-of-middleware,-facilitating-on-demand-enabling-and-combination
-
app-creates-gin-engine-and-mounts-middleware-chain-at-startup,-supports-graceful-shutdown-and-subprocess-management
-
middlewares-are-coupled-through-context-and-order:-jwt-depends-on-principal-injection;-casbin-depends-on-username-injected-by-jwt;-rsa-as-preposition-is-independent-of-jwt/casbin
-
authentication-abstraction-and-implementation-decoupling:-rsaauthconfig-defines-interfaces,-memory*-implementations-provide-high-performance-in-memory-caching-and-cleanup
-
configuration-driven:-casbinconfig-and-appconfig-inject-runtime-behavior-through-configuration-files
-
signature-cache-and-nonce-deduplication
- rsa-middleware-through-signaturecache-and-noncestore-caching-and-deduplication,-significantly-reducing-cpu-overhead-and-database-pressure-for-duplicate-requests
- in-memory-implementations-have-built-in-periodic-cleanup-goroutines,-avoiding-unlimited-growth
-
time-window-control
- control-timestamp-tolerance-through-timewindow,-balancing-security-and-usability
-
middleware-order-optimization
- place-lightweight-prepositions-(such-as-rsa)-at-chain-head,-reducing-subsequent-middleware-burden
-
concurrency-and-lock-granularity
- memory*-implementations-use-mutexes-to-protect-shared-state,-note-in-high-concurrency-scenarios-appropriately-extend-to-persistent-storage-or-distributed-cache
-
jwt-middleware-common-issues
- missing-or-malformed-authorization-header:-return-401
- token-format/signature/expiration/not-yet-effective:-return-clear-errors-based-on-v5-error-types
- suggestion:-uniformly-intercept-and-record-detailed-context-(ip,-user-agent,-trace-id)-at-gateway-layer
-
casbin-middleware-common-issues
- context-not-injected-with-username:-usually-caused-by-jwt-not-passing
- policy-model/policy-file-configuration-error:-check-casbinconfig's-model_path-and-policy_path
-
rsa-middleware-common-issues
- missing-request-headers-or-signature-format-error:-return-401
- timestamp-out-of-bounds:-check-client-clock-synchronization
- duplicate-nonce:-confirm-if-noncestore-correctly-writes-and-expires
- suggestion:-enable-signature-cache-to-reduce-duplicate-request-overhead
this-security-middleware-system-implements-a-complete-closed-loop-from-client-signature-authentication,-token-authentication-to-fine-grained-authorization-through-clear-responsibility-separation-and-pluggable-configuration.-combined-with-in-memory-caching-and-reasonable-execution-order,-good-performance-can-be-achieved-while-ensuring-security.-suggested-to-combine-with-configuration-files-and-observability-means-in-production-environment,-continuously-optimizing-middleware-chain-and-resource-configuration.
appendix
middleware-configuration-options-overview
-
jwt
- dependent-key-(hs256),-loaded-at-application-startup
-
casbin
- model_path:-policy-model-file-path
- policy_path:-policy-rule-file-path
-
rsa
- clientidheader,-clientsignatureheader,-nonceheader,-timestampheader:-request-header-names
- timewindow:-timestamp-tolerance-(seconds)
- publickeyprovider:-public-key-provider-(can-be-in-memory-or-external-storage)
- noncestore:-nonce-storage-(can-be-in-memory-or-external-storage)
- signaturecache:-signature-cache-(can-be-in-memory-or-external-storage)
-
custom-middleware-development
- follow-gin-middleware-specifications:-gin.handlerfunc
- clear-error-handling-and-status-code-return
- pass-necessary-information-through-context-(such-as-principal,-clientid)
-
middleware-combination-patterns
- preposition-strong-validation-(rsa)-→-token-parsing-(jwt)-→-authorization-(casbin)
- can-insert-audit,-rate-limiting,-circuit-breaking-middleware-as-needed
-
exception-handling-best-practices
- add-degradation-and-timeout-control-for-external-dependencies-(casbin,-cache)
- record-structured-logs-(requestid,-middleware-stage,-time-consumed,-error-code)
- add-audit-logs-for-sensitive-operations-(username,-resource,-action,-result)
practical-deployment-suggestions
- multi-middleware-chain
- place-rsa-at-chain-head,-jwt-second,-casbin-at-tail
- for-public-interfaces-can-only-enable-rsa,-internal-interfaces-enable-jwt-+-casbin
- performance-impact-analysis
- duplicate-requests-can-significantly-reduce-cpu-and-io-through-signaturecache-and-noncestore
- high-concurrency-scenarios-suggest-replacing-in-memory-implementation-with-distributed-cache
- security-audit-logs
- record-input-output-summaries-at-each-middleware-stage-(excluding-sensitive-body)
- add-alerts-and-tracing-for-401/403/5xx