Table of Contents

Class CapabilityTokensController

Namespace
ReferenceApplication.Web.Controllers.Api
Assembly
ReferenceApplication.Web.dll

Issues signed capability tokens for the capability-protected sample operations.

[ApiController]
[ApiVersion("1.0")]
[Authorize(Policy = "application.AuthenticatedUser")]
[Route("api/v{version:apiVersion}/capability-tokens")]
public sealed class CapabilityTokensController : ControllerBase
Inheritance
CapabilityTokensController
Inherited Members

Remarks

Issuance plays the role an authorization service would play in a larger system. Entitlement still comes from the actor's normalized permission claims: a token is issued only to an actor who holds every scope the target endpoint declares. The token then binds that entitlement to one actor, one operation, one request payload, a short lifetime, and a single use.

The payload is described with form fields named payload.<field>: a field payload.Note binds the governed request's Note field. The binding is computed with AsiBackbone's CreateBinding(IEnumerable<KeyValuePair<string, StringValues>>, IEnumerable<string>), the same rule the relying endpoint applies, so every other form field the governed request posts, except the antiforgery field, invalidates the token. The route is present only while capability tokens are enabled; otherwise it returns 404.

Constructors

CapabilityTokensController(IOptions<CapabilityTokenOptions>, IOptions<AntiforgeryOptions>, EndpointDataSource, IHttpGovernanceActorContextResolver, ClaimEndpointCapabilityGrantValidator)

Issues signed capability tokens for the capability-protected sample operations.

public CapabilityTokensController(IOptions<CapabilityTokenOptions> optionsAccessor, IOptions<AntiforgeryOptions> antiforgeryOptionsAccessor, EndpointDataSource endpointDataSource, IHttpGovernanceActorContextResolver actorContextResolver, ClaimEndpointCapabilityGrantValidator entitlementValidator)

Parameters

optionsAccessor IOptions<CapabilityTokenOptions>
antiforgeryOptionsAccessor IOptions<AntiforgeryOptions>
endpointDataSource EndpointDataSource
actorContextResolver IHttpGovernanceActorContextResolver
entitlementValidator ClaimEndpointCapabilityGrantValidator

Remarks

Issuance plays the role an authorization service would play in a larger system. Entitlement still comes from the actor's normalized permission claims: a token is issued only to an actor who holds every scope the target endpoint declares. The token then binds that entitlement to one actor, one operation, one request payload, a short lifetime, and a single use.

The payload is described with form fields named payload.<field>: a field payload.Note binds the governed request's Note field. The binding is computed with AsiBackbone's CreateBinding(IEnumerable<KeyValuePair<string, StringValues>>, IEnumerable<string>), the same rule the relying endpoint applies, so every other form field the governed request posts, except the antiforgery field, invalidates the token. The route is present only while capability tokens are enabled; otherwise it returns 404.

Fields

PayloadFieldPrefix

Gets the prefix of form fields that describe the governed request's payload.

public const string PayloadFieldPrefix = "payload."

Field Value

string

Methods

Issue(string, CancellationToken)

Issues a single-use capability token for one governed request.

[HttpPost]
[ValidateAntiForgeryToken]
[ProducesResponseType<CapabilityTokenResponse>(200)]
[ProducesResponseType(400)]
[ProducesResponseType(401)]
[ProducesResponseType(403)]
[ProducesResponseType(404)]
public Task<ActionResult<CapabilityTokenResponse>> Issue(string operation, CancellationToken cancellationToken)

Parameters

operation string

The governed operation: capability or consequential.

cancellationToken CancellationToken

A token that cancels issuance.

Returns

Task<ActionResult<CapabilityTokenResponse>>

The token and the values it is bound to.