This is an automated email from the ASF dual-hosted git repository.
hsluoyz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/casbin-caddy-authz.git
The following commit(s) were added to refs/heads/master by this push:
new 20554ca fix: improve README with authz and authn
20554ca is described below
commit 20554ca64d6d0a3c01fb7ed2d0fcf232ccc09576
Author: Yang Luo <[email protected]>
AuthorDate: Sat Apr 25 14:49:05 2026 +0800
fix: improve README with authz and authn
---
README.md | 39 ++++++++++++++++++++++++++++++++++++---
authz.go | 8 ++++----
authz_test.go | 1 +
3 files changed, 41 insertions(+), 7 deletions(-)
diff --git a/README.md b/README.md
index b1f567b..760b83a 100644
--- a/README.md
+++ b/README.md
@@ -59,18 +59,51 @@ The `authz` directive takes two arguments:
For how to write these files, refer to the [Apache Casbin
documentation](https://casbin.apache.org/docs/get-started).
+## Security: Authentication vs Authorization
+
+> **⚠️ Important:** This plugin handles **authorization only** — it does NOT
validate passwords or verify user identity.
+>
+> You **must** place an authentication middleware **before** this plugin to
verify credentials. Without it, anyone can set an arbitrary `Authorization`
header and impersonate any user.
+
+This plugin is designed to be used alongside a dedicated authentication layer:
+
+```
+localhost:8080 {
+ route {
+ basicauth { # ← Step 1:
Authentication (validates credentials)
+ alice $2a$14$Zkx19XLiW6VYouLHR5NmfOFU0z2GTNmpkT/5qqR7hx4IjWJPDhjvG
+ }
+ authz "authz_model.conf" "authz_policy.csv" # ← Step 2:
Authorization (checks permissions)
+ respond "Hello, world!"
+ }
+}
+```
+
+Caddy's built-in
[`basicauth`](https://caddyserver.com/docs/caddyfile/directives/basic_auth)
directive is recommended for HTTP Basic Authentication. For other schemes
(OAuth, JWT, LDAP, etc.), use the appropriate authentication plugin and ensure
it runs before `authz`.
+
+If you need to validate credentials programmatically, set the
`CredentialValidator` hook before the server starts:
+
+```go
+import authz "github.com/apache/casbin-caddy-authz/v3"
+
+func init() {
+ authz.CredentialValidator = func(username, password string) bool {
+ // query your database or LDAP here
+ return myDB.CheckPassword(username, password)
+ }
+}
+```
+
## How Access Control Works
Authorization is determined based on `{subject, object, action}`:
| Field | Meaning |
|-------|---------|
-| `subject` | The logged-in user name (from HTTP Basic Auth header) |
+| `subject` | The authenticated user name (extracted from HTTP Basic Auth
header) |
| `object` | The URL path of the requested resource, e.g. `dataset1/item1` |
| `action` | The HTTP method, e.g. `GET`, `POST`, `PUT`, `DELETE` |
-> **Note:** This plugin reads the user name from the HTTP `Authorization`
header using Basic Auth. If you use other authentication methods (OAuth, LDAP,
JWT, etc.), you will need to customize the plugin.
-
## Working Example
1. Build Caddy with this plugin using
[xcaddy](https://github.com/caddyserver/xcaddy):
diff --git a/authz.go b/authz.go
index 2f5087e..402e21b 100644
--- a/authz.go
+++ b/authz.go
@@ -24,10 +24,10 @@ func init() {
type Authorizer struct {
AuthConfig struct {
- ModelPath string
- PolicyPath string
- }
- Enforcer *casbin.Enforcer
+ ModelPath string `json:"model_path"`
+ PolicyPath string `json:"policy_path"`
+ } `json:"auth_config"`
+ Enforcer *casbin.Enforcer `json:"-"`
}
// CaddyModule returns the Caddy module information.
diff --git a/authz_test.go b/authz_test.go
index b3c264c..4a39cf2 100644
--- a/authz_test.go
+++ b/authz_test.go
@@ -37,6 +37,7 @@ func initTester(t *testing.T) {
{
http_port 9080
https_port 9443
+ admin localhost:2999
}
localhost:9080 {
route /* {
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
