Fixed app session start audit events for Device Trust failures

[21KennethTran]

When Device Trust and MFA is enabled for accessing a resource and a user without a trusted device tries to access that resource, their session should get rejected and an auth attempt fail event is generated in the audit log.

Since this type of session rejection is an auth failure, the type of event generated in the audit logs should be an AppSessionStart. The AppMetadata struct is added to this to provide more information about the resource the user tried to access.

Following the recreation steps from #54139 ,

Before:

device-trust-before.mov

After:

device-trust-after2.mov

Here is the audit log fields with the changes from the demo above:

{
  "app_name": "debug-app",
  "app_public_addr": "debug-app.localhost",
  "app_uri": "http://localhost:8000/",
  "cluster_name": "localhost",
  "code": "T2007E",
  "ei": 0,
  "error": "access to resource requires a trusted device",
  "event": "app.session.start",
  "message": "access to application debug-app requires a trusted device",
  "namespace": "default",
  "public_addr": "",
  "server_id": "4948fc26-21e7-4aaf-a45b-02b39d392a0d",
  "server_version": "19.0.0-dev",
  "sid": "",
  "time": "2026-01-21T00:27:54.033Z",
  "uid": "b53c7358-bdc9-4a99-94a7-0a56477fa2f1",
  "user": "kenneth.tran@goteleport.com",
  "user_cluster_name": "localhost",
  "user_kind": 1,
  "user_roles": [
    "access",
    "editor",
    "mfa-device-trust",
    "require-trusted-device"
  ],
  "user_traits": {
    "acr": [
      "1"
    ],
    "at_hash": [
      "_J7AxLN1qCDTGoeMQp5y8Q"
    ],
    "aud": [
      "teleport-oidc"
    ],
    "azp": [
      "teleport-oidc"
    ],
    "email": [
      "kenneth.tran@goteleport.com"
    ],
    "family_name": [
      "tran"
    ],
    "given_name": [
      "kenneth"
    ],
    "groups": [
      "teleport-admins"
    ],
    "iss": [
      "https://localhost:8443/realms/teleport"
    ],
    "jti": [
      "38610d7d-fad0-c7de-03c2-60b1b4cacd4c"
    ],
    "name": [
      "kenneth tran"
    ],
    "preferred_username": [
      "kenneth-keycloak"
    ],
    "sid": [
      "3c62224c-e0bf-37b9-5c57-a76a2dd53550"
    ],
    "sub": [
      "80814091-50d6-4214-8b23-229a1f13c596"
    ],
    "typ": [
      "ID"
    ],
    "username": [
      "kenneth-keycloak"
    ]
  },
  "with_mfa": "77879faa-6ed8-4799-8b0e-e46af9f3facb"
}

changelog: Reject application session requests and emit a failed session start audit event when a trusted device is required but not provided

[zmb3]

The PR title could be more descriptive. It refers to "session start" events, but the change is actually about preventing "app session start" events from being emitted for sessions that are unsuccessful.

[zmb3]

I wonder if we should change this doc comment.

Are there any cases where this is being emitted on success?

[21KennethTran]

There doesn't seem to be any instances where an AuthAttempt has a success in the code field. It seems that successful events have more granular types and success codes. I will change the doc comment for more clarity.

[zmb3]

@codingllama do you think this is the right place to check whether a trusted device credential is being presented?

Context:

Prior to this change, when an app session is rejected due to device trust, the request traverses through the proxy, and the app agent itself sends back an HTTP response saying that device trust is required (instead of connecting to the app).

The problem is from the proxy's perspective, traffic is being routed to an agent, so an app session start event gets emitted. This is a problem for cases when you alert on accesses that come from untrusted devices (which is somethign we do internally!)

[codingllama]

I don't mind the early check, but I dislike the addition (and duplication!) of authz-related device trust logic to this handler. I think this is the responsibility of the AccessChecker, so I would prefer an early CheckAccess if possible, like you suggested above.

If for some reason that doesn't work, then we could expose an AccessChecker.CheckDeviceAccess method instead.

WDYT?

[21KennethTran]

I opted to expose an AccessChecker.CheckDeviceAccess method since we don't have an app session to use CheckAccess on yet at this point. Let me know if this implementation looks good!

[zmb3]

This looks very similar to (RoleSet).checkAccess():

		// Device verification.
		var deviceVerificationPassed bool
		switch role.GetOptions().DeviceTrustMode {
		case constants.DeviceTrustModeOff, constants.DeviceTrustModeOptional, "":
			// OK, extensions not enforced.
			deviceVerificationPassed = true
		case constants.DeviceTrustModeRequiredForHumans:
			// Humans must use trusted devices, bots can use untrusted devices.
			deviceVerificationPassed = deviceTrusted || state.IsBot
		case constants.DeviceTrustModeRequired:
			// Only trusted devices allowed for bot human and bot users.
			deviceVerificationPassed = deviceTrusted
		}
		if !deviceVerificationPassed {
			logger.LogAttrs(ctx, logutils.TraceLevel, "Access to resource denied, role requires a trusted device",
				slog.String("role", role.GetName()),
			)
			return ErrTrustedDeviceRequired
		}

I wonder if we should be running the access check sooner rather than duplicating some of its code here?

[21KennethTran]

That is true. I am not sure if we really need all of the other checks in roleset.checkAccess() like label matching or login usernames, before issuing an app session certificate, which from my understanding comes from the Auth server. The access checks comes after the proxy connects to the app service, which should be when authorization takes place.

Let me know if doing the access checks earlier would be the better choice here. I could also refactor the device trust section into a utility function to use in these two parts.

[zmb3]

Should we omit ServerMetadata here since we know the access attempt was for an app, and we have app metadata below?

[21KennethTran]

ServerMetadata tells what specific Auth server emitted the event, which could be useful for audit logs? I also chose to include this to mirror the AppSessionStart emitted in the same function on a successful event.

[codingllama]

I don't mind the early check, but I dislike the addition (and duplication!) of authz-related device trust logic to this handler. I think this is the responsibility of the AccessChecker, so I would prefer an early CheckAccess if possible, like you suggested above.

If for some reason that doesn't work, then we could expose an AccessChecker.CheckDeviceAccess method instead.

WDYT?

[codingllama]

Somewhat related: #62523. Reviews welcome!

• Unify device verification logic under lib/devicetrust/authz #62523

[public-teleport-github-review-bot]

@21KennethTran - this PR will require admin approval to merge due to its size. Consider breaking it up into a series smaller changes.