Subjects¶
A subject is a registered identity in the Keyserver. Every API call and UI action is performed by a subject, and a subject's roles determine what it may do. There are two types: users and clients.
Subjects are not accounts¶
A subject is the Keyserver-side record of an identity that already exists in the authorization server. Creating a subject creates no credentials: the person or system must first exist in your identity provider, which issues its tokens. The trial Authserver has no facility to register new identities, so on a trial you edit the seeded subjects instead of creating new ones.
Users¶
A user is a person who logs in to the Keyserver UI. Users typically:
- Approve pending operations, or cancel them with Revoke, in the approval workflow
- Administer keys, roles, and subjects during an administrative session
- Review the audit log
Users authenticate with the OAuth2 Authorization Code Flow (browser redirect) against your identity provider, for example Azure Entra ID. A provisioning station where an operator logs in (Authorization Code + PKCE) is also a user. See Users: Authorization Code Flow.
Clients¶
A client is a non-interactive system, such as a CI/CD pipeline, a headless provisioning tool, or a build server. It authenticates with OAuth2 Client Credentials or a federated CI job token, and calls the REST API or the PKCS#11 interface. See Clients: Client Credentials Flow.
Subject registration¶
An administrator registers each subject. See Create a subject. A valid token is not enough on its own: a token whose identity matches no registered subject is rejected with 401. See Diagnosing 401 vs 404 vs 403.
Token-to-subject mapping¶
A subject has two identifying fields: Subject ID, the identity provider's stable identifier that is matched against the token, and Subject name, a human-readable label. Which token claims are used is configured per identity provider.
Users:
- On every login, the token's user-ID claim (for example
oidorsub) is matched against Subject ID. - On a user's first login, when no Subject ID matches, the username claim (for example
preferred_username) is matched against Subject name. On a match, the user-ID claim is written into Subject ID for later logins. Later logins overwrite Subject name with the username claim. - User logins do not use wildcards.
Subject ID matching ignores case: FW-CLIENT and fw-client are the same Subject ID. Creating a subject whose Subject ID differs from an existing one only in case is refused with 409 "Subjectid already exists".
Clients:
- The provider's service-ID claim is matched against Subject ID. The trial Authserver uses
sub, which carries an MD5 hash of the client ID (forfw-client,cf6faf7065a6bceb95460a733002dce3). Entra ID usesazp, the app registration's Application (client) ID. GitLab CI usessub, for exampleproject_path:group/project:ref_type:branch:ref:main. Copy the value from an issued token rather than retyping it. - If no Subject ID matches in full, a Subject ID ending in
*matches any claim value that starts with the text before the*. The prefix is compared ignoring case. Rules and examples: Wildcard Subject IDs for clients.
flowchart TD
T["Valid token"] --> SA{"Client (service account) token?"}
SA -->|yes| C["Match the provider's service-ID claim<br/>against Subject ID"]
SA -->|no| U["Match the user-ID claim<br/>against Subject ID"]
U -->|no match| F["First login: match the username claim<br/>against Subject name, then store<br/>the user ID as Subject ID"]
C -->|match| OK["Subject found: its roles apply"]
U -->|match| OK
F -->|match| OK
C -->|no match| R["401 The user/client is not valid"]
F -->|no match| RDiagram: Valid token; Client (service account) token?; yes; Match the provider's service-ID claim against Subject ID; no; Match the user-ID claim against Subject ID; no match; First login: match the username claim against Subject name, then store the user ID as Subject ID; match; Subject found: its roles apply; 401 The user/client is not valid
Related pages¶
- Manage Subjects: creating, editing, and deleting subjects, including what deletion does to the name
- Roles: what a subject's roles grant