diff --git a/weed/command/filer.go b/weed/command/filer.go
index 1cf033f55a..f791deacc8 100644
--- a/weed/command/filer.go
+++ b/weed/command/filer.go
@@ -506,12 +506,9 @@ func (fo *FilerOptions) startFiler() {
 	grpcS := pb.NewGrpcServer(security.LoadServerTLS(util.GetViper(), "grpc.filer"))
 	filer_pb.RegisterSeaweedFilerServer(grpcS, fs)
 
-	// Register the IAM gRPC service. Auth is opt-in: when
-	// jwt.filer_signing.key is configured the service requires a Bearer token
-	// signed with that key; otherwise it runs unauthenticated, matching the
-	// rest of the filer's gRPC surface. Operators who expose the filer gRPC
-	// port beyond a trusted network should set jwt.filer_signing.key on both
-	// the filer and the admin server.
+	// IAM RPCs require a Bearer token signed with jwt.filer_signing.key when it
+	// is set. The key does not protect the rest of this port; that needs
+	// [grpc.filer] mTLS.
 	if credentialManager != nil {
 		adminSigningKey := security.SigningKey(util.GetViper().GetString("jwt.filer_signing.key"))
 		iamGrpcServer := weed_server.NewIamGrpcServer(credentialManager, adminSigningKey)
diff --git a/weed/command/scaffold/security.toml b/weed/command/scaffold/security.toml
index f412765b2f..b347d818a2 100644
--- a/weed/command/scaffold/security.toml
+++ b/weed/command/scaffold/security.toml
@@ -57,9 +57,11 @@ expires_after_seconds = 10           # seconds
 #       CreateAccessKey, ...). When set, every IAM RPC must carry a Bearer
 #       token signed with this key in its "authorization" gRPC metadata; mint
 #       such a token with security.GenJwtForFilerAdmin. When empty, the IAM
-#       gRPC service runs unauthenticated, like the rest of the filer's gRPC
-#       surface — set the key on both filer and admin if the gRPC port is
-#       reachable beyond a trusted network.
+#       gRPC service runs unauthenticated and refuses its OIDC provider and
+#       role RPCs. When set, set it on both filer and admin.
+#       The key does not protect the other filer gRPC RPCs, which can read and
+#       write the IAM store under /etc/iam; if the filer gRPC port is reachable
+#       beyond a trusted network, enable [grpc.filer] mTLS below.
 # the jwt defaults to expire after 10 seconds.
 [jwt.filer_signing]
 key = ""
diff --git a/weed/server/filer_server_handlers_iam_grpc.go b/weed/server/filer_server_handlers_iam_grpc.go
index be98356614..508dcd2c3b 100644
--- a/weed/server/filer_server_handlers_iam_grpc.go
+++ b/weed/server/filer_server_handlers_iam_grpc.go
@@ -17,11 +17,11 @@ import (
 )
 
 // IamGrpcServer implements the IAM gRPC service on the filer.
-// Auth is opt-in: when jwt.filer_signing.key is set in security.toml the
-// service requires a Bearer token in the "authorization" metadata signed with
-// that key; when it is empty every RPC is accepted unauthenticated, matching
-// the rest of SeaweedFS's gRPC surface. Operators who expose the filer gRPC
-// port beyond a trusted network should configure the key.
+// When jwt.filer_signing.key is set, every RPC requires a Bearer token signed
+// with it; otherwise RPCs run unauthenticated, except the OIDC provider and
+// role RPCs, which are refused. The key gates only this service: the filer RPCs
+// on the same port can still read and write the IAM store under /etc/iam.
+// Protect a filer gRPC port reachable by untrusted clients with [grpc.filer] mTLS.
 type IamGrpcServer struct {
 	iam_pb.UnimplementedSeaweedIdentityAccessManagementServer
 	credentialManager *credential.CredentialManager