Creating your own OpenID Connect server with ASOS: implementing the resource owner password credentials grant

Development

This post is the fifth part of a series of blog posts entitled Creating your own OpenID Connect server with ASOS:

  1. Introduction
  2. Choosing the right flow(s)
  3. Registering the middleware in the ASP.NET Core pipeline
  4. Creating your own authorization provider
  5. Implementing the resource owner password credentials grant
  6. Implementing the authorization code and implicit flows
  7. Adding custom claims and granting scopes
  8. Testing your authorization server with Postman
  9. Conclusion

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.

It should be noted that ASOS doesn't validate the grant_type value, that can even contain a custom value for extension grants: if you only want to support standard grants, it's up to you to reject the token request by calling context.Reject().

IsAuthorizationCodeGrantType(), IsRefreshTokenGrantType(), IsPasswordGrantType() and IsClientCredentialsGrantType() can be used for this exact purpose.

  • The client credentials (client_id/client_secret): the OAuth2 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.

Contrary to popular belief, client authentication is never mandatory when using the token endpoint (except for the client credentials grant), which means that public applications like JS or mobile apps are allowed to use the resource owner password grant without having to send their credentials.

In practice, it's up to you to decide whether your token endpoint should accept unauthenticated requests or not, depending on the type of client you'll use.

Read more

Creating your own OpenID Connect server with ASOS: creating your own authorization provider

Development

This post is the fourth part of a series of blog posts entitled Creating your own OpenID Connect server with ASOS:

  1. Introduction
  2. Choosing the right flow(s)
  3. Registering the middleware in the ASP.NET Core pipeline
  4. Creating your own authorization provider
  5. Implementing the resource owner password credentials grant
  6. Implementing the authorization code and implicit flows
  7. Adding custom claims and granting scopes
  8. Testing your authorization server with Postman
  9. Conclusion

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();
});

It's important to note that the authorization provider is always a singleton: don't try to inject scoped dependencies in its constructor. To resolve scoped dependencies (e.g an Entity Framework DbContext), use the context.HttpContext.RequestServices property to access the scoped container.

You can read this thread for more information about this limitation/design choice, which is not specific to ASOS and impacts all the security middleware sharing the same events model. It might be fixed in a future version, though.

Read more

Creating your own OpenID Connect server with ASOS: registering the middleware in the ASP.NET Core pipeline

Development

This post is the third part of a series of blog posts entitled Creating your own OpenID Connect server with ASOS:

  1. Introduction
  2. Choosing the right flow(s)
  3. Registering the middleware in the ASP.NET Core pipeline
  4. Creating your own authorization provider
  5. Implementing the resource owner password credentials grant
  6. Implementing the authorization code and implicit flows
  7. Adding custom claims and granting scopes
  8. Testing your authorization server with Postman
  9. Conclusion

In the previous post (Choosing the right flow(s)), we saw the differences between the various OAuth2/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

This post was updated to reflect the latest changes introduced in the 1.0.0 RTM version of ASOS.

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 OAuth2 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).

Starting with ASOS beta5, JWT is no longer the default format for access tokens, but is still supported natively. To use JWT tokens instead of opaque/encrypted tokens, follow the steps below:

  • Remove the reference to AspNet.Security.OAuth.Validation in project.json.
  • Remove the validation middleware registration (app.UseOAuthValidation()),
  • Reference the Microsoft.AspNetCore.Authentication.JwtBearer package.
  • Register the JWT middleware using app.UseJwtBearerAuthentication().
  • Assign options.AccessTokenHandler = new JwtSecurityTokenHandler() to override the default format.

Read more

Creating your own OpenID Connect server with ASOS: choosing the right flow(s)

Development

This post is the second part of a series of blog posts entitled Creating your own OpenID Connect server with ASOS:

  1. Introduction
  2. Choosing the right flow(s)
  3. Registering the middleware in the ASP.NET Core pipeline
  4. Creating your own authorization provider
  5. Implementing the resource owner password credentials grant
  6. Implementing the authorization code and implicit flows
  7. Adding custom claims and granting scopes
  8. Testing your authorization server with Postman
  9. Conclusion

ASOS offers built-in support for all the standard flows defined by the OAuth2 and OpenID Connect core specifications: the authorization code flow, the implicit flow, the hybrid flow (which is basically a mix between the first two flows), the resource owner password credentials grant and the client credentials grant.

Though not specific to ASOS, choosing the best flow(s) for your application is an important prerequisite when implementing your own authorization server ; so here's a quick overview of the different OAuth2/OpenID Connect flows:

Non-interactive flows

Resource owner password credentials flow

Directly inspired by basic authentication, the resource owner password credentials grant (abbreviated ROPC) is probably the simplest OAuth2 flow: the client application asks the user his username/password, sends a token request to the authorization server with the user credentials (and depending on the client authentication policy defined by the authorization server, its own client credentials) and gets back an access token it can use to retrieve the user's resources.

1
2
3
4
5
POST /connect/token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=johndoe&password=A3ddj3w
1
2
3
4
5
6
7
8
9
10
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"bearer",
  "expires_in":3600
}

Though not recommended by the OAuth2 specification as it's the only flow where the user password is directly exposed to the client application (which breaks the principle of least privilege), the resource owner password credentials grant is one of the most popular flows.

It is is particularly appreciated by SPA writers as it's trivial to implement in vanilla JavaScript, doesn't involve any redirection or consent form and, unlike interactive flows, doesn't require implementing token validation or cross-site request forgery (XSRF) countermeasures to prevent session fixation attacks.

If you don't feel comfortable with the other flows (and the security measures they require on the client-side), using ROPC might be a good option: paradoxically, a client application using ROPC will be far less vulnerable than a client using interactive flows without implementing the appropriate security checks.

As recommended by the OAuth2 specification, you SHOULD NEVER use it with third-party applications. If you want to support applications you don't fully trust, consider using an interactive flow instead (e.g authorization code or implicit flow).

Read more

Creating your own OpenID Connect server with ASOS: introduction

Development

This post is the first part of a series of blog posts entitled Creating your own OpenID Connect server with ASOS:

  1. Introduction
  2. Choosing the right flow(s)
  3. Registering the middleware in the ASP.NET Core pipeline
  4. Creating your own authorization provider
  5. Implementing the resource owner password credentials grant
  6. Implementing the authorization code and implicit flows
  7. Adding custom claims and granting scopes
  8. Testing your authorization server with Postman
  9. Conclusion

What's ASOS?

AspNet.Security.OpenIdConnect.Server (codenamed ASOS) is an open-source OAuth2/OpenID Connect server middleware for OWIN/Katana and ASP.NET Core 1.0 (previously known as ASP.NET 5), designed to work on both the full .NET desktop framework and the new .NET Core platform. It is part of the aspnet-contrib initiative, that's also behind the OAuth2 social providers for ASP.NET Core.

Forked from Katana's now deprecated OAuth2 authorization server middleware, ASOS shares the same same low-level, protocol-first approach but comes with many new OpenID Connect features (e.g provider configuration discovery, client-initiated logout or userinfo support) and implements some of the recent OAuth2 specifications like token revocation or token introspection (kudos to Michael Ciarlillo for his great contribution!).

How is it different from the other identity servers?

Unlike other identity server projects, ASOS only focuses on the OAuth2/OpenID Connect protocol part and acts as a thin layer between your application and the protocol details: it comes with no membership feature, implementing the consent pages is left as an exercise and adding a CORS policy must be done by the developer depending on his/her own needs.

Though it requires a solid knowledge of the OAuth2/OpenID Connect specifications and generally needs more work than turnkey solutions (like the famous IdentityServer or OpenIddict), ASOS offers the most flexible approach and can be easily integrated to any existing environment.

Read more