Attaching a destination to custom claims using AddClaim or SetDestinations

Unlike OAuthAuthorizationServerMiddleware, ASOS doesn't assume that access tokens are always consumed by your own resource servers and refuses to serialize claims that don't explicitly specify a destination to avoid leaking confidential data to unauthorized parties.

Concretely, this means that all your claims won't be returned to the client application, unless you explicitly call the AddClaim overload taking one or more destinations or use SetDestinations to attach the appropriate destination(s) to your claims.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

var identity = new ClaimsIdentity(OpenIdConnectServerDefaults.AuthenticationScheme);
    
// When access_token and id_token are specified,
// the claim will be serialized in both tokens.
identity.AddClaim("username", "Pinpoint",
    OpenIdConnectConstants.Destinations.AccessToken,
    OpenIdConnectConstants.Destinations.IdentityToken);

// If only access_token is specified, the language
// claim won't be added in the identity token.
var claim = new Claim("language", "fr-FR");
claim.SetDestinations(OpenIdConnectConstants.Destinations.AccessToken);

identity.AddClaim(claim);

Read more

To support interactive flows like the authorization code or the implicit flows, the ValidateAuthorizationRequest event must be implemented to validate the authorization request sent by the client application.

Implementing ValidateAuthorizationRequest to validate response_type, client_id and redirect_uri

To support interactive flows, you must implement ValidateAuthorizationRequest to validate the client_id and the redirect_uri parameters provided by the client application to ensure they correspond to a registered client.

Ideally, the response_type parameter should also be validated to ensure that a client_id corresponding to a confidential application cannot be used with the implicit/hybrid flow to prevent [downgrade attacks](http://homakov.blogspot.com/2012/08/saferweb-OAuth 2.0a-or-lets-just-fix-it.html).

Nothing surprising: the exact implementation of ValidateAuthorizationRequest will depend on the flows you want to support (e.g authorization code/implicit/hybrid) and on how you store your application details (e.g hardcoded or in a database).

Read more

Implementing the resource owner password credentials grant (abbreviated ROPC for brevity) is quite easy with ASOS as the only thing you have to do is to provide your own implementation of ValidateTokenRequest and HandleTokenRequest.

But to properly implement these events, you first need to determine what's the best client authentication policy for your application.

Implementing ValidateTokenRequest to validate the grant type and the client application credentials

When implementing flows using backchannel communication (i.e resource owner password credentials grant, client credentials grant, authorization code flow or refresh token grant), the ValidateTokenRequest event must be overridden to validate the token request.

So, what are you supposed to validate in this event? Mainly two things:

• The grant type: in most cases, you'll likely want to restrict the grants a client application is allowed to use (e.g resource owner password credentials only): ValidateTokenRequest is the best place for that.

• The client credentials (client_id/client_secret): the OAuth 2.0 specification explicitly states that confidential applications (i.e applications that are able to keep their credentials secret, like server-side apps) must authenticate when using the token endpoint. This security measure is extremely important as it's the only way to prevent malicious applications from retrieving an access token on behalf of a legitimate confidential application.

Read more

ASOS leverages the same events model as the rest of the ASP.NET Core security stack: often hard to understand for beginners, this pattern (inherited from OWIN/Katana) proved to be extremely powerful by offering full flexibility on the request processing.

To help make things clearer before trying to implement a concrete flow, here's a quick overview of how it works with ASOS:

OpenIdConnectServerProvider and the events model

OpenIdConnectServerProvider is ASOS' main extensibility hook: its methods (named events or notifications) are invoked by OpenIdConnectServerHandler for every OpenID Connect request to give you a chance to control how the request is handled. Depending on the flows you want to support, you'll need to implement different events.

You have 2 options to create your own provider:

• Directly instantiante an OpenIdConnectServerProvider and use inline delegates. This approach is perfect when implementing a simple server that mainly relies on hardcoded values.

1
2
3
4
5
6
7
8
9
10
11
12
13

app.UseOpenIdConnectServer(options =>
{
    options.Provider = new OpenIdConnectServerProvider
    {
        // Implement OnValidateAuthorizationRequest to
        // support interactive flows (code/implicit/hybrid).
        OnValidateAuthorizationRequest = async context => { ... },

        // Implement OnValidateTokenRequest to support flows using the token endpoint
        // (code/refresh token/password/client credentials/custom grant).
        OnValidateTokenRequest = async context => { ... }
    };
});

You can also directly set the events properties without having to manually instantiate a OpenIdConnectServerProvider, as ASOS always registers a default OpenIdConnectServerProvider instance for you:

1
2
3
4
5
6
7
8
9
10

app.UseOpenIdConnectServer(options =>
{
    // Implement OnValidateAuthorizationRequest to
    // support interactive flows (code/implicit/hybrid).
    options.Provider.OnValidateAuthorizationRequest = async context => { ... };

    // Implement OnValidateTokenRequest to support flows using the token endpoint
    // (code/refresh token/password/client credentials/custom grant).
    options.Provider.OnValidateTokenRequest = async context => { ... };
});

• Create your own subclass of OpenIdConnectServerProvider and override the virtual methods you want to implement. This is clearly the best approach when implementing a more complex authorization server.

1
2
3
4
5
6
7
8
9

public sealed class AuthorizationProvider : OpenIdConnectServerProvider
{
    // Implement OnValidateAuthorizationRequest to support interactive flows (code/implicit/hybrid).
    public override async Task ValidateAuthorizationRequest(ValidateAuthorizationRequestContext context) { ... }

    // Implement OnValidateTokenRequest to support flows using the token endpoint
    // (code/refresh token/password/client credentials/custom grant).
    public override async Task ValidateTokenRequest(ValidateTokenRequestContext context) { ... }
}

1
2
3
4

app.UseOpenIdConnectServer(options =>
{
    options.Provider = new AuthorizationProvider();
});

Read more

In the previous post (Choosing the right flow(s)), we saw the differences between the various OAuth 2.0/OpenID Connect flows. In this one, we'll see how to reference the ASOS package and how to register it in the ASP.NET Core pipeline.

Referencing the OpenID Connect server middleware package

To reference ASOS, simply add "AspNet.Security.OpenIdConnect.Server": "1.0.0" under the dependencies node of your .csproj file:

1
2
3
4
5
6
7

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="AspNet.Security.OpenIdConnect.Server" Version="1.0.0" />
  </ItemGroup>

</Project>

Referencing the OAuth 2.0 validation middleware

You'll also need to add the validation middleware, in charge of verifying/decrypting the tokens produced by ASOS and protecting your API endpoints:

1
2
3
4
5
6
7

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="AspNet.Security.OAuth.Validation" Version="1.0.0" />
  </ItemGroup>

</Project>

The validation middleware is similar to the JWT bearer middleware developed by the ASP.NET team but was specifically designed to use the encrypted tokens issued by ASOS and to offer a much easier experience (it doesn't require any explicit configuration by default).

Read more