This tip will give you an overview about how to integrate Identity Server 4 library in your .NET Core app.
What is an Identity Server?
Identity Server 4 (IdS4) is an OpenID Connect and OAuth 2.0 framework for .NET core application. It’s an authentication service that provides you centralized authentication logic for different types of applications (Web, Mobile, or Services).
Implement IdS4 in ASP.NET Core Web App
First, you need to create an empty ASP.NET Core web app using the below command:
dotnet new web
Alternatively, you can achieve the same from Visual Studio by choosing the ASP.NET Core Web Application project using an empty template.
Now, let’s add IdS4 by installing the NuGet package.
dotnet add package IdentityServer4
You have successfully installed the IdS4 package, now open your project’s Startup.cs file and add the below code in ConfigureServices()
function. Please keep in mind that the below sample code is just referring to an empty list, so you need to make sure that you have a valid list of In-Memory resources and clients in your app.
services.AddIdentityServer()
.AddInMemoryClients(new List<Client>())
.AddInMemoryApiResources(new List<ApiResource>())
.AddInMemoryIdentityResources(new List<IdentityResource>())
.AddInMemoryPersistedGrants()
.AddTestUsers(new List<TestUser>())
.AddDeveloperSigningCredential();
The above code will include IdS4 dependency and now you need to update Configure
a method with the below code snippet.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseHttpsRedirection();
app.UseIdentityServer();
}
Let’s understand the configuration, we have added IdS4 dependency using .AddIdentityServer()
with default signing certificate using .AddDeveloperSigningCredential()
extension method. Then we have updated Configure()
method with .UseIdentityServer()
extension method here we are actually enabling OpenIdConnect
endpoints. Please see below the list of endpoints provided by IdS4:
connect/token
connect/authorize
connect/userinfo
connect/endsession
connect/revocation
connect/introspect
connect/deviceauthorization
You can get a list of available endpoints using /.well-known/openid-configuration
endpoint.
The above list of endpoints are provided by IdS4/OpenIdConnect/OAuth2 framework. In case you need your own endpoint for your business need, yes you can definitely create your custom endpoint!
Follow the below steps to add a custom endpoint:
- Register custom endpoint:
services.AddIdentityServer(options =>
{
options.Discovery.ExpandRelativePathsInCustomEntries = true;
options.Discovery.CustomEntries = new Dictionary<string, object>
{
{ "myCustomEndpoint", "connect/myCustomEndpoint"}
};
})
.AddEndpoint<MyCustomEndpoint>("myCustomEndpoint", "connect/myCustomEndpoint");
- Implement Handler:
The above code adds a custom endpoint in IdS4’s endpoints, now you need to write a handler class for actual implementation.
using IdentityServer4.Hosting;
public class MyCustomEndpoint : IEndpointHandler
{
public async Task<IEndpointResult> ProcessAsync(HttpContext
context)
{
logic
}
}
How to Use These Endpoints?
You can use these endpoints to get access/refresh/identity
a token from the IdS4 token provider, each endpoint serves a different purpose, e.g., connect/authorize
endpoint used in a public-facing application where you can use the IdS4 login screen for authentication (using implicit grant type).
Similarly, connect/token
endpoint provides you access token programmatically (using password grant type).
Request for Password/ResourceOwner
grant type:
POST /connect/token
Headers:
Content-Type: application/x-www-form-urlencoded
Body:
grant_type=password&scope=api1&client_id=testClient&client_secret=testSecret&
username=test.user&password=testPassword
The above request will provide you accessToken
, so now you can use this access token to pass along with your REST API request.
How to Protect Your API using IdS4?
You can protect your existing API or create a new one using dotnet new webapi
command.
To protect your API, you need to install the NuGet package.
dotnet add package IdentityServer4.AccessTokenValidation
This NuGet provides JWT and Reference token validation middleware, for reference token validation it provides caching as well. To validate your access token, you will need to add the below code in ConfigureService
method:
services.AddAuthentication("Bearer")
.AddIdentityServerAuthentication("Bearer", options =>
{
options.ApiName = "api1";
options.Authority = "https://localhost:44385";
});
Here, Authority
is the IdentityServer4
's URL and ApiName
is the Audience
from the access token and API resource name from IdS4 configuration.
To add IdS4 authentication middleware, you need to update your Configure
method with the below code:
public void Configure(IApplicationBuilder app)
{
app.UseAuthentication();
app.UseAuthorization();
}
If you look at the business need, Authenticated user isn’t always authorized to access all resources. So to allow access to authorized users, you can implement policy-based authorization. E.g., in case you have decided to authorize a user if the user’s accessToken
contains specific scope, then you can create a simple policy using .AddPolicy()
method. You need to update the ConfigureServices
method with the below sample code.
Startup.cs
services.AddAuthorization(option =>
{
option.AddPolicy("MyPolicy", p =>
{
p.RequireAuthenticatedUser();
p.RequireClaim(JwtClaimTypes.Scope,
new List<string>
{
"api1.read",
"api1.write:
}
);
});
});
Now your API is protected by the IdS4 authentication provider, so any endpoint decorated with [Authorize]
an attribute is protected. To call these REST endpoints, you need to pass an accessToken
using the Authorization
header.
GET /api/v1.0/getuser
Headers:
Authorization: Bearer <AccessToken>
Note: We have implemented/integrated IdS4 in the .NET project but we haven’t introduced the user interface yet, so to add UI for the IdS4 project, you can copy-paste code from the QuickStart folder.
In this blog, I use In-Memory clients and users, which is definitely not acceptable for a production app so you can use entity framework to update/get clients/users/resources from SQL DB or you can create your own storage library.
Happy coding!
Picture source: Identity Server 4 docs
History
- 30th October, 2020: Initial version