Skip to content

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:

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 oid or sub) 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 (for fw-client, cf6faf7065a6bceb95460a733002dce3). Entra ID uses azp, the app registration's Application (client) ID. GitLab CI uses sub, for example project_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| R

Diagram: 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


  • Manage Subjects: creating, editing, and deleting subjects, including what deletion does to the name
  • Roles: what a subject's roles grant