Get started with DNV.OAuth.Web

DNV.OAuth.Web is a .NETCore library for developers to simplify the work of setting up OpenId Connection authentication (OIDC) such as Veracity or Azure AD B2C for ASP.NET Core web project.

Below samples will show you how to do authentication through Veracity.

Prerequisites

Please create an App resource in Veracity developer (https://developer.veracity.com/) and copy out the client id and client secret for the use in further steps below. Please follow the tutorials from here: https://developer.veracity.com/docs/section/developerexperience/introduction.

Package Install

Ensure you have configured to package NuGet Package Source or find the instructions here.

Package Manager Console

PM> `Install-Package DNV.OAuth.Web`

Basic Authentication Usage

To simplify your authentication implementation of Veracity for your .Net 6+ web project, you need to add 3 blocks of codes to Startup.cs.

Add namespace reference.

using DNV.OAuth.Web;

Add AddOidc extension method to ConfigureServices.

public void ConfigureServices(IServiceCollection services)
{
	...
	var oidcOptions = new OidcOptions
	{
		Authority = "<Authority>",
		ClientId = "<ClientId>",
		Scopes = new[] { "<Scope>" },
	};
	services.AddOidc(oidcOptions);
	...
}

Add UseAuthentication and UseAuthorization extension methods to Configure.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
	...
	app.UseAuthentication().UseAuthorization();
	...
}

Then you could launch your project and access an action in a controller that decorated with [Authorize], a challenge request will be sent to IDP(Microsoft or Veracity) to start the authentication process, and the HttpContext will be filled with authentication result.

A sample project is ready for you to try out: OidcOAuthSample.

Access Token Cache Usage

If you web project act as an API gateway, you will want to cache users' access tokens to prevent unnecessary token requests. The library uses MSAL (Microsoft Authentication Library) to manipulate tokens.

Authorization code flow needs to be set to acquire access token, and refresh token is required for MSAL to re-acquire token from IDP if the token exceed its expiration.

public void ConfigureServices(IServiceCollection services)
{
	...
	var oidcOptions = new OidcOptions
	{
		Authority = "<Authority>",
		ClientId = "<ClientId>",
		ClientSecret = "<ClientSecret>",
		Resource = "<Resource>",
		Scopes = new[] { "<Scope>", "offline_access" },	// offline_access is required to retrieve refresh_token.
		ResponseType = OpenIdConnectResponseType.Code
	};
	...
}

To cache the tokens, an implementaion of IDistributedCache such as MemoryDistributedCache needs to be added.

public void ConfigureServices(IServiceCollection services)
{
	...
	services.AddDistributedMemoryCache();
	...
}

You can also add RedisCache instead.

public void ConfigureServices(IServiceCollection services)
{
	...
	services.AddDistributedRedisCache(o =>
	{
		o.InstanceName = "<InstanceName>";
		o.Configuration = "<Configuration>";
	});
	...
}

Don't forget to add AddOidc after what you did previously.

public void ConfigureServices(IServiceCollection services)
{
	...
	services.AddOidc(oidcOptions);
	...
}

Add UseAuthentication and UseAuthorization extension methods to Configure.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
	...
	app.UseAuthentication().UseAuthorization();
	...
}

A sample project is ready for you to try out: TokenCacheSample.

Authorize Api with a specific JWT scheme

Create two Api resources (tick the checkbox "This is an API") in Veracity developer and copy out the client ids. Then for both Apis, add client application using the client id you created in the beginning.
Add the JWT options with two authentication themes in appsettings.json

"JwtOptions": {
	"App1": {
		"AuthorizationPolicyName": "Policy1",
		"Authority": "<Authority>",
		"ClientId": "<client id of Api 1>"
	},
	"App2": {
		"AuthorizationPolicyName": "Policy2",
		"Authority": "<Authority>",
		"ClientId": "<client id of Api 2>"
	}
}

Configure services to use JWT options

services.AddJwt(this.Configuration.GetSection("JwtOptions").GetChildren());

Create controller authorized by JWT authentication theme

[ApiController]
[Route("api/[controller]")]
public class TestController : ControllerBase
{
	/// <summary>
	/// requires token from App1
	/// </summary>
	/// <returns></returns>
	[HttpGet("mobile")]
	[Authorize(AuthenticationSchemes = "App1")]
	public IEnumerable<KeyValuePair<string, string>> GetMobileClaims()
	{
		return this.User.Claims.Select(c => new KeyValuePair<string, string>(c.Type, c.Value));
	}

	/// <summary>
	/// requires token from App2
	/// </summary>
	/// <returns></returns>
	[HttpGet("janus")]
	[Authorize(AuthenticationSchemes = "App2")]
	public IEnumerable<KeyValuePair<string, string>> GetJanusClaims()
	{
		return this.User.Claims.Select(c => new KeyValuePair<string, string>(c.Type, c.Value));
	}
}

Configure swagger

a. Add swagger options in appsettings.json

"SwaggerOptions": {
	"Enabled": true,
	"Version": "v1",
	"DocumentTitle": "Demo API",
	"ClientId": "<put your client id here>",
	"ClientSecret": "<put your client secret here>",
	"AuthCodeFlow": {
		"AuthorizationUrl": "<Authorization url>",
		"TokenUrl": "<Token url>",
		"Scopes": {
			"App1": "<scope for App 1>",
			"App2": "<scope for App 2>"
		}
	},
	"ClientCredsFlow": {
		"AuthorizationUrl": "<Authorization url>",
		"TokenUrl": "<Token url>",
		"Scopes": {
			"App1": "<scope for App 1>",
			"App2": "<scope for App 2>"
		}
	}
}

Add the code snippet below to your Start.cs file

// ConfigureServices
services.AddSwagger(o => this.Configuration.Bind("SwaggerOptions", o));

//Configure
app.UseSwaggerWithUI(o => this.Configuration.Bind("SwaggerOptions", o));