[API Proposal]: AuthN/AuthZ metrics

[MackinnonBuck]

Background and Motivation

This is a collection of metrics for ASP.NET Core Authentication and Authorization.

Implemented in #59557.

Proposed API

Microsoft.AspNetCore.Authentication

aspnetcore.authentication.request.duration

Name	Instrument Type	Unit	Description
aspnetcore.authentication.request.duration	Histogram	{request}	The authentication duration for a request.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
aspnetcore.authentication.result	string	The authentication result.	success; failure; none; _OTHER	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

aspnetcore.authentication.challenges

Name	Instrument Type	Unit	Description
aspnetcore.authentication.challenges	Counter	{request}	The total number of times a scheme is challenged.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

aspnetcore.authentication.forbids

Name	Instrument Type	Unit	Description
aspnetcore.authentication.forbids	Counter	{request}	The total number of times an authenticated user attempts to access a resources they are not permitted to access.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

aspnetcore.authentication.sign_ins

Name	Instrument Type	Unit	Description
aspnetcore.authentication.sign_ins	Counter	{request}	The total number of times a principal is signed in.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

aspnetcore.authentication.sign_outs

Name	Instrument Type	Unit	Description
aspnetcore.authentication.sign_ins	Counter	{request}	The total number of times a scheme is signed out.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

Microsoft.AspNetCore.Authorization

aspnetcore.authorization.requests

Name	Instrument Type	Unit	Description
aspnetcore.authorization.requests	Counter	{request}	The total number of requests for which authorization was attempted.

Attribute	Type	Description	Examples	Presence
user.is_authenticated	boolean	Whether the request came from an authenticated user	true	Required
aspnetcore.authorization.policy	string	The name of the authorization policy.	AtLeast21; EmployeeOnly	Conditionally required if an authorization policy is used
aspnetcore.authorization.result	string	Whether the authorization succeeded or failed.	success; failure	Conditionally Required if an exception is not thrown during authorization
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

Alternative Designs

Currently, error.type is just the exception type name. This isn't very descriptive. We could also consider a way to allow authentication handlers to specify a failure reason (maybe in some kind of aspnetcore.authentication.failure_reason attribute). This can be added in the future as a non-breaking change.

Also, error.type is only populated if an unhandled exception is thrown by a handler. This excludes cases where authentication fails by returning an AuthenticationResult indicating failure (even though the AuthenticateResult contains an Exception describing the failure). We could change error.type to contain the type of any exception in the AuthenticateResult, but this would be inconsistent with authorization because AuthorizationResult does not contain an exception to be reported on.

Risks

None that I'm aware of.

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[halter73]

• Is aspnetcore.authentication.request.duration for the entire request or just AuthenticateAsync?
  • AuthenticateAsync
  • Could we rename it to aspnetcore.authentication.authenticate.duration? Yes.
• Is _OTHER possible for aspnetcore.authentication.result? No. We'll remove it.
• Why is challenges plural when authenticate is not? challenges is a Counter, so it should be plural. https://opentelemetry.io/docs/specs/semconv/general/metrics/#pluralization
• The authz aspnetcore.authentication.requests should be aspnetcore.authorization.requests
• Should aspnetcore.authorization.requests be aspnetcore.authorization.count? https://opentelemetry.io/docs/specs/semconv/general/metrics/#use-count-instead-of-pluralization-for-updowncounters
  • Or what about aspnetcore.authorization.attempts so "requests" isn't interpreted as an HTTP request?
  • aspnetcore.authorization.attempts wins.
• Do need units for duration? No. It's implied to be seconds. 'duration' is a pretty common otel name ending.

API approved!

Microsoft.AspNetCore.Authentication

aspnetcore.authentication.authenticate.duration

Name	Instrument Type	Unit	Description
aspnetcore.authentication.authenticate.duration	Histogram	{'s'}	The authentication duration for a request.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
aspnetcore.authentication.result	string	The authentication result.	success; failure; none; _OTHER	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if authentication failed or the request has ended with an error

aspnetcore.authentication.challenges

Name	Instrument Type	Unit	Description
aspnetcore.authentication.challenges	Counter	{request}	The total number of times a scheme is challenged.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

aspnetcore.authentication.forbids

Name	Instrument Type	Unit	Description
aspnetcore.authentication.forbids	Counter	{request}	The total number of times an authenticated user attempts to access a resources they are not permitted to access.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

aspnetcore.authentication.sign_ins

Name	Instrument Type	Unit	Description
aspnetcore.authentication.sign_ins	Counter	{request}	The total number of times a principal is signed in.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

aspnetcore.authentication.sign_outs

Name	Instrument Type	Unit	Description
aspnetcore.authentication.sign_ins	Counter	{request}	The total number of times a scheme is signed out.

Attribute	Type	Description	Examples	Presence
aspnetcore.authentication.scheme	string	The name of the authentication scheme.	Bearer; Cookies	Conditionally Required if the request did not end with an error
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

Microsoft.AspNetCore.Authorization

aspnetcore.authorization.attempts

Name	Instrument Type	Unit	Description
aspnetcore.authorization.attempts	Counter	{request}	The total number of requests for which authorization was attempted.

Attribute	Type	Description	Examples	Presence
user.is_authenticated	boolean	Whether the request came from an authenticated user	true	Required
aspnetcore.authorization.policy	string	The name of the authorization policy.	AtLeast21; EmployeeOnly	Conditionally required if an authorization policy is used
aspnetcore.authorization.result	string	Whether the authorization succeeded or failed.	success; failure	Conditionally Required if an exception is not thrown during authorization
error.type	string	The full name of the exception type.	System.InvalidOperationException; Contoso.MyException	Conditionally Required if the request has ended with an error

[MackinnonBuck]

@lmolkova, would you mind giving this API a look (described in the comment just above this one) and letting us know if you think there's anything else that needs revision? The main things that need confirmation are:

1. Whether {request} is a valid unit, especially on aspnetcore.authorization.attempts (should be something like {attempt} instead?)
2. Whether user.is_authenticated is a valid attribute name. There are standard user attributes, and is_authenticated is not one of them.

Thanks!

[MackinnonBuck]

Closing as this was completed in #59557