robsonkades/agent-skills/service-identity-and-trust

Service Identity and Trust

Decide which remote caller may cause which effect, under whose authority, and how that decision remains enforceable when credentials, policies or dependencies change. A valid workload identity establishes a principal; permission still depends on the operation, resource, tenant and applicable delegation policy.

Scope and compatibility

Own the trust graph, identity semantics, credential lifecycle and placement of enforcement between workloads. Preserve an adequate existing mechanism. Neither a mesh nor SPIFFE, OAuth, a central policy engine or a separate identity platform is required by this skill. Do not replace a local call with a remote authentication protocol without a trust boundary.

The architecture is independent of Java and Spring versions. Before recommending APIs, inspect compiler/toolchain settings, resolved Boot/Security/client-library versions, runtime images and deployed proxy/provider capabilities. This package contains a conceptual policy example, no executable Java or Spring configuration. Framework examples from other skills retain their declared baselines; adopting this skill does not authorize upgrades.

For Servlet filters, token validators and method interception, optionally use spring-security-for-apis. For code-level tenant/instance authorization and its consistency with a write, use java-application-security-basics. Pass the identities, credential profile, allowed operations, reachable paths and required hostile tests. These optional handoffs do not excuse an incomplete authorized implementation; use existing project conventions and version-matched primary sources if a specialist is unavailable. Password storage, browser login and building an authorization server are separate tasks.

Discover the actual trust graph

Start with the affected call and protected effect; expand only to paths that can reach or bypass it. Inspect source and deployment configuration before asking for missing facts.

1. Follow every entry path. Include gateways, direct service addresses, alternate ports,

management endpoints, scheduled jobs, message consumers and support tools. Mark TLS termination and re-encryption, which peer the application actually authenticates, and who can reach a listener without the intended proxy. A diagram is a claim to check against listeners, network policy and a representative request path.

1. Name identities separately. Record the workload executing the call; the user or

system subject whose authority is used; the current delegate, if any; and the tenant whose resources are addressed. Identify their trusted sources and namespace/issuer. A tenant selector in a URL or body is input to authorization, not proof of membership. Service names, email addresses and subject strings from different issuers can collide. Within one issuer, distinguish client and user subjects using its trusted issuance contract before granting user rights; a signed sub or matching user record is insufficient.

1. Trace issuance and consumption. Inspect trusted issuers or CA bundles, audiences,

token/certificate profiles, client registration or workload attestation, permissions, key custody, credential lifetime and caches. Determine who can grant a workload an identity; authentication cannot compensate for an overbroad issuance policy.

1. Find policy ownership. Identify who defines delegation rights and who owns the

resource/tenant decision. Inspect actual enforcement and denial paths, including authorization caches. Record revocation targets and acceptable security-state staleness separately from availability objectives; neither implies the other.

1. Separate evidence from assumptions. Sanitized configuration supports configuration

claims; it does not prove production reachability or refresh behavior. If topology, issuance authority or the permission contract is missing, name the missing evidence and keep dependent decisions conditional. Continue mapping known paths; do not invent trusted issuers or grant all callers access to unblock progress.

Never collect private keys or live bearer tokens for a design review. Redact credentials and unnecessary personal claims in captures; use synthetic principals for validation.

Choose the identity and authority contract

Choose mechanisms against the observed boundary, deployment capability and lifecycle cost. They can compose: workload authentication and user authorization answer different questions.

Use audience and privilege restriction to limit where a credential is useful, following OAuth Security BCP, sections 2.2–2.3. A bearer token can be replayed by its holder. Where theft/replay is material, evaluate a supported sender-constrained mechanism and its end-to-end binding, not just an extra TLS hop.

When choosing token relay/exchange, certificate identities, federation or validation caches, read protocol and lifecycle contracts. It explains which protocol guarantees can support the architecture and which remain deployment policy.

Put enforcement at the protected boundary

• Authenticate the evidence before trusting its claims. Select issuers, key sources,

token profiles and CA bundles from trusted configuration. For JWTs, verify the agreed signature/algorithm, issuer, intended audience and time/profile rules; for opaque tokens, use the trusted introspection contract and applicable claim checks. For certificate authentication, enforce the selected profile's proof-of-possession and trust checks. PKI identities require a valid chain and expected peer; an explicitly supported profile of registered certificates uses trusted client binding instead. Do not relax PKI checks on other paths. An incoming iss, jku, certificate header or discovery result does not grant itself authority. An ID token is not an API access token.

• Make proxy trust explicit. A gateway assertion is acceptable only over a protected

route from an authenticated, authorized assertion producer, with client-supplied identity headers stripped/replaced and bypass paths excluded or independently protected. If TLS ends at a proxy, establish how validated caller identity reaches the application. A forwarded certificate string is not proof of possession. Test direct access with forged identity headers; an internal network label is insufficient evidence.

• Authorize both the actor relationship and the effect. A trusted payments service

does not thereby gain every user's refund rights. Validate who may represent whom and for which operation; enforce the resource's tenant/owner and business invariant at a boundary all relevant entry paths cross. Central policy may decide shared rules, but the effect owner must enforce the decision against the actual resource and current state. If state changes between check and write, preserve the policy with the required transaction, version predicate or conditional mutation.

• Keep transport types at integration boundaries. In Java/Spring, map validated caller

data into the small trusted context the application operation needs. Do not pass raw Jwt, servlet requests or credentials throughout a domain model. An immutable context is useful but does not prove provenance; only trusted adapters may construct its security assertions. Recheck paths that bypass Spring proxies and lost or copied security context across executors. A thread-local context does not cross a network.

• Handle asynchronous authority deliberately. Broker authentication identifies the

connection's workload, not automatically the original user behind a payload. Decide whether a message carries an already-authorized business fact or requests a future effect that needs current authorization. Record provenance and tenant binding using the agreed producer/consumer contract; do not store a user's bearer token for indefinite replay. Delayed commands require an explicit authority and expiry/revalidation policy.

Conceptual policy pseudocode, not a token verifier or executable Java:

permit refund only if
  verified caller is an allowed refund delegate
  AND verified subject may request this refund
  AND requested tenant equals the resource tenant and is allowed for this subject
  AND actor is allowed to represent this subject for this operation
  AND refund invariant still holds at the protected mutation

A batch reconciliation operation can instead use bounded system authority without a user. Changing that requirement must change the identity contract; do not force delegation into every background task or silently replace user authority with a powerful service account.

Deliver and validate the contract