RFC: Extend Admin API to support multiple personas

[fitzthum]

Today the admin configuration of Trustee is very basic. It only has two fields; a path to a public key representing a singular Trustee admin, and a flag to disable checking the admin private key.

Enterprise use cases will require more sophisticated admin configurations with multiple personas, roles, identities, etc. I have some ideas about how we can introduce these features.

Decoupled Admin Backend

Today what few admin configurations we have come from the Trustee config file. In the future, admin information could be specified in the config file, but it could also come from some other service such as LDAP. In many parts of Trustee we already have a modular backend pattern. We should adopt something similar for admin. The default can be a local admin provider where the admin config comes directly from the Trustee config. Other admin providers can use the Trustee config to store information about connecting to an external admin service.

The exact API of the admin backend isn't yet clear, but the next sections will help to understand some of the requirements.

Multiple Admin Personas, Roles, and Identities

There are a lot of things we could do with a more sophisticated admin config. Some things would require significant changes to other parts of Trustee, but some would not.

The simplest possible change would be to support multiple admins, which all have the same capabilities. As soon as we have multiple admins, we probably want to have some kind of admin ID so that we can track (at least in the logs) who did what.

We should probably introduce some kind of admin roles. In the short term these roles can simply allow access to combinations of API endpoints. There can be a role for resources, a role for policies, etc. In the longterm we can think about deeper integrations for roles and maybe even try to figure out some form of multi-tenancy.

Authentication Modes

Today, authenticating to Trustee with the KBS client is a somewhat annoying. You must provide the admin private key to the KBS-Client. It can be annoying to specify this path every time and although it is secure, some people get a little bit scared by dealing with the private key.

In the short term, we could hide this by creating some local kbs-client config that stores your login information (like with Docker) . We should also think about how a modular admin backend would work with logging in. Authenticating a user will probably be delegated to the backend, meaning that the information required to login could be different for different backends. We'll need to make our authentication mechanism flexible enough to handle this.

[bpradipt]

Would it make sense to add an oauth proxy layer and let the auth be handled via that for advanced usage?

[fitzthum]

@bpradipt yeah I think we could have an oauth admin backend using scopes for different roles.

[mkulke]

casbin looks like a good candidate for a simple RBAC authz (not authN), they do provide an actix-web middleware

[fitzthum]

I wonder if we should implement the admin logic as actix middleware or keep calling the admin code explicitly. We use one actix method to handle admin and non-admin endpoints (it's up to the plugin author to specify if an endpoint requites admin), which might not be a great fit for the middleware approach.

[Xynnn007]

I think we can first clarify what the Admin black box logic should look like - that is, what is the interface that administrators call and how to express their identity; then we can define specific solutions

[fitzthum]

I think a first step can be to introduce an admin API and a simple config backend. This would basically have the same behavior that we currently have. We can then extend this to allow multiple admin to be specified. After that we will probably need to introduce some kind of admin session to support more sophisticated backends and allow admin to only login once per connection.

[Xynnn007]

As the PR process progressed, I gradually became aware of some more fundamental questions about the design.

To summarize my position: I think it makes sense for Trustee to do some AuthZ, but not AuthN in the core.

As the PR #1025 is not flourish validate_admin_token API, but also tries to bring in a new generate_admin_token API which is actually in authN scope. This raise my concerns.

The main reasons are:

1. Scope and responsibility of Trustee

Trustee is primarily an attestation/trust service, not an identity provider (I mean the usual admin identity. Guest/container identity based on attestation is still in scope).

AuthN (who you are / how you log in) is better handled by dedicated IdPs or sidecars.
Trustee should focus on verifying tokens and making minimal authorization decisions, not managing login flows and credentials.

2. Complexity and long-term maintenance

Verifying a token is relatively simple: check signature, issuer, expiry, and claims.
Issuing tokens and handling logins is more complex, even if we "just proxy" to external services:

We must care about protocol details (OAuth2/OIDC/etc.), redirects, CSRF, error handling;
we need to maintain the libraries, config, integration tests, and documentation over time;
once Trustee becomes the login/token-issuing entry point, users will expect us to own the security properties of that flow.

3. Built-in security vs. full login experience

I agree Trustee needs built-in, default security for admin APIs, without forcing everyone to deploy extra services.

Today, a simple admin token already gives a non-naked default protection.
We can extend this with signed tokens and minimal, config-driven AuthZ based on claims (e.g., roles → allowed APIs).
This covers “secure by default” without turning Trustee into a full login system.

4. AuthZ in Trustee, keep it small

I think Trustee should:

verify admin tokens in the core;
implement minimal, configurable AuthZ based on token claims (e.g., simple mapping from role/claims to allowed endpoints).
More complex AuthZ (multi-tenant, rich RBAC/ABAC, enterprise policies) is better handled by external services that issue the tokens and define the roles/claims. Trustee just consumes those claims.

5. External or sidecar AuthN for those who need login

For users who want a "login experience" (username/password, OAuth2/OIDC, LDAP, etc.), my view is:

a separate auth service or sidecar can handle login and token issuance;
Trustee just verifies the issued token (public key or issuer configured ahead of time).
This keeps the core cleaner and lets different deployments choose the auth stack that fits their environment.

In short:

Yes: Trustee should have minimal built-in AuthZ and token verification for admin protection.
No: Trustee core should not take on full AuthN and token issuing logic.

Whether we want to support a full "single-binary login experience" inside Trustee is, in my opinion, the key product question behind the two designs (my proposal is above, while @fitzthum wants to integrate both authN and authZ of admin API into trustee).

I think it's important to get broader feedback from the TSC and users on this before we decide which direction the project should take.

[Xynnn007]

cc @confidential-containers/trustee-maintainers

[pmores]

@Xynnn007 I can agree with most of what you say but it's stated fairly generally (i.e. I'm not quite clear on what is considered "full AuthN") - could you spell out the actual proposal more explicitly? Provided I'm not missing anything we have

• the simple auth plugin (merged with Add Pluggable Admin Backends to KBS #1014)
• the username/password auth plugin (under review in Allow admins to login with a username and password #1025)
• no further local auth methods planned afaik (I think @fitzthum stated OAuth2 would be next which doesn't qualify as trustee doing full AuthN I guess).

So is the proposal to drop the username/password plugin (essentially #1025)? Or the key-based auth part of #1014 too? If it's to drop username/password and keep key-based auth then I would say, if we are to keep only one simple local auth method I'd probably vote for the username/password one since it seems much more user-friendly - a lot of folks don't feel comfortable generating keys, and then there's the hassle with properly storing the private key, compared to just running argon2 and putting two strings into the config file.

[fitzthum]

I appreciate the concerns about complexity and maintenance, especially in such a security-sensitive area, but I think we're overlooking a few key things here and ultimately miscalculating the tradeoffs.

The big question is whether we want Trustee to provide an admin_login interface. Note that this is different from Trustee actually being a authentication service. Login requests would be proxied to external services, with one simple fallback option (password backend) for users that don't want to setup an external authentication service.

If we do not provide an admin login interface, users will face significant problems. First, users who don't have an external authentication service, won't have a good way to login (the simple backend is not a good way to login). We support deploying Trustee as a single, standalone binary. It's not realistic to expect users to setup an authentication service alongside of that to be able to do something as fundamental as admin login. In a recent Trustee meeting concerns were raised about introducing a database dependency. This would be far more complicated dependency than that.

Second, without an admin login interface, the user experience is bad. To make an admin request, the user would first have to login to some external service. They would need to save the token from this service and then provide it to the KBS Client when making an admin request. This is more complicated than the existing auth flow, which users already struggle with. With an admin login interface, you would login once (per token lifetime) with the kbs-client and the rest would be seamless. The user would never even see the token. They wouldn't have to know anything about which authentication service is being used.

Third, if we don't provide an admin login interface, we will still have to maintain an admin login flow. Some of the concerns above are about having to do more documentation, testing, and maintenance. This isn't really a fair comparison. If we don't have an admin login interface, we will still need to have rigorous admin flows in our deployments (docker compose, operator, helm chart, etc). We will need to test those flows and document them. Things might actually be more complicated without an admin login interface because the flow for a user is more complicated (see above) and because there is no password backend to fall back on.

Overall, let's not mischaracterize creating an admin login interface as adding a bunch of scary DIY crypto code. The admin login interface would use standard, mature protocols to forward authentication requests to the appropriate service. Of course we should be careful here (especially with the password backend, which is a little more complex, but still reasonable), but overall this is one of the simplest parts of the flow.

Finally, and perhaps most importantly, the admin login interface gives us flexibility. There is nothing prescriptive here. If we add an admin login interface, an admin backend doesn't have to implement it. So we could easily create backends that do exactly what Ding is suggesting (just validate tokens). Furthermore, if someone wants to use a k8s-based gateway, they could disable authentication altogether. The admin login interface gives us more options, including one with no dependencies, that is easier to use than what we currently have or anything that has been proposed, but you don't have to use any of them. Only one admin interface is allowed at a time, so it's easy to set whatever configuration you want. Ultimately, if we don't provide any way for Trustee to generate admin tokens (despite requiring them for admin endpoints), we will probably find that very annoying.

[Xynnn007]

@pmores

Yes my idea is not highlight thus easy to miss in the last comment ; (.

To summarize my position: I think it makes sense for Trustee to do some AuthZ, but not AuthN in the core.

s.t. we'd better not care about how to provision tokens in trustee (thus no ``), but we can do (limitedly) how to validate tokens via validate_admin_token.

More specifically, I hope KBS won't have username/password logic. Your question mentioned the issue of generating and managing keys, and I agree with you; managing public and private keys is complex.

However, this problem won't be improved by introducing username/password, because the trustee still needs to maintain a private key for signing tokens.

Conversely, regarding security requirements, if your KBS deployment does require admin authentication, we can adopt another excellent practice from #1025: kbs-client can use a token directly than the private key to do admin auth and the login token can be placed in a fixed directory. This way, the kbs-client doesn't need to maintain a private key, only a token. For convenience, we can place the token generation logic within the KBS startup logic (e.g., the initContainer logic).