Welcome to IdentityServer4 (ASP.NET Core 3.x)¶
IdentityServer4 is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core.
It enables the following features in your applications:
The Big Picture¶
Most modern applications look more or less like this:
The most common interactions are:
- Browsers communicate with web applications
- Web applications communicate with web APIs (sometimes on their own, sometimes on behalf of a user)
- Browser-based applications communicate with web APIs
- Native applications communicate with web APIs
- Server-based applications communicate with web APIs
- Web APIs communicate with web APIs (sometimes on their own, sometimes on behalf of a user)
Typically each and every layer (front-end, middle-tier and back-end) has to protect resources and implement authentication and/or authorization – often against the same user store.
Outsourcing these fundamental security functions to a security token service prevents duplicating that functionality across those applications and endpoints.
Restructuring the application to support a security token service leads to the following architecture and protocols:
Such a design divides security concerns into two parts:
Authentication¶
Authentication is needed when an application needs to know the identity of the current user. Typically these applications manage data on behalf of that user and need to make sure that this user can only access the data for which he is allowed. The most common example for that is (classic) web applications – but native and JS-based applications also have a need for authentication.
The most common authentication protocols are SAML2p, WS-Federation and OpenID Connect – SAML2p being the most popular and the most widely deployed.
OpenID Connect is the newest of the three, but is considered to be the future because it has the most potential for modern applications. It was built for mobile application scenarios right from the start and is designed to be API friendly.
API Access¶
Applications have two fundamental ways with which they communicate with APIs – using the application identity, or delegating the user’s identity. Sometimes both methods need to be combined.
OAuth2 is a protocol that allows applications to request access tokens from a security token service and use them to communicate with APIs. This delegation reduces complexity in both the client applications as well as the APIs since authentication and authorization can be centralized.
OpenID Connect and OAuth 2.0 – better together¶
OpenID Connect and OAuth 2.0 are very similar – in fact OpenID Connect is an extension on top of OAuth 2.0. The two fundamental security concerns, authentication and API access, are combined into a single protocol - often with a single round trip to the security token service.
We believe that the combination of OpenID Connect and OAuth 2.0 is the best approach to secure modern applications for the foreseeable future. IdentityServer4 is an implementation of these two protocols and is highly optimized to solve the typical security problems of today’s mobile, native and web applications.
How IdentityServer4 can help¶
IdentityServer is middleware that adds the spec compliant OpenID Connect and OAuth 2.0 endpoints to an arbitrary ASP.NET Core application.
Typically, you build (or re-use) an application that contains a login and logout page (and maybe consent - depending on your needs), and the IdentityServer middleware adds the necessary protocol heads to it, so that client applications can talk to it using those standard protocols.
The hosting application can be as complex as you want, but we typically recommend to keep the attack surface as small as possible by including authentication related UI only.
Terminology¶
The specs, documentation and object model use a certain terminology that you should be aware of.
IdentityServer¶
IdentityServer is an OpenID Connect provider - it implements the OpenID Connect and OAuth 2.0 protocols.
Different literature uses different terms for the same role - you probably also find security token service, identity provider, authorization server, IP-STS and more.
But they are in a nutshell all the same: a piece of software that issues security tokens to clients.
IdentityServer has a number of jobs and features - including:
- protect your resources
- authenticate users using a local account store or via an external identity provider
- provide session management and single sign-on
- manage and authenticate clients
- issue identity and access tokens to clients
- validate tokens
User¶
A user is a human that is using a registered client to access resources.
Client¶
A client is a piece of software that requests tokens from IdentityServer - either for authenticating a user (requesting an identity token) or for accessing a resource (requesting an access token). A client must be first registered with IdentityServer before it can request tokens.
Examples for clients are web applications, native mobile or desktop applications, SPAs, server processes etc.
Resources¶
Resources are something you want to protect with IdentityServer - either identity data of your users, or APIs.
Every resource has a unique name - and clients use this name to specify to which resources they want to get access to.
Identity data Identity information (aka claims) about a user, e.g. name or email address.
APIs APIs resources represent functionality a client wants to invoke - typically modelled as Web APIs, but not necessarily.
Identity Token¶
An identity token represents the outcome of an authentication process. It contains at a bare minimum an identifier for the user (called the sub aka subject claim) and information about how and when the user authenticated. It can contain additional identity data.
Access Token¶
An access token allows access to an API resource. Clients request access tokens and forward them to the API. Access tokens contain information about the client and the user (if present). APIs use that information to authorize access to their data.
Supported Specifications¶
IdentityServer implements the following specifications:
OpenID Connect¶
OAuth 2.0¶
- OAuth 2.0 (RFC 6749)
- OAuth 2.0 Bearer Token Usage (RFC 6750)
- OAuth 2.0 Multiple Response Types (spec)
- OAuth 2.0 Form Post Response Mode (spec)
- OAuth 2.0 Token Revocation (RFC 7009)
- OAuth 2.0 Token Introspection (RFC 7662)
- Proof Key for Code Exchange (RFC 7636)
- JSON Web Tokens for Client Authentication (RFC 7523)
- OAuth 2.0 Device Authorization Grant (RFC 8628)
- OAuth 2.0 Mutual TLS Client Authentication and Certificate-Bound Access Tokens (draft)
Packaging and Builds¶
IdentityServer consists of a number of nuget packages.
IdentityServer4 main repo¶
Contains the core IdentityServer object model, services and middleware as well as the EntityFramework and ASP.NET Identity integration.
nugets:
Access token validation handler¶
ASP.NET Core authentication handler for validating tokens in APIs. The handler allows supporting both JWT and reference tokens in the same API.
Dev builds¶
In addition we publish dev/interim builds to the GitHub package repository. Add the following feed if you want to give them a try:
Support and Consulting Options¶
We have several free and commercial support and consulting options for IdentityServer.
Free support¶
Free support is community-based and uses public forums
StackOverflow
There’s an ever growing community of people using IdentityServer that monitor questions on StackOverflow. If time permits, we also try to answer as many questions as possible
You can subscribe to all IdentityServer4 related questions using this feed:
https://stackoverflow.com/questions/tagged/?tagnames=identityserver4&sort=newest
Please use the IdentityServer4 tag when asking new questions
Gitter
You can chat with other IdentityServer4 users in our Gitter chat room:
https://gitter.im/IdentityServer/IdentityServer4
Reporting a bug
If you think you have found a bug or unexpected behavior, please open an issue on the Github issue tracker. We try to get back to you ASAP. Please understand that we also have day jobs, and might be too busy to reply immediately.
Also check the contribution guidelines before posting.
Commercial support¶
We are doing consulting, mentoring and custom software development around identity & access control architecture in general, and IdentityServer in particular. Please get in touch with us to discuss possible options.
Training
We are regularly doing workshops around identity & access control for modern applications. Check the agenda and upcoming public dates here. We can also perform the training privately at your company. Contact us to request the training on-site.
AdminUI, WS-Federation, SAML2p, and FIDO2 support
There are commercial add-on products available from our partners, Rock Solid Knowledge, on identityserver.com.
Demo Server¶
You can try IdentityServer4 with your favourite client library. We have a test instance at demo.identityserver.io. On the main page you can find instructions on how to configure your client and how to call an API.
Contributing¶
We are very open to community contributions, but there are a couple of guidelines you should follow so we can handle this without too much effort.
How to contribute?¶
The easiest way to contribute is to open an issue and start a discussion. Then we can decide if and how a feature or a change could be implemented. If you should submit a pull request with code changes, start with a description, only make the minimal changes to start with and provide tests that cover those changes.
Also read this first: Being a good open source citizen
General feedback and discussions?¶
Please start a discussion on the core repo issue tracker.
Bugs and feature requests?¶
Please log a new issue in the appropriate GitHub repo:
Contributing code and content¶
You will need to sign a Contributor License Agreement before you can contribute any code or content. This is an automated process that will start after you opened a pull request.
Contribution projects¶
We very much appreciate if you start a contribution project (e.g. support for Database X or Configuration Store Y). Tell us about it so we can tweet and link it in our docs.
We generally don’t want to take ownership of those contribution libraries, we are already really busy supporting the core projects.
Naming conventions
As of October 2017, the IdentityServer4.* nuget namespace is reserved for our packages. Please use the following naming conventions:
YourProjectName.IdentityServer4
or
IdentityServer4.Contrib.YourProjectName
Overview¶
The quickstarts provide step by step instructions for various common IdentityServer scenarios. They start with the absolute basics and become more complex - it is recommended you do them in order.
- adding IdentityServer to an ASP.NET Core application
- configuring IdentityServer
- issuing tokens for various clients
- securing web applications and APIs
- adding support for EntityFramework based configuration
- adding support for ASP.NET Identity
Every quickstart has a reference solution - you can find the code in the samples folder.
Preparation¶
The first thing you should do is install our templates:
dotnet new -i IdentityServer4.Templates
They will be used as a starting point for the various tutorials.
OK - let’s get started!
Note
The quickstarts target the latest version of IdentityServer and ASP.NET Core (3.0) - there are also quickstarts for ASP.NET Core 2 and ASP.NET Core 1.
Protecting an API using Client Credentials¶
The following Identity Server 4 quickstart provides step by step instructions for various common IdentityServer scenarios. These start with the absolute basics and become more complex as they progress. We recommend that you follow them in sequence.
To see the full list, please go to IdentityServer4 Quickstarts Overview
This first quickstart is the most basic scenario for protecting APIs using IdentityServer. In this quickstart you define an API and a Client with which to access it. The client will request an access token from the Identity Server using its client ID and secret will then use the token to gain access to the API.
Source Code¶
As with all of these quickstarts you can find the source code for it in the IdentityServer4 repository. The project for this quickstart is Quickstart #1: Securing an API using Client Credentials
Preparation¶
The IdentityServer templates for the dotnet CLI are a good starting point for the quickstarts. To install the templates open a console window and type the following command:
dotnet new -i IdentityServer4.Templates
They will be used as a starting point for the various tutorials.
Setting up the ASP.NET Core application¶
First create a directory for the application - then use our template to create an ASP.NET Core application that includes a basic IdentityServer setup, e.g.:
md quickstart
cd quickstart
md src
cd src
dotnet new is4empty -n IdentityServer
This will create the following files:
IdentityServer.csproj- the project file and aProperties\launchSettings.jsonfileProgram.csandStartup.cs- the main application entry pointConfig.cs- IdentityServer resources and clients configuration file
You can now use your favorite text editor to edit or view the files. If you want to have Visual Studio support, you can add a solution file like this:
cd ..
dotnet new sln -n Quickstart
and let it add your IdentityServer project (keep this command in mind as we will create other projects below):
dotnet sln add .\src\IdentityServer\IdentityServer.csproj
Note
The protocol used in this Template is http and the port is set to 5000 when running on Kestrel or a random one on IISExpress. You can change that in the Properties\launchSettings.json file. However, all of the quickstart instructions will assume you use the default port on Kestrel as well as the http protocol, which is sufficient for local development. For production scenarios you should switch to https.
Defining an API Resource¶
An API is a resource in your system that you want to protect. Resource definitions can be loaded in many ways, the template you used to create the project above shows how to use a “code as configuration” approach.
For this add a new class to your project and call it Config - add the following code to it:
public static class Config
{
public static IEnumerable<ApiResource> Apis =>
new List<ApiResource>
{
new ApiResource("api1", "My API")
};
}
(see the full file here).
Note
If you will be using this in production it is important to give your API a logical name. Developers will be using this to connect to your api though your Identity server. It should describe your api in simple terms to both developers and users.
Defining the client¶
The next step is to define a client application that we will use to access our new API.
For this scenario, the client will not have an interactive user, and will authenticate using the so called client secret with IdentityServer.
For this, add a client definition:
public static IEnumerable<Client> Clients =>
new List<Client>
{
new Client
{
ClientId = "client",
// no interactive user, use the clientid/secret for authentication
AllowedGrantTypes = GrantTypes.ClientCredentials,
// secret for authentication
ClientSecrets =
{
new Secret("secret".Sha256())
},
// scopes that client has access to
AllowedScopes = { "api1" }
}
};
You can think of the ClientId and the ClientSecret as the login and password for your application itself. It identifies your application to the identity server so that it knows which application is trying to connect to it.
Configuring IdentityServer¶
Loading the resource and client definitions happens in Startup.cs - the template already does this for you:
public void ConfigureServices(IServiceCollection services)
{
var builder = services.AddIdentityServer()
.AddInMemoryApiResources(Config.Apis)
.AddInMemoryClients(Config.Clients);
// omitted for brevity
}
That’s it your identity server should now be configured. If you run the server and navigate the browser to http://localhost:5000/.well-known/openid-configuration, you should see the so-called discovery document.
The discovery document is a standard endpoint in identity servers. The discovery document will be used by your clients and APIs to download the necessary configuration data.
At first startup, IdentityServer will create a developer signing key for you, it’s a file called tempkey.rsa.
You don’t have to check that file into your source control, it will be re-created if it is not present.
Adding an API¶
Next, add an API to your solution.
You can either use the ASP.NET Core Web API template from Visual Studio or use the .NET CLI to create the API project as we do here.
Run from within the src folder the following command:
dotnet new web -n Api
Then add it to the solution by running the following commands:
cd ..
dotnet sln add .\src\Api\Api.csproj
Configure the API application to run on http://localhost:5001 only. You can do this by editing the launchSettings.json file inside the Properties folder. Change the application URL setting to be:
"applicationUrl": "http://localhost:5001"
The controller¶
Add a new class called IdentityController:
[Route("identity")]
[Authorize]
public class IdentityController : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return new JsonResult(from c in User.Claims select new { c.Type, c.Value });
}
}
This controller will be used later to test the authorization requirement, as well as visualize the claims identity through the eyes of the API.
Adding a Nuget Dependency¶
In order for the configuration step to work the nuget package dependency has to be added, run this command in the root directory.
dotnet add .\src\api\Api.csproj package Microsoft.AspNetCore.Authentication.JwtBearer
Configuration¶
The last step is to add the authentication services to DI (dependency injection) and the authentication middleware to the pipeline. These will:
- validate the incoming token to make sure it is coming from a trusted issuer
- validate that the token is valid to be used with this api (aka audience)
Update Startup to look like this:
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddAuthentication("Bearer")
.AddJwtBearer("Bearer", options =>
{
options.Authority = "http://localhost:5000";
options.RequireHttpsMetadata = false;
options.Audience = "api1";
});
}
public void Configure(IApplicationBuilder app)
{
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
}
AddAuthenticationadds the authentication services to DI and configuresBeareras the default scheme.UseAuthenticationadds the authentication middleware to the pipeline so authentication will be performed automatically on every call into the host.UseAuthorizationadds the authorization middleware to make sure, our API endpoint cannot be accessed by anonymous clients.
Navigating to the controller http://localhost:5001/identity on a browser should return a 401 status code.
This means your API requires a credential and is now protected by IdentityServer.
Creating the client¶
The last step is to write a client that requests an access token, and then uses this token to access the API. For that, add a console project to your solution, remember to create it in the src:
dotnet new console -n Client
Then as before, add it to your solution using:
cd ..
dotnet sln add .\src\Client\Client.csproj
The token endpoint at IdentityServer implements the OAuth 2.0 protocol, and you could use raw HTTP to access it. However, we have a client library called IdentityModel, that encapsulates the protocol interaction in an easy to use API.
Add the IdentityModel NuGet package to your client.
This can be done either via Visual Studio’s Nuget Package manager or dotnet CLI:
dotnet add package IdentityModel
IdentityModel includes a client library to use with the discovery endpoint. This way you only need to know the base-address of IdentityServer - the actual endpoint addresses can be read from the metadata:
// discover endpoints from metadata
var client = new HttpClient();
var disco = await client.GetDiscoveryDocumentAsync("http://localhost:5000");
if (disco.IsError)
{
Console.WriteLine(disco.Error);
return;
}
Next you can use the information from the discovery document to request a token to IdentityServer to access api1:
// request token
var tokenResponse = await client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
{
Address = disco.TokenEndpoint,
ClientId = "client",
ClientSecret = "secret",
Scope = "api1"
});
if (tokenResponse.IsError)
{
Console.WriteLine(tokenResponse.Error);
return;
}
Console.WriteLine(tokenResponse.Json);
(full file can be found here)
Note
Copy and paste the access token from the console to jwt.ms to inspect the raw token.
Calling the API¶
To send the access token to the API you typically use the HTTP Authorization header. This is done using the SetBearerToken extension method:
// call api
var client = new HttpClient();
client.SetBearerToken(tokenResponse.AccessToken);
var response = await client.GetAsync("http://localhost:5001/identity");
if (!response.IsSuccessStatusCode)
{
Console.WriteLine(response.StatusCode);
}
else
{
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(JArray.Parse(content));
}
The output should look like this:
Note
By default an access token will contain claims about the scope, lifetime (nbf and exp), the client ID (client_id) and the issuer name (iss).
Further experiments¶
This walkthrough focused on the success path so far
- client was able to request token
- client could use the token to access the API
You can now try to provoke errors to learn how the system behaves, e.g.
- try to connect to IdentityServer when it is not running (unavailable)
- try to use an invalid client id or secret to request the token
- try to ask for an invalid scope during the token request
- try to call the API when it is not running (unavailable)
- don’t send the token to the API
- configure the API to require a different scope than the one in the token
Interactive Applications with ASP.NET Core¶
Note
For any pre-requisites (like e.g. templates) have a look at the overview first.
In this quickstart we want to add support for interactive user authentication via the OpenID Connect protocol to our IdentityServer we built in the previous chapter.
Once that is in place, we will create an MVC application that will use IdentityServer for authentication.
Adding the UI¶
All the protocol support needed for OpenID Connect is already built into IdentityServer. You need to provide the necessary UI parts for login, logout, consent and error.
While the look & feel as well as the exact workflows will probably always differ in every IdentityServer implementation, we provide an MVC-based sample UI that you can use as a starting point.
This UI can be found in the Quickstart UI repo. You can clone or download this repo and drop the controllers, views, models and CSS into your IdentityServer web application.
Alternatively you can use the .NET CLI (run from within the src/IdentityServer folder):
dotnet new is4ui
Once you have added the MVC UI, you will also need to enable MVC, both in the DI system and in the pipeline.
When you look at Startup.cs you will find comments in the ConfigureServices and Configure method that tell you how to enable MVC.
Note
There is also a template called is4inmem which combines a basic IdentityServer including the standard UI.
Run the IdentityServer application, you should now see a home page.
Spend some time inspecting the controllers and models - especially the AccountController which is the main UI entry point.
The better you understand them, the easier it will be to make future modifications.
Most of the code lives in the “Quickstart” folder using a “feature folder” style.
If this style doesn’t suit you, feel free to organize the code in any way you want.
Creating an MVC client¶
Next you will create an MVC application. Use the ASP.NET Core “Web Application” (i.e. MVC) template for that. Once you’ve created the project, configure the application to run on port 5002.
To add support for OpenID Connect authentication to the MVC application, you first need to add the nuget package containing the OpenID Connect handler to your project, e.g.:
dotnet add package Microsoft.AspNetCore.Authentication.OpenIdConnect
..then add the following to ConfigureServices in Startup:
JwtSecurityTokenHandler.DefaultMapInboundClaims = false;
services.AddAuthentication(options =>
{
options.DefaultScheme = "Cookies";
options.DefaultChallengeScheme = "oidc";
})
.AddCookie("Cookies")
.AddOpenIdConnect("oidc", options =>
{
options.Authority = "http://localhost:5000";
options.RequireHttpsMetadata = false;
options.ClientId = "mvc";
options.ClientSecret = "secret";
options.ResponseType = "code";
options.SaveTokens = true;
});
AddAuthentication adds the authentication services to DI.
We are using a cookie to locally sign-in the user (via "Cookies" as the DefaultScheme),
and we set the DefaultChallengeScheme to oidc because when we need the user to login, we will be using the OpenID Connect protocol.
We then use AddCookie to add the handler that can process cookies.
Finally, AddOpenIdConnect is used to configure the handler that perform the OpenID Connect protocol.
The Authority indicates where the trusted token service is located.
We then identify this client via the ClientId and the ClientSecret.
SaveTokens is used to persist the tokens from IdentityServer in the cookie (as they will be needed later).
Note
We use the so called authorization code flow with PKCE to connect to the OpenID Connect provider. See here for more information on protocol flows.
And then to ensure the authentication services execute on each request, add UseAuthentication to Configure in Startup:
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute()
.RequireAuthorization();
});
Note
The RequireAuthorization method disables anonymous access for the entire application. You can also use the [Authorize] attribute, if you want to specify that on a per controller or action method basis.
Also modify the home view to display the claims of the user as well as the cookie properties:
@using Microsoft.AspNetCore.Authentication
<h2>Claims</h2>
<dl>
@foreach (var claim in User.Claims)
{
<dt>@claim.Type</dt>
<dd>@claim.Value</dd>
}
</dl>
<h2>Properties</h2>
<dl>
@foreach (var prop in (await Context.AuthenticateAsync()).Properties.Items)
{
<dt>@prop.Key</dt>
<dd>@prop.Value</dd>
}
</dl>
If you now navigate to the application using the browser, a redirect attempt will be made to IdentityServer - this will result in an error because the MVC client is not registered yet.
Adding support for OpenID Connect Identity Scopes¶
Similar to OAuth 2.0, OpenID Connect also uses the scopes concept. Again, scopes represent something you want to protect and that clients want to access. In contrast to OAuth, scopes in OIDC don’t represent APIs, but identity data like user id, name or email address.
Add support for the standard openid (subject id) and profile (first name, last name etc..) scopes
by ammending the Ids property in Config.cs:
public static IEnumerable<IdentityResource> Ids =>
new List<IdentityResource>
{
new IdentityResources.OpenId(),
new IdentityResources.Profile(),
};
Register the identity resources with IdentityServer in startup.cs:
var builder = services.AddIdentityServer()
.AddInMemoryIdentityResources(Config.Ids)
.AddInMemoryApiResources(Config.Apis)
.AddInMemoryClients(Config.Clients);
Note
All standard scopes and their corresponding claims can be found in the OpenID Connect specification
Adding Test Users¶
The sample UI also comes with an in-memory “user database”. You can enable this in IdentityServer by adding the AddTestUsers extension method:
var builder = services.AddIdentityServer()
.AddInMemoryIdentityResources(Config.Ids)
.AddInMemoryApiResources(Config.Apis)
.AddInMemoryClients(Config.Clients)
.AddTestUsers(TestUsers.Users);
When you navigate to the TestUsers class, you can see that two users called alice and bob as well as some identity claims are defined.
You can use those users to login.
Adding the MVC Client to the IdentityServer Configuration¶
The last step is to add a new configuration entry for the MVC client to IdentityServer.
OpenID Connect-based clients are very similar to the OAuth 2.0 clients we added so far. But since the flows in OIDC are always interactive, we need to add some redirect URLs to our configuration.
The client list should look like this:
public static IEnumerable<Client> Clients =>
new List<Client>
{
// machine to machine client (from quickstart 1)
new Client
{
ClientId = "client",
ClientSecrets = { new Secret("secret".Sha256()) },
AllowedGrantTypes = GrantTypes.ClientCredentials,
// scopes that client has access to
AllowedScopes = { "api1" }
},
// interactive ASP.NET Core MVC client
new Client
{
ClientId = "mvc",
ClientSecrets = { new Secret("secret".Sha256()) },
AllowedGrantTypes = GrantTypes.Code,
RequireConsent = false,
RequirePkce = true,
// where to redirect to after login
RedirectUris = { "http://localhost:5002/signin-oidc" },
// where to redirect to after logout
PostLogoutRedirectUris = { "http://localhost:5002/signout-callback-oidc" },
AllowedScopes = new List<string>
{
IdentityServerConstants.StandardScopes.OpenId,
IdentityServerConstants.StandardScopes.Profile
}
}
};
Testing the client¶
Now finally everything should be in place for the new MVC client.
Trigger the authentication handshake by navigating to the protected controller action. You should see a redirect to the login page at IdentityServer.
After that, IdentityServer will redirect back to the MVC client, where the OpenID Connect authentication handler processes the response and signs-in the user locally by setting a cookie. Finally the MVC view will show the contents of the cookie.
As you can see, the cookie has two parts, the claims of the user, and some metadata. This metadata also contains the original token that was issued by IdentityServer. Feel free to copy this token to jwt.ms to inspect its content.
Adding sign-out¶
The very last step is to add sign-out to the MVC client.
With an authentication service like IdentityServer, it is not enough to clear the local application cookies. In addition you also need to make a roundtrip to IdentityServer to clear the central single sign-on session.
The exact protocol steps are implemented inside the OpenID Connect handler, simply add the following code to some controller to trigger the sign-out:
public IActionResult Logout()
{
return SignOut("Cookies", "oidc");
}
This will clear the local cookie and then redirect to IdentityServer. IdentityServer will clear its cookies and then give the user a link to return back to the MVC application.
Further Experiments¶
Feel free to add more claims to the test users - and also more identity resources.
The process for defining an identity resource is as follows:
- add a new identity resource to the list - give it a name and specify which claims should be returned when this resource is requested
- give the client access to the resource via the
AllowedScopesproperty on the client configuration - request the resource by adding it to the
Scopescollection on the OpenID Connect handler configuration in the client
It is also noteworthy, that the retrieval of claims for tokens is an extensibility point - IProfileService.
Since we are using AddTestUsers, the TestUserProfileService is used by default.
You can inspect the source code here
to see how it works.
Adding Support for External Authentication¶
Next we will add support for external authentication. This is really easy, because all you really need is an ASP.NET Core compatible authentication handler.
ASP.NET Core itself ships with support for Google, Facebook, Twitter, Microsoft Account and OpenID Connect. In addition you can find implementations for many other authentication providers here.
Adding Google support¶
To be able to use Google for authentication, you first need to register with them. This is done at their developer console. Create a new project, enable the Google+ API and configure the callback address of your local IdentityServer by adding the /signin-google path to your base-address (e.g. http://localhost:5000/signin-google).
The developer console will show you a client ID and secret issued by Google - you will need that in the next step.
Add the Google authentication handler to the DI of the IdentityServer host.
This is done by first adding the Microsoft.AspNetCore.Authentication.Google nuget package and then adding this snippet to ConfigureServices in Startup:
services.AddAuthentication()
.AddGoogle("Google", options =>
{
options.SignInScheme = IdentityServerConstants.ExternalCookieAuthenticationScheme;
options.ClientId = "<insert here>";
options.ClientSecret = "<insert here>";
});
By default, IdentityServer configures a cookie handler specifically for the results of external authentication (with the scheme based on the constant IdentityServerConstants.ExternalCookieAuthenticationScheme).
The configuration for the Google handler is then using that cookie handler.
Now run the MVC client and try to authenticate - you will see a Google button on the login page:
After authentication with the MVC client, you can see that the claims are now being sourced from Google data.
Note
If you are interested in the magic that automatically renders the Google button on the login page, inspect the BuildLoginViewModel method on the AccountController.
Further experiments¶
You can add an additional external provider. We have a cloud-hosted demo version of IdentityServer4 which you can integrate using OpenID Connect.
Add the OpenId Connect handler to DI:
services.AddAuthentication()
.AddGoogle("Google", options =>
{
options.SignInScheme = IdentityServerConstants.ExternalCookieAuthenticationScheme;
options.ClientId = "<insert here>";
options.ClientSecret = "<insert here>";
})
.AddOpenIdConnect("oidc", "Demo IdentityServer", options =>
{
options.SignInScheme = IdentityServerConstants.ExternalCookieAuthenticationScheme;
options.SignOutScheme = IdentityServerConstants.SignoutScheme;
options.SaveTokens = true;
options.Authority = "https://demo.identityserver.io/";
options.ClientId = "native.code";
options.ClientSecret = "secret";
options.ResponseType = "code";
options.TokenValidationParameters = new TokenValidationParameters
{
NameClaimType = "name",
RoleClaimType = "role"
};
});
And now a user should be able to use the cloud-hosted demo identity provider.
Note
The quickstart UI auto-provisions external users. As an external user logs in for the first time, a new local user is created, and all the external claims are copied over and associated with the new user. The way you deal with such a situation is completely up to you though. Maybe you want to show some sort of registration UI first. The source code for the default quickstart can be found here. The controller where auto-provisioning is executed can be found here.
ASP.NET Core and API access¶
In the previous quickstarts we explored both API access and user authentication. Now we want to bring the two parts together.
The beauty of the OpenID Connect & OAuth 2.0 combination is, that you can achieve both with a single protocol and a single exchange with the token service.
So far we only asked for identity resources during the token request, once we start also including API resources, IdentityServer will return two tokens: the identity token containing the information about the authentication and session, and the access token to access APIs on behalf of the logged on user.
Modifying the client configuration¶
Updating the client configuration in IdentityServer is straightforward - we simply need to add the api1 resource to the allowed scopes list.
In addition we enable support for refresh tokens via the AllowOfflineAccess property:
new Client
{
ClientId = "mvc",
ClientSecrets = { new Secret("secret".Sha256()) },
AllowedGrantTypes = GrantTypes.Code,
RequireConsent = false,
RequirePkce = true,
// where to redirect to after login
RedirectUris = { "http://localhost:5002/signin-oidc" },
// where to redirect to after logout
PostLogoutRedirectUris = { "http://localhost:5002/signout-callback-oidc" },
AllowedScopes = new List<string>
{
IdentityServerConstants.StandardScopes.OpenId,
IdentityServerConstants.StandardScopes.Profile,
"api1"
},
AllowOfflineAccess = true
}
Modifying the MVC client¶
All that’s left to do now in the client is to ask for the additional resources via the scope parameter. This is done in the OpenID Connect handler configuration:
services.AddAuthentication(options =>
{
options.DefaultScheme = "Cookies";
options.DefaultChallengeScheme = "oidc";
})
.AddCookie("Cookies")
.AddOpenIdConnect("oidc", options =>
{
options.Authority = "http://localhost:5000";
options.RequireHttpsMetadata = false;
options.ClientId = "mvc";
options.ClientSecret = "secret";
options.ResponseType = "code";
options.SaveTokens = true;
options.Scope.Add("api1");
options.Scope.Add("offline_access");
});
Since SaveTokens is enabled, ASP.NET Core will automatically store the resulting access and refresh token in the authentication session.
You should be able to inspect the data on the page that prints out the contents of the session that you created earlier.
Using the access token¶
You can access the tokens in the session using the standard ASP.NET Core extension methods that you can find in the Microsoft.AspNetCore.Authentication namespace:
var accessToken = await HttpContext.GetTokenAsync(“access_token”) var refreshToken = await HttpContext.GetTokenAsync(“refresh_token”);
For accessing the API using the access token, all you need to do is retrieve the token, and set it on your HttpClient:
public async Task<IActionResult> CallApi()
{
var accessToken = await HttpContext.GetTokenAsync("access_token");
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
var content = await client.GetStringAsync("http://localhost:5001/identity");
ViewBag.Json = JArray.Parse(content).ToString();
return View("json");
}
Create a view called json.cshtml that outputs the json like this:
<pre>@ViewBag.Json</pre>
Make sure the API is running, start the MVC client and call /home/CallApi after authentication.
Managing the access token¶
By far the most complex task for a typical client is to manage the access token. You typically want to
- request the access and refresh token at login time
- cache those tokens
- use the access token to call APIs until it expires
- use the refresh token to get a new access token
- start over
ASP.NET Core has many built-in facility that can help you with those tasks (like caching or sessions), but there is still quite some work left to do. Feel free to have a look at this library, which can automate many of the boilerplate tasks.
Using EntityFramework Core for configuration and operational data¶
In the previous quickstarts, we created our client and scope data in code. On startup, IdentityServer loaded this configuration data into memory. If we wanted to modify this configuration data, we had to stop and start IdentityServer.
IdentityServer also generates temporary data, such as authorization codes, consent choices, and refresh tokens. By default, these are also stored in-memory.
To move this data into a database that is persistent between restarts and across multiple IdentityServer instances, we can use the IdentityServer4 Entity Framework library.
Note
In addition to manually configuring EF support, there is also an IdentityServer template to create a new project with EF support, using dotnet new is4ef.
IdentityServer4.EntityFramework¶
IdentityServer4.EntityFramework implements the required stores and services using the following DbContext’s:
- ConfigurationDbContext - used for configuration data such as clients, resources, and scopes
- PersistedGrantDbContext - used for temporary operational data such as authorization codes, and refresh tokens
These contexts are suitable for any Entity Framework Core compatible relational database.
You can find these contexts, their entities, and the IdentityServer4 stores that use them in the IdentityServer4.EntityFramework.Storage nuget package.
You can find the extension methods to register them in your IdentityServer in IdentityServer4.EntityFramework, which we will do now:
dotnet add package IdentityServer4.EntityFramework
Using SqlServer¶
For this quickstart, we will use the LocalDb version of SQLServer that comes with Visual Studio. To add SQL Server support to our IdentityServer project, you’ll need the following nuget package:
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
Database Schema Changes and Using EF Migrations¶
The IdentityServer4.EntityFramework.Storage package contains entity classes that map from IdentityServer’s models
As IdentityServer’s models change, so will the entity classes in IdentityServer4.EntityFramework.Storage.
As you use IdentityServer4.EntityFramework.Storage and upgrade over time, you are responsible for your database schema and changes necessary to that schema as the entity classes change.
One approach for managing those changes is to use EF migrations, which is what we’ll use in this quickstart.
If migrations are not your preference, then you can manage the schema changes in any way you see fit.
Note
You can find the latest SQL scripts for SqlServer in the IdentityServer4.EntityFramework.Storage repository.
Configuring the Stores¶
To start using these stores, you’ll need to replace any existing calls to AddInMemoryClients, AddInMemoryIdentityResources, AddInMemoryApiResources, and AddInMemoryPersistedGrants in your ConfigureServices method in Startup.cs with AddConfigurationStore and AddOperationalStore.
These methods each require a DbContextOptionsBuilder, meaning your code will look something like this:
var migrationsAssembly = typeof(Startup).GetTypeInfo().Assembly.GetName().Name;
const string connectionString = @"Data Source=(LocalDb)\MSSQLLocalDB;database=IdentityServer4.Quickstart.EntityFramework-3.0.0;trusted_connection=yes;";
services.AddIdentityServer()
.AddTestUsers(TestUsers.Users)
.AddConfigurationStore(options =>
{
options.ConfigureDbContext = b => b.UseSqlServer(connectionString,
sql => sql.MigrationsAssembly(migrationsAssembly));
})
.AddOperationalStore(options =>
{
options.ConfigureDbContext = b => b.UseSqlServer(connectionString,
sql => sql.MigrationsAssembly(migrationsAssembly));
});
You might need these namespaces added to the file:
using Microsoft.EntityFrameworkCore;
using System.Reflection;
Because we are using EF migrations in this quickstart, the call to MigrationsAssembly is used to inform Entity Framework that the host project will contain the migrations code.
This is necessary since the host project is in a different assembly than the one that contains the DbContext classes.
Adding Migrations¶
Once the IdentityServer has been configured to use Entity Framework, we’ll need to generate some migrations.
To create migrations, you will need to install the Entity Framework Core CLI on your machine and the Microsoft.EntityFrameworkCore.Design nuget package in IdentityServer:
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.Design
To create the migrations, open a command prompt in the IdentityServer project directory and run the following two commands:
dotnet ef migrations add InitialIdentityServerPersistedGrantDbMigration -c PersistedGrantDbContext -o Data/Migrations/IdentityServer/PersistedGrantDb
dotnet ef migrations add InitialIdentityServerConfigurationDbMigration -c ConfigurationDbContext -o Data/Migrations/IdentityServer/ConfigurationDb
You should now see a ~/Data/Migrations/IdentityServer folder in your project containing the code for your newly created migrations.
Initializing the Database¶
Now that we have the migrations, we can write code to create the database from the migrations. We can also seed the database with the in-memory configuration data that we already defined in the previous quickstarts.
Note
The approach used in this quickstart is used to make it easy to get IdentityServer up and running. You should devise your own database creation and maintenance strategy that is appropriate for your architecture.
In Startup.cs add this method to help initialize the database:
private void InitializeDatabase(IApplicationBuilder app)
{
using (var serviceScope = app.ApplicationServices.GetService<IServiceScopeFactory>().CreateScope())
{
serviceScope.ServiceProvider.GetRequiredService<PersistedGrantDbContext>().Database.Migrate();
var context = serviceScope.ServiceProvider.GetRequiredService<ConfigurationDbContext>();
context.Database.Migrate();
if (!context.Clients.Any())
{
foreach (var client in Config.Clients)
{
context.Clients.Add(client.ToEntity());
}
context.SaveChanges();
}
if (!context.IdentityResources.Any())
{
foreach (var resource in Config.Ids)
{
context.IdentityResources.Add(resource.ToEntity());
}
context.SaveChanges();
}
if (!context.ApiResources.Any())
{
foreach (var resource in Config.Apis)
{
context.ApiResources.Add(resource.ToEntity());
}
context.SaveChanges();
}
}
}
The above code may require you to add the following namespaces to your file:
using System.Linq;
using IdentityServer4.EntityFramework.DbContexts;
using IdentityServer4.EntityFramework.Mappers;
And then we can invoke this from the Configure method:
public void Configure(IApplicationBuilder app)
{
// this will do the initial DB population
InitializeDatabase(app);
// the rest of the code that was already here
// ...
}
Now if you run the IdentityServer project, the database should be created and seeded with the quickstart configuration data. You should be able to use SQL Server Management Studio or Visual Studio to connect and inspect the data.
Note
The above InitializeDatabase helper API is convenient to seed the database, but this approach is not ideal to leave in to execute each time the applicaion runs. Once your database is populated, consider removing the call to the API.
Run the client applications¶
You should now be able to run any of the existing client applications and sign-in, get tokens, and call the API – all based upon the database configuration.
Startup¶
IdentityServer is a combination of middleware and services. All configuration is done in your startup class.
Configuring services¶
You add the IdentityServer services to the DI system by calling:
public void ConfigureServices(IServiceCollection services)
{
var builder = services.AddIdentityServer();
}
Optionally you can pass in options into this call. See here for details on options.
This will return you a builder object that in turn has a number of convenience methods to wire up additional services.
Key material¶
IdentityServer supports X.509 certificates (both raw files and a reference to the Windows certificate store), RSA keys and EC keys for token signatures and validation. Each key can be configured with a (compatible) signing algorith, e.g. RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 or ES512.
You can configure the key material with the following methods:
AddSigningCredential- Adds a signing key service that provides the specified key material to the various token creation/validation services.
AddDeveloperSigningCredential- Creates temporary key material at startup time. This is for dev scenarios. The generated key will be persisted in the local directory by default.
AddValidationKey- Adds a key for validating tokens. They will be used by the internal token validator and will show up in the discovery document.
In-Memory configuration stores¶
The various “in-memory” configuration APIs allow for configuring IdentityServer from an in-memory list of configuration objects. These “in-memory” collections can be hard-coded in the hosting application, or could be loaded dynamically from a configuration file or a database. By design, though, these collections are only created when the hosting application is starting up.
Use of these configuration APIs are designed for use when prototyping, developing, and/or testing where it is not necessary to dynamically consult database at runtime for the configuration data. This style of configuration might also be appropriate for production scenarios if the configuration rarely changes, or it is not inconvenient to require restarting the application if the value must be changed.
AddInMemoryClients- Registers
IClientStoreandICorsPolicyServiceimplementations based on the in-memory collection ofClientconfiguration objects.
AddInMemoryIdentityResources- Registers
IResourceStoreimplementation based on the in-memory collection ofIdentityResourceconfiguration objects.
AddInMemoryApiResources- Registers
IResourceStoreimplementation based on the in-memory collection ofApiResourceconfiguration objects.
Test stores¶
The TestUser class models a user, their credentials, and claims in IdentityServer.
Use of TestUser is similar to the use of the “in-memory” stores in that it is intended for when prototyping, developing, and/or testing.
The use of TestUser is not recommended in production.
AddTestUsers- Registers
TestUserStorebased on a collection ofTestUserobjects.TestUserStoreis used by the default quickstart UI. Also registers implementations ofIProfileServiceandIResourceOwnerPasswordValidator.
Additional services¶
AddExtensionGrantValidator- Adds
IExtensionGrantValidatorimplementation for use with extension grants.
AddSecretParser- Adds
ISecretParserimplementation for parsing client or API resource credentials.
AddSecretValidator- Adds
ISecretValidatorimplementation for validating client or API resource credentials against a credential store.
AddResourceOwnerValidator- Adds
IResourceOwnerPasswordValidatorimplementation for validating user credentials for the resource owner password credentials grant type.
AddProfileService- Adds
IProfileServiceimplementation for connecting to your custom user profile store. TheDefaultProfileServiceclass provides the default implementation which relies upon the authentication cookie as the only source of claims for issuing in tokens.
AddAuthorizeInteractionResponseGenerator- Adds
IAuthorizeInteractionResponseGeneratorimplementation to customize logic at authorization endpoint for when a user must be shown a UI for error, login, consent, or any other custom page. TheAuthorizeInteractionResponseGeneratorclass provides a default implementation, so consider deriving from this existing class if you need to augment the existing behavior.
AddCustomAuthorizeRequestValidator- Adds
ICustomAuthorizeRequestValidatorimplementation to customize request parameter validation at the authorization endpoint.
AddCustomTokenRequestValidator- Adds
ICustomTokenRequestValidatorimplementation to customize request parameter validation at the token endpoint.
AddRedirectUriValidator- Adds
IRedirectUriValidatorimplementation to customize redirect URI validation.
AddAppAuthRedirectUriValidator- Adds a an “AppAuth” (OAuth 2.0 for Native Apps) compliant redirect URI validator (does strict validation but also allows http://127.0.0.1 with random port).
AddJwtBearerClientAuthentication- Adds support for client authentication using JWT bearer assertions.
AddMutualTlsSecretValidators- Adds the X509 secret validators for mutual TLS.
Caching¶
Client and resource configuration data is used frequently by IdentityServer. If this data is being loaded from a database or other external store, then it might be expensive to frequently re-load the same data.
AddInMemoryCaching- To use any of the caches described below, an implementation of
ICache<T>must be registered in DI. This API registers a default in-memory implementation ofICache<T>that’s based on ASP.NET Core’sMemoryCache.
AddClientStoreCache- Registers a
IClientStoredecorator implementation which will maintain an in-memory cache ofClientconfiguration objects. The cache duration is configurable on theCachingconfiguration options on theIdentityServerOptions.
AddResourceStoreCache- Registers a
IResourceStoredecorator implementation which will maintain an in-memory cache ofIdentityResourceandApiResourceconfiguration objects. The cache duration is configurable on theCachingconfiguration options on theIdentityServerOptions.
AddCorsPolicyCache- Registers a
ICorsPolicyServicedecorator implementation which will maintain an in-memory cache of the results of the CORS policy service evaluation. The cache duration is configurable on theCachingconfiguration options on theIdentityServerOptions.
Further customization of the cache is possible:
The default caching relies upon the ICache<T> implementation.
If you wish to customize the caching behavior for the specific configuration objects, you can replace this implementation in the dependency injection system.
The default implementation of the ICache<T> itself relies upon the IMemoryCache interface (and MemoryCache implementation) provided by .NET.
If you wish to customize the in-memory caching behavior, you can replace the IMemoryCache implementation in the dependency injection system.
Configuring the pipeline¶
You need to add IdentityServer to the pipeline by calling:
public void Configure(IApplicationBuilder app)
{
app.UseIdentityServer();
}
Note
UseIdentityServer includes a call to UseAuthentication, so it’s not necessary to have both.
There is no additional configuration for the middleware.
Be aware that order matters in the pipeline. For example, you will want to add IdentitySever before the UI framework that implements the login screen.
Defining Resources¶
The first thing you will typically define in your system are the resources that you want to protect. That could be identity information of your users, like profile data or email addresses, or access to APIs.
Note
You can define resources using a C# object model - or load them from a data store. An implementation of IResourceStore deals with these low-level details. For this document we are using the in-memory implementation.
Defining identity resources¶
Identity resources are data like user ID, name, or email address of a user.
An identity resource has a unique name, and you can assign arbitrary claim types to it. These claims will then be included in the identity token for the user.
The client will use the scope parameter to request access to an identity resource.
The OpenID Connect specification specifies a couple of standard identity resources.
The minimum requirement is, that you provide support for emitting a unique ID for your users - also called the subject id.
This is done by exposing the standard identity resource called openid:
public static IEnumerable<IdentityResource> GetIdentityResources()
{
return new List<IdentityResource>
{
new IdentityResources.OpenId()
};
}
The IdentityResources class supports all scopes defined in the specification (openid, email, profile, telephone, and address). If you want to support them all, you can add them to your list of supported identity resources:
public static IEnumerable<IdentityResource> GetIdentityResources()
{
return new List<IdentityResource>
{
new IdentityResources.OpenId(),
new IdentityResources.Email(),
new IdentityResources.Profile(),
new IdentityResources.Phone(),
new IdentityResources.Address()
};
}
Defining custom identity resources¶
You can also define custom identity resources. Create a new IdentityResource class, give it a name and optionally a display name and description and define which user claims should be included in the identity token when this resource gets requested:
public static IEnumerable<IdentityResource> GetIdentityResources()
{
var customProfile = new IdentityResource(
name: "custom.profile",
displayName: "Custom profile",
claimTypes: new[] { "name", "email", "status" });
return new List<IdentityResource>
{
new IdentityResources.OpenId(),
new IdentityResources.Profile(),
customProfile
};
}
See the reference section for more information on identity resource settings.
Defining API resources¶
To allow clients to request access tokens for APIs, you need to define API resources, e.g.:
To get access tokens for APIs, you also need to register them as a scope. This time the scope type is of type Resource:
public static IEnumerable<ApiResource> GetApis()
{
return new[]
{
// simple API with a single scope (in this case the scope name is the same as the api name)
new ApiResource("api1", "Some API 1"),
// expanded version if more control is needed
new ApiResource
{
Name = "api2",
// secret for using introspection endpoint
ApiSecrets =
{
new Secret("secret".Sha256())
},
// include the following using claims in access token (in addition to subject id)
UserClaims = { JwtClaimTypes.Name, JwtClaimTypes.Email },
// this API defines two scopes
Scopes =
{
new Scope()
{
Name = "api2.full_access",
DisplayName = "Full access to API 2",
},
new Scope
{
Name = "api2.read_only",
DisplayName = "Read only access to API 2"
}
}
}
};
}
See the reference section for more information on API resource settings.
Note
The user claims defined by resources are used to tell the IProfileService extensibility point which claims to include in tokens.
Defining Clients¶
Clients represent applications that can request tokens from your identityserver.
The details vary, but you typically define the following common settings for a client:
- a unique client ID
- a secret if needed
- the allowed interactions with the token service (called a grant type)
- a network location where identity and/or access token gets sent to (called a redirect URI)
- a list of scopes (aka resources) the client is allowed to access
Note
At runtime, clients are retrieved via an implementation of the IClientStore. This allows loading them from arbitrary data sources like config files or databases. For this document we will use the in-memory version of the client store. You can wire up the in-memory store in ConfigureServices via the AddInMemoryClients extensions method.
Defining a client for server to server communication¶
In this scenario no interactive user is present - a service (aka client) wants to communicate with an API (aka scope):
public class Clients
{
public static IEnumerable<Client> Get()
{
return new List<Client>
{
new Client
{
ClientId = "service.client",
ClientSecrets = { new Secret("secret".Sha256()) },
AllowedGrantTypes = GrantTypes.ClientCredentials,
AllowedScopes = { "api1", "api2.read_only" }
}
};
}
}
Defining browser-based JavaScript client (e.g. SPA) for user authentication and delegated access and API¶
This client uses the so called implicit flow to request an identity and access token from JavaScript:
var jsClient = new Client
{
ClientId = "js",
ClientName = "JavaScript Client",
ClientUri = "http://identityserver.io",
AllowedGrantTypes = GrantTypes.Implicit,
AllowAccessTokensViaBrowser = true,
RedirectUris = { "http://localhost:7017/index.html" },
PostLogoutRedirectUris = { "http://localhost:7017/index.html" },
AllowedCorsOrigins = { "http://localhost:7017" },
AllowedScopes =
{
IdentityServerConstants.StandardScopes.OpenId,
IdentityServerConstants.StandardScopes.Profile,
IdentityServerConstants.StandardScopes.Email,
"api1", "api2.read_only"
}
};
Defining a server-side web application (e.g. MVC) for use authentication and delegated API access¶
Interactive server side (or native desktop/mobile) applications use the hybrid flow. This flow gives you the best security because the access tokens are transmitted via back-channel calls only (and gives you access to refresh tokens):
var mvcClient = new Client
{
ClientId = "mvc",
ClientName = "MVC Client",
ClientUri = "http://identityserver.io",
AllowedGrantTypes = GrantTypes.Hybrid,
AllowOfflineAccess = true,
ClientSecrets = { new Secret("secret".Sha256()) },
RedirectUris = { "http://localhost:21402/signin-oidc" },
PostLogoutRedirectUris = { "http://localhost:21402/" },
FrontChannelLogoutUri = "http://localhost:21402/signout-oidc",
AllowedScopes =
{
IdentityServerConstants.StandardScopes.OpenId,
IdentityServerConstants.StandardScopes.Profile,
IdentityServerConstants.StandardScopes.Email,
"api1", "api2.read_only"
},
};
Defining clients in appsettings.json¶
The AddInMemoryClients extensions method also supports adding clients from the ASP.NET Core configuration file. This allows you to define static clients directly from the appsettings.json file:
"IdentityServer": {
"IssuerUri": "urn:sso.company.com",
"Clients": [
{
"Enabled": true,
"ClientId": "local-dev",
"ClientName": "Local Development",
"ClientSecrets": [ { "Value": "<Insert Sha256 hash of the secret encoded as Base64 string>" } ],
"AllowedGrantTypes": [ "implicit" ],
"AllowedScopes": [ "openid", "profile" ],
"RedirectUris": [ "https://localhost:5001/signin-oidc" ],
"RequireConsent": false
}
]
}
Then pass the configuration section to the AddInMemoryClients method:
AddInMemoryClients(configuration.GetSection("IdentityServer:Clients"))
Sign-in¶
In order for IdentityServer to issue tokens on behalf of a user, that user must sign-in to IdentityServer.
Cookie authentication¶
Authentication is tracked with a cookie managed by the cookie authentication handler from ASP.NET Core.
IdentityServer registers two cookie handlers (one for the authentication session and one for temporary external cookies). These are used by default and you can get their
names from the IdentityServerConstants class (DefaultCookieAuthenticationScheme and ExternalCookieAuthenticationScheme) if you want to reference them manually.
We only expose basic settings for these cookies (expiration and sliding), and you can register your own cookie handlers if you need more control.
IdentityServer uses whichever cookie handler matches the DefaultAuthenticateScheme as configured on the AuthenticationOptions when using AddAuthentication from ASP.NET Core.
Overriding cookie handler configuration¶
If you wish to use your own cookie authentication handler, then you must configure it yourself.
This must be done in ConfigureServices after registering IdentityServer in DI (with AddIdentityServer).
For example:
services.AddIdentityServer()
.AddInMemoryClients(Clients.Get())
.AddInMemoryIdentityResources(Resources.GetIdentityResources())
.AddInMemoryApiResources(Resources.GetApiResources())
.AddDeveloperSigningCredential()
.AddTestUsers(TestUsers.Users);
services.AddAuthentication("MyCookie")
.AddCookie("MyCookie", options =>
{
options.ExpireTimeSpan = ...;
});
Note
IdentityServer internally calls both AddAuthentication and AddCookie with a custom scheme (via the constant IdentityServerConstants.DefaultCookieAuthenticationScheme), so to override them you must make the same calls after AddIdentityServer.
Login User Interface and Identity Management System¶
IdentityServer does not provide any user-interface or user database for user authentication. These are things you are expected to provide or develop yourself.
If you need a starting point for a basic UI (login, logout, consent and manage grants), you can use our quickstart UI.
The quickstart UI authenticates users against an in-memory database. You would replace those bits with access to your real user store. We have samples that use ASP.NET Identity.
Login Workflow¶
When IdentityServer receives a request at the authorization endpoint and the user is not authenticated, the user will be redirected to the configured login page.
You must inform IdentityServer of the path to your login page via the UserInteraction settings on the options (the default is /account/login).
A returnUrl parameter will be passed informing your login page where the user should be redirected once login is complete.
Note
Beware open-redirect attacks via the returnUrl parameter. You should validate that the returnUrl refers to well-known location. See the interaction service for APIs to validate the returnUrl parameter.
Login Context¶
On your login page you might require information about the context of the request in order to customize the login experience
(such as client, prompt parameter, IdP hint, or something else).
This is made available via the GetAuthorizationContextAsync API on the interaction service.
Issuing a cookie and Claims¶
There are authentication-related extension methods on the HttpContext from ASP.NET Core to issue the authentication cookie and sign a user in.
The authentication scheme used must match the cookie handler you are using (see above).
When you sign the user in you must issue at least a sub claim and a name claim.
IdentityServer also provides a few SignInAsync extension methods on the HttpContext to make this more convenient.
You can also optionally issue an idp claim (for the identity provider name), an amr claim (for the authentication method used), and/or an auth_time claim (for the epoch time a user authenticated).
If you do not provide these, then IdentityServer will provide default values.
Sign-in with External Identity Providers¶
ASP.NET Core has a flexible way to deal with external authentication. This involves a couple of steps.
Note
If you are using ASP.NET Identity, many of the underlying technical details are hidden from you. It is recommended that you also read the Microsoft docs and do the ASP.NET Identity quickstart.
Adding authentication handlers for external providers¶
The protocol implementation that is needed to talk to an external provider is encapsulated in an authentication handler. Some providers use proprietary protocols (e.g. social providers like Facebook) and some use standard protocols, e.g. OpenID Connect, WS-Federation or SAML2p.
See this quickstart for step-by-step instructions for adding external authentication and configuring it.
The role of cookies¶
One option on an external authentication handlers is called SignInScheme, e.g.:
services.AddAuthentication()
.AddGoogle("Google", options =>
{
options.SignInScheme = "scheme of cookie handler to use";
options.ClientId = "...";
options.ClientSecret = "...";
})
The signin scheme specifies the name of the cookie handler that will temporarily store the outcome of the external authentication, e.g. the claims that got sent by the external provider. This is necessary, since there are typically a couple of redirects involved until you are done with the external authentication process.
Given that this is such a common practise, IdentityServer registers a cookie handler specifically for this external provider workflow.
The scheme is represented via the IdentityServerConstants.ExternalCookieAuthenticationScheme constant.
If you were to use our external cookie handler, then for the SignInScheme above you’d assign the value to be the IdentityServerConstants.ExternalCookieAuthenticationScheme constant:
services.AddAuthentication()
.AddGoogle("Google", options =>
{
options.SignInScheme = IdentityServerConstants.ExternalCookieAuthenticationScheme;
options.ClientId = "...";
options.ClientSecret = "...";
})
You can also register your own custom cookie handler instead, like this:
services.AddAuthentication()
.AddCookie("YourCustomScheme")
.AddGoogle("Google", options =>
{
options.SignInScheme = "YourCustomScheme";
options.ClientId = "...";
options.ClientSecret = "...";
})
Note
For specialized scenarios, you can also short-circuit the external cookie mechanism and forward the external user directly to the main cookie handler. This typically involves handling events on the external handler to make sure you do the correct claims transformation from the external identity source.
Triggering the authentication handler¶
You invoke an external authentication handler via the ChallengeAsync extension method on the HttpContext (or using the MVC ChallengeResult).
You typically want to pass in some options to the challenge operation, e.g. the path to your callback page and the name of the provider for bookkeeping, e.g.:
var callbackUrl = Url.Action("ExternalLoginCallback");
var props = new AuthenticationProperties
{
RedirectUri = callbackUrl,
Items =
{
{ "scheme", provider },
{ "returnUrl", returnUrl }
}
};
return Challenge(provider, props);
Handling the callback and signing in the user¶
On the callback page your typical tasks are:
- inspect the identity returned by the external provider.
- make a decision how you want to deal with that user. This might be different based on the fact if this is a new user or a returning user.
- new users might need additional steps and UI before they are allowed in.
- probably create a new internal user account that is linked to the external provider.
- store the external claims that you want to keep.
- delete the temporary cookie
- sign-in the user
Inspecting the external identity:
// read external identity from the temporary cookie
var result = await HttpContext.AuthenticateAsync(IdentityServerConstants.ExternalCookieAuthenticationScheme);
if (result?.Succeeded != true)
{
throw new Exception("External authentication error");
}
// retrieve claims of the external user
var externalUser = result.Principal;
if (externalUser == null)
{
throw new Exception("External authentication error");
}
// retrieve claims of the external user
var claims = externalUser.Claims.ToList();
// try to determine the unique id of the external user - the most common claim type for that are the sub claim and the NameIdentifier
// depending on the external provider, some other claim type might be used
var userIdClaim = claims.FirstOrDefault(x => x.Type == JwtClaimTypes.Subject);
if (userIdClaim == null)
{
userIdClaim = claims.FirstOrDefault(x => x.Type == ClaimTypes.NameIdentifier);
}
if (userIdClaim == null)
{
throw new Exception("Unknown userid");
}
var externalUserId = userIdClaim.Value;
var externalProvider = userIdClaim.Issuer;
// use externalProvider and externalUserId to find your user, or provision a new user
Clean-up and sign-in:
// issue authentication cookie for user
await HttpContext.SignInAsync(user.SubjectId, user.Username, provider, props, additionalClaims.ToArray());
// delete temporary cookie used during external authentication
await HttpContext.SignOutAsync(IdentityServerConstants.ExternalCookieAuthenticationScheme);
// validate return URL and redirect back to authorization endpoint or a local page
if (_interaction.IsValidReturnUrl(returnUrl) || Url.IsLocalUrl(returnUrl))
{
return Redirect(returnUrl);
}
return Redirect("~/");
State, URL length, and ISecureDataFormat¶
When redirecting to an external provider for sign-in, frequently state from the client application must be round-tripped.
This means that state is captured prior to leaving the client and preserved until the user has returned to the client application.
Many protocols, including OpenID Connect, allow passing some sort of state as a parameter as part of the request, and the identity provider will return that state on the response.
The OpenID Connect authentication handler provided by ASP.NET Core utilizes this feature of the protocol, and that is how it implements the returnUrl feature mentioned above.
The problem with storing state in a request parameter is that the request URL can get too large (over the common limit of 2000 characters).
The OpenID Connect authentication handler does provide an extensibility point to store the state in your server, rather than in the request URL.
You can implement this yourself by implementing ISecureDataFormat<AuthenticationProperties> and configuring it on the OpenIdConnectOptions.
Fortunately, IdentityServer provides an implementation of this for you, backed by the IDistributedCache implementation registered in the DI container (e.g. the standard MemoryDistributedCache).
To use the IdentityServer provided secure data format implementation, simply call the AddOidcStateDataFormatterCache extension method on the IServiceCollection when configuring DI.
If no parameters are passed, then all OpenID Connect handlers configured will use the IdentityServer provided secure data format implementation:
public void ConfigureServices(IServiceCollection services)
{
// configures the OpenIdConnect handlers to persist the state parameter into the server-side IDistributedCache.
services.AddOidcStateDataFormatterCache();
services.AddAuthentication()
.AddOpenIdConnect("demoidsrv", "IdentityServer", options =>
{
// ...
})
.AddOpenIdConnect("aad", "Azure AD", options =>
{
// ...
})
.AddOpenIdConnect("adfs", "ADFS", options =>
{
// ...
});
}
If only particular schemes are to be configured, then pass those schemes as parameters:
public void ConfigureServices(IServiceCollection services)
{
// configures the OpenIdConnect handlers to persist the state parameter into the server-side IDistributedCache.
services.AddOidcStateDataFormatterCache("aad", "demoidsrv");
services.AddAuthentication()
.AddOpenIdConnect("demoidsrv", "IdentityServer", options =>
{
// ...
})
.AddOpenIdConnect("aad", "Azure AD", options =>
{
// ...
})
.AddOpenIdConnect("adfs", "ADFS", options =>
{
// ...
});
}
Windows Authentication¶
On supported platforms, you can use IdentityServer to authenticate users using Windows authentication (e.g. against Active Directory). Currently Windows authentication is available when you host IdentityServer using:
In both cases, Windows authentication is triggered by using the ChallengeAsync API on the HttpContext using the scheme "Windows".
The account controller in our quickstart UI implements the necessary logic.
Using Kestrel¶
When using Kestrel, you must run “behind” IIS and use the IIS integration:
var host = new WebHostBuilder()
.UseKestrel()
.UseUrls("http://localhost:5000")
.UseContentRoot(Directory.GetCurrentDirectory())
.UseIISIntegration()
.UseStartup<Startup>()
.Build();
Kestrel is automatically configured when using the WebHost.CreateDefaultBuilder approach for setting up the WebHostBuilder.
Also the virtual directory in IIS (or IIS Express) must have Windows and anonymous authentication enabled.
The IIS integration layer will configure a Windows authentication handler into DI that can be invoked via the authentication service.
Typically in IdentityServer it is advisable to disable this automatic behavior.
This is done in ConfigureServices:
services.Configure<IISOptions>(iis =>
{
iis.AuthenticationDisplayName = "Windows";
iis.AutomaticAuthentication = false;
});
Note
By default, the display name is empty, and the Windows authentication button will not show up in the quickstart UI. You need to set a display name if you rely on automatic discovery of external providers.
Sign-out¶
Signing out of IdentityServer is as simple as removing the authentication cookie, but for doing a complete federated sign-out, we must consider signing the user out of the client applications (and maybe even up-stream identity providers) as well.
Removing the authentication cookie¶
To remove the authentication cookie, simply use the SignOutAsync extension method on the HttpContext.
You will need to pass the scheme used (which is provided by IdentityServerConstants.DefaultCookieAuthenticationScheme unless you have changed it):
await HttpContext.SignOutAsync(IdentityServerConstants.DefaultCookieAuthenticationScheme);
Or you can use the convenience extension method that is provided by IdentityServer:
await HttpContext.SignOutAsync();
Note
Typically you should prompt the user for signout (meaning require a POST), otherwise an attacker could hotlink to your logout page causing the user to be automatically logged out.
Notifying clients that the user has signed-out¶
As part of the signout process you will want to ensure client applications are informed that the user has signed out. IdentityServer supports the front-channel specification for server-side clients (e.g. MVC), the back-channel specification for server-side clients (e.g. MVC), and the session management specification for browser-based JavaScript clients (e.g. SPA, React, Angular, etc.).
Front-channel server-side clients
To signout the user from the server-side client applications via the front-channel spec, the “logged out” page in IdentityServer must render an <iframe> to notify the clients that the user has signed out.
Clients that wish to be notified must have the FrontChannelLogoutUri configuration value set.
IdentityServer tracks which clients the user has signed into, and provides an API called GetLogoutContextAsync on the IIdentityServerInteractionService (details).
This API returns a LogoutRequest object with a SignOutIFrameUrl property that your logged out page must render into an <iframe>.
Back-channel server-side clients
To signout the user from the server-side client applications via the back-channel spec, the SignOutIFrameUrl endpoint in IdentityServer will automatically trigger server-to-server invocation passing a signed sign-out request to the client.
This means that even if there are no front-channel clients, the “logged out” page in IdentityServer must still render an <iframe> to the SignOutIFrameUrl as described above.
Clients that wish to be notified must have the BackChannelLogoutUri configuration value set.
Browser-based JavaScript clients
Given how the session management specification is designed, there is nothing special in IdentityServer that you need to do to notify these clients that the user has signed out. The clients, though, must perform monitoring on the check_session_iframe, and this is implemented by the oidc-client JavaScript library.
Sign-out initiated by a client application¶
If sign-out was initiated by a client application, then the client first redirected the user to the end session endpoint. Processing at the end session endpoint might require some temporary state to be maintained (e.g. the client’s post logout redirect uri) across the redirect to the logout page. This state might be of use to the logout page, and the identifier for the state is passed via a logoutId parameter to the logout page.
The GetLogoutContextAsync API on the interaction service can be used to load the state.
Of interest on the ShowSignoutPrompt is the ShowSignoutPrompt which indicates if the request for sign-out has been authenticated, and therefore it’s safe to not prompt the user for sign-out.
By default this state is managed as a protected data structure passed via the logoutId value.
If you wish to use some other persistence between the end session endpoint and the logout page, then you can implement IMessageStore<LogoutMessage> and register the implementation in DI.
Sign-out of External Identity Providers¶
When a user is signing-out of IdentityServer, and they have used an external identity provider to sign-in then it is likely that they should be redirected to also sign-out of the external provider. Not all external providers support sign-out, as it depends on the protocol and features they support.
To detect that a user must be redirected to an external identity provider for sign-out is typically done by using a idp claim issued into the cookie at IdentityServer.
The value set into this claim is the AuthenticationScheme of the corresponding authentication middleware.
At sign-out time this claim is consulted to know if an external sign-out is required.
Redirecting the user to an external identity provider is problematic due to the cleanup and state management already required by the normal sign-out workflow. The only way to then complete the normal sign-out and cleanup process at IdentityServer is to then request from the external identity provider that after its logout that the user be redirected back to IdentityServer. Not all external providers support post-logout redirects, as it depends on the protocol and features they support.
The workflow at sign-out is then to revoke IdentityServer’s authentication cookie, and then redirect to the external provider requesting a post-logout redirect.
The post-logout redirect should maintain the necessary sign-out state described here (i.e. the logoutId parameter value).
To redirect back to IdentityServer after the external provider sign-out, the RedirectUri should be used on the AuthenticationProperties when using ASP.NET Core’s SignOutAsync API, for example:
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Logout(LogoutInputModel model)
{
// build a model so the logged out page knows what to display
var vm = await _account.BuildLoggedOutViewModelAsync(model.LogoutId);
var user = HttpContext.User;
if (user?.Identity.IsAuthenticated == true)
{
// delete local authentication cookie
await HttpContext.SignOutAsync();
// raise the logout event
await _events.RaiseAsync(new UserLogoutSuccessEvent(user.GetSubjectId(), user.GetName()));
}
// check if we need to trigger sign-out at an upstream identity provider
if (vm.TriggerExternalSignout)
{
// build a return URL so the upstream provider will redirect back
// to us after the user has logged out. this allows us to then
// complete our single sign-out processing.
string url = Url.Action("Logout", new { logoutId = vm.LogoutId });
// this triggers a redirect to the external provider for sign-out
return SignOut(new AuthenticationProperties { RedirectUri = url }, vm.ExternalAuthenticationScheme);
}
return View("LoggedOut", vm);
}
Once the user is signed-out of the external provider and then redirected back, the normal sign-out processing at IdentityServer should execute which involves processing the logoutId and doing all necessary cleanup.
Federated Sign-out¶
Federated sign-out is the situation where a user has used an external identity provider to log into IdentityServer, and then the user logs out of that external identity provider via a workflow unknown to IdentityServer. When the user signs out, it will be useful for IdentityServer to be notified so that it can sign the user out of IdentityServer and all of the applications that use IdentityServer.
Not all external identity providers support federated sign-out, but those that do will provide a mechanism to notify clients that the user has signed out.
This notification usually comes in the form of a request in an <iframe> from the external identity provider’s “logged out” page.
IdentityServer must then notify all of its clients (as discussed here), also typically in the form of a request in an <iframe> from within the external identity provider’s <iframe>.
What makes federated sign-out a special case (when compared to a normal sign-out) is that the federated sign-out request is not to the normal sign-out endpoint in IdentityServer. In fact, each external IdentityProvider will have a different endpoint into your IdentityServer host. This is due to that fact that each external identity provider might use a different protocol, and each middleware listens on different endpoints.
The net effect of all of these factors is that there is no “logged out” page being rendered as we would on the normal sign-out workflow, which means we are missing the sign-out notifications to IdentityServer’s clients. We must add code for each of these federated sign-out endpoints to render the necessary notifications to achieve federated sign-out.
Fortunately IdentityServer already contains this code.
When requests come into IdentityServer and invoke the handlers for external authentication providers, IdentityServer detects if these are federated signout requests and if they are it will automatically render the same <iframe> as described here for signout.
In short, federated signout is automatically supported.
Federation Gateway¶
A common architecture is the so-called federation gateway. In this approach IdentityServer acts as a gateway to one or more external identity providers.
This architecture has the following advantages
- your applications only need to know about the one token service (the gateway) and are shielded from all the details about connecting to the external provider(s). This also means that you can add or change those external providers without needing to update your applications.
- you control the gateway (as opposed to some external service provider) - this means you can make any changes to it and can protect your applications from changes those external providers might do to their own services.
- most external providers only support a fixed set of claims and claim types - having a gateway in the middle allows post-processing the response from the providers to transform/add/amend domain specific identity information.
- some providers don’t support access tokens (e.g. social providers) - since the gateway knows about your APIs, it can issue access tokens based on the external identities.
- some providers charge by the number of applications you connect to them. The gateway acts as a single application to the external provider. Internally you can connect as many applications as you want.
- some providers use proprietary protocols or made proprietary modifications to standard protocols - with a gateway there is only one place you need to deal with that.
- forcing every authentication (internal or external) through one single place gives you tremendous flexibility with regards to identity mapping, providing a stable identity to all your applications and dealing with new requirements
In other words - owning your federation gateway gives you a lot of control over your identity infrastructure. And since the identity of your users is one of your most important assets, we recommend taking control over the gateway.
Implementation¶
Our quick start UI utilizes some of the below features. Also check out the external authentication quickstart and the docs about external providers.
- You can add support for external identity providers by adding authentication handlers to your IdentityServer application.
- You can programmatically query those external providers by calling
IAuthenticationSchemeProvider. This allows to dynamically render your login page based on the registered external providers. - Our client configuration model allows restricting the available providers on a per client basis (use the
IdentityProviderRestrictionsproperty). - You can also use the
EnableLocalLoginproperty on the client to tell your UI whether the username/password input should be rendered. - Our quickstart UI funnels all external authentication calls through a single callback (see
ExternalLoginCallbackon theAccountControllerclass). This allows for a single point for post-processing.
Consent¶
During an authorization request, if IdentityServer requires user consent the browser will be redirected to the consent page.
Consent is used to allow an end user to grant a client access to resources (identity or API). This is typically only necessary for third-party clients, and can be enabled/disabled per-client on the client settings.
Consent Page¶
In order for the user to grant consent, a consent page must be provided by the hosting application. The quickstart UI has a basic implementation of a consent page.
A consent page normally renders the display name of the current user, the display name of the client requesting access, the logo of the client, a link for more information about the client, and the list of resources the client is requesting access to. It’s also common to allow the user to indicate that their consent should be “remembered” so they are not prompted again in the future for the same client.
Once the user has provided consent, the consent page must inform IdentityServer of the consent, and then the browser must be redirected back to the authorization endpoint.
Authorization Context¶
IdentityServer will pass a returnUrl parameter (configurable on the user interaction options) to the consent page which contains the parameters of the authorization request.
These parameters provide the context for the consent page, and can be read with help from the interaction service.
The GetAuthorizationContextAsync API will return an instance of AuthorizationRequest.
Additional details about the client or resources can be obtained using the IClientStore and IResourceStore interfaces.
Informing IdentityServer of the consent result¶
The GrantConsentAsync API on the interaction service allows the consent page to inform IdentityServer of the outcome of consent (which might also be to deny the client access).
IdentityServer will temporarily persist the outcome of the consent.
This persistence uses a cookie by default, as it only needs to last long enough to convey the outcome back to the authorization endpoint.
This temporary persistence is different than the persistence used for the “remember my consent” feature (and it is the authorization endpoint which persists the “remember my consent” for the user).
If you wish to use some other persistence between the consent page and the authorization redirect, then you can implement IMessageStore<ConsentResponse> and register the implementation in DI.
Returning the user to the authorization endpoint¶
Once the consent page has informed IdentityServer of the outcome, the user can be redirected back to the returnUrl.
Your consent page should protect against open redirects by verifying that the returnUrl is valid.
This can be done by calling IsValidReturnUrl on the interaction service.
Also, if GetAuthorizationContextAsync returns a non-null result, then you can also trust that the returnUrl is valid.
Protecting APIs¶
IdentityServer issues access tokens in the JWT (JSON Web Token) format by default.
Every relevant platform today has support for validating JWT tokens, a good list of JWT libraries can be found here. Popular libraries are e.g.:
- JWT bearer authentication handler for ASP.NET Core
- JWT bearer authentication middleware for Katana
- IdentityServer authentication middleware for Katana
- jsonwebtoken for nodejs
Protecting a ASP.NET Core-based API is only a matter of configuring the JWT bearer authentication handler in DI, and adding the authentication middleware to the pipeline:
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(options =>
{
// base-address of your identityserver
options.Authority = "https://demo.identityserver.io";
// name of the API resource
options.Audience = "api1";
});
}
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
app.UseAuthentication();
app.UseMvc();
}
}
The IdentityServer authentication handler¶
Our authentication handler serves the same purpose as the above handler (in fact it uses the Microsoft JWT library internally), but adds a couple of additional features:
- support for both JWTs and reference tokens
- extensible caching for reference tokens
- unified configuration model
- scope validation
For the simplest case, our handler configuration looks very similar to the above snippet:
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddAuthentication(IdentityServerAuthenticationDefaults.AuthenticationScheme)
.AddIdentityServerAuthentication(options =>
{
// base-address of your identityserver
options.Authority = "https://demo.identityserver.io";
// name of the API resource
options.ApiName = "api1";
});
}
public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
app.UseAuthentication();
app.UseMvc();
}
}
Supporting reference tokens¶
If the incoming token is not a JWT, our middleware will contact the introspection endpoint found in the discovery document to validate the token. Since the introspection endpoint requires authentication, you need to supply the configured API secret, e.g.:
.AddIdentityServerAuthentication(options =>
{
// base-address of your identityserver
options.Authority = "https://demo.identityserver.io";
// name of the API resource
options.ApiName = "api1";
options.ApiSecret = "secret";
})
Typically, you don’t want to do a roundtrip to the introspection endpoint for each incoming request. The middleware has a built-in cache that you can enable like this:
.AddIdentityServerAuthentication(options =>
{
// base-address of your identityserver
options.Authority = "https://demo.identityserver.io";
// name of the API resource
options.ApiName = "api1";
options.ApiSecret = "secret";
options.EnableCaching = true;
options.CacheDuration = TimeSpan.FromMinutes(10); // that's the default
})
The handler will use whatever IDistributedCache implementation is registered in the DI container (e.g. the standard MemoryDistributedCache).
Validating scopes¶
The ApiName property checks if the token has a matching audience (or short aud) claim.
In IdentityServer you can also sub-divide APIs into multiple scopes. If you need that granularity you can use the ASP.NET Core authorization policy system to check for scopes.
Creating a global policy:
services
.AddMvcCore(options =>
{
// require scope1 or scope2
var policy = ScopePolicy.Create("scope1", "scope2");
options.Filters.Add(new AuthorizeFilter(policy));
})
.AddJsonFormatters()
.AddAuthorization();
Composing a scope policy:
services.AddAuthorization(options =>
{
options.AddPolicy("myPolicy", builder =>
{
// require scope1
builder.RequireScope("scope1");
// and require scope2 or scope3
builder.RequireScope("scope2", "scope3");
});
});
Deployment¶
Your identity server is just a standard ASP.NET Core application including the IdentityServer middleware. Read the official Microsoft documentation on publishing and deployment first (and especially the section about load balancers and proxies).
Typical architecture¶
Typically you will design your IdentityServer deployment for high availability:
IdentityServer itself is stateless and does not require server affinity - but there is data that needs to be shared between the instances.
Configuration data¶
This typically includes:
- resources
- clients
- startup configuration, e.g. key material, external provider settings etc…
The way you store that data depends on your environment. In situations where configuration data rarely changes we recommend using the in-memory stores and code or configuration files.
In highly dynamic environments (e.g. Saas) we recommend using a database or configuration service to load configuration dynamically.
IdentityServer supports code configuration and configuration files (see here) out of the box. For databases we provide support for Entity Framework Core based databases.
You can also build your own configuration stores by implementing IResourceStore and IClientStore.
Key material¶
Another important piece of startup configuration is your key material, see here for more details on key material and cryptography.
Operational data¶
For certain operations, IdentityServer needs a persistence store to keep state, this includes:
- issuing authorization codes
- issuing reference and refresh tokens
- storing consent
You can either use a traditional database for storing operational data, or use a cache with persistence features like Redis. The EF Core implementation mentioned above has also support for operational data.
You can also implement support for your own custom storage mechanism by implementing IPersistedGrantStore - by default IdentityServer injects an in-memory version.
Logging¶
IdentityServer uses the standard logging facilities provided by ASP.NET Core. The Microsoft documentation has a good intro and a description of the built-in logging providers.
We are roughly following the Microsoft guidelines for usage of log levels:
TraceFor information that is valuable only to a developer troubleshooting an issue. These messages may contain sensitive application data like tokens and should not be enabled in a production environment.DebugFor following the internal flow and understanding why certain decisions are made. Has short-term usefulness during development and debugging.InformationFor tracking the general flow of the application. These logs typically have some long-term value.WarningFor abnormal or unexpected events in the application flow. These may include errors or other conditions that do not cause the application to stop, but which may need to be investigated.ErrorFor errors and exceptions that cannot be handled. Examples: failed validation of a protocol request.CriticalFor failures that require immediate attention. Examples: missing store implementation, invalid key material…
Setup for Serilog¶
We personally like Serilog a lot. Give it a try.
ASP.NET Core 2.0+¶
For the following configuration you need the Serilog.AspNetCore and Serilog.Sinks.Console packages:
public class Program
{
public static void Main(string[] args)
{
Console.Title = "IdentityServer4";
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Debug()
.MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
.MinimumLevel.Override("System", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.AspNetCore.Authentication", LogEventLevel.Information)
.Enrich.FromLogContext()
.WriteTo.Console(outputTemplate: "[{Timestamp:HH:mm:ss} {Level}] {SourceContext}{NewLine}{Message:lj}{NewLine}{Exception}{NewLine}", theme: AnsiConsoleTheme.Literate)
.CreateLogger();
BuildWebHost(args).Run();
}
public static IWebHost BuildWebHost(string[] args)
{
return WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.UseSerilog()
.Build();
}
}
.NET Core 1.0, 1.1¶
For the following configuration you need the Serilog.Extensions.Logging and Serilog.Sinks.Console packages:
public class Program
{
public static void Main(string[] args)
{
Console.Title = "IdentityServer4";
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Debug()
.MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
.MinimumLevel.Override("System", LogEventLevel.Warning)
.MinimumLevel.Override("Microsoft.AspNetCore.Authentication", LogEventLevel.Information)
.Enrich.FromLogContext()
.WriteTo.Console(outputTemplate: "[{Timestamp:HH:mm:ss} {Level}] {SourceContext}{NewLine}{Message:lj}{NewLine}{Exception}{NewLine}", theme: AnsiConsoleTheme.Literate)
.CreateLogger();
BuildWebHost(args).Run();
}
public static IWebHost BuildWebHost(string[] args)
{
return WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
.ConfigureLogging(builder =>
{
builder.ClearProviders();
builder.AddSerilog();
})
.Build();
}
}
Events¶
While logging is more low level “printf” style - events represent higher level information about certain operations in IdentityServer. Events are structured data and include event IDs, success/failure information, categories and details. This makes it easy to query and analyze them and extract useful information that can be used for further processing.
Events work great with event stores like ELK, Seq or Splunk.
Emitting events¶
Events are not turned on by default - but can be globally configured in the ConfigureServices method, e.g.:
services.AddIdentityServer(options =>
{
options.Events.RaiseSuccessEvents = true;
options.Events.RaiseFailureEvents = true;
options.Events.RaiseErrorEvents = true;
});
To emit an event use the IEventService from the DI container and call the RaiseAsync method, e.g.:
public async Task<IActionResult> Login(LoginInputModel model)
{
if (_users.ValidateCredentials(model.Username, model.Password))
{
// issue authentication cookie with subject ID and username
var user = _users.FindByUsername(model.Username);
await _events.RaiseAsync(new UserLoginSuccessEvent(user.Username, user.SubjectId, user.Username));
}
else
{
await _events.RaiseAsync(new UserLoginFailureEvent(model.Username, "invalid credentials"));
}
}
Custom sinks¶
Our default event sink will simply serialize the event class to JSON and forward it to the ASP.NET Core logging system.
If you want to connect to a custom event store, implement the IEventSink interface and register it with DI.
The following example uses Seq to emit events:
public class SeqEventSink : IEventSink
{
private readonly Logger _log;
public SeqEventSink()
{
_log = new LoggerConfiguration()
.WriteTo.Seq("http://localhost:5341")
.CreateLogger();
}
public Task PersistAsync(Event evt)
{
if (evt.EventType == EventTypes.Success ||
evt.EventType == EventTypes.Information)
{
_log.Information("{Name} ({Id}), Details: {@details}",
evt.Name,
evt.Id,
evt);
}
else
{
_log.Error("{Name} ({Id}), Details: {@details}",
evt.Name,
evt.Id,
evt);
}
return Task.CompletedTask;
}
}
Add the Serilog.Sinks.Seq package to your host to make the above code work.
Built-in events¶
The following events are defined in IdentityServer:
ApiAuthenticationFailureEvent&ApiAuthenticationSuccessEvent- Gets raised for successful/failed API authentication at the introspection endpoint.
ClientAuthenticationSuccessEvent&ClientAuthenticationFailureEvent- Gets raised for successful/failed client authentication at the token endpoint.
TokenIssuedSuccessEvent&TokenIssuedFailureEvent- Gets raised for successful/failed attempts to request identity tokens, access tokens, refresh tokens and authorization codes.
TokenIntrospectionSuccessEvent&TokenIntrospectionFailureEvent- Gets raised for successful token introspection requests.
TokenRevokedSuccessEvent- Gets raised for successful token revocation requests.
UserLoginSuccessEvent&UserLoginFailureEvent- Gets raised by the quickstart UI for successful/failed user logins.
UserLogoutSuccessEvent- Gets raised for successful logout requests.
ConsentGrantedEvent&ConsentDeniedEvent- Gets raised in the consent UI.
UnhandledExceptionEvent- Gets raised for unhandled exceptions.
DeviceAuthorizationFailureEvent&DeviceAuthorizationSuccessEvent- Gets raised for successful/failed device authorization requests.
Custom events¶
You can create your own events and emit them via our infrastructure.
You need to derive from our base Event class which injects contextual information like activity ID, timestamp, etc.
Your derived class can then add arbitrary data fields specific to the event context:
public class UserLoginFailureEvent : Event
{
public UserLoginFailureEvent(string username, string error)
: base(EventCategories.Authentication,
"User Login Failure",
EventTypes.Failure,
EventIds.UserLoginFailure,
error)
{
Username = username;
}
public string Username { get; set; }
}
Cryptography, Keys and HTTPS¶
IdentityServer relies on a couple of crypto mechanisms to do its job.
Token signing and validation¶
IdentityServer needs an asymmetric key pair to sign and validate JWTs. This keypair can be a certificate/private key combination or raw RSA keys. In any case it must support RSA with SHA256.
Loading of signing key and the corresponding validation part is done by implementations of ISigningCredentialStore and IValidationKeysStore.
If you want to customize the loading of the keys, you can implement those interfaces and register them with DI.
The DI builder extensions has a couple of convenience methods to set signing and validation keys - see here.
Signing key rollover¶
While you can only use one signing key at a time, you can publish more than one validation key to the discovery document. This is useful for key rollover.
A rollover typically works like this:
- you request/create new key material
- you publish the new validation key in addition to the current one. You can use the
AddValidationKeybuilder extension method for that. - all clients and APIs now have a chance to learn about the new key the next time they update their local copy of the discovery document
- after a certain amount of time (e.g. 24h) all clients and APIs should now accept both the old and the new key material
- keep the old key material around for as long as you like, maybe you have long-lived tokens that need validation
- retire the old key material when it is not used anymore
- all clients and APIs will “forget” the old key next time they update their local copy of the discovery document
This requires that clients and APIs use the discovery document, and also have a feature to periodically refresh their configuration.
Data protection¶
Cookie authentication in ASP.NET Core (or anti-forgery in MVC) use the ASP.NET Core data protection feature. Depending on your deployment scenario, this might require additional configuration. See the Microsoft docs for more information.
HTTPS¶
We don’t enforce the use of HTTPS, but for production it is mandatory for every interaction with IdentityServer.
Grant Types¶
The OpenID Connect and OAuth 2.0 specifications define so-called grant types (often also called flows - or protocol flows). Grant types specify how a client can interact with the token service.
You need to specify which grant types a client can use via the AllowedGrantTypes property on the Client configuration.
This allows locking down the protocol interactions that are allowed for a given client.
A client can be configured to use more than a single grant type (e.g. Authorization Code flow for user centric operations and client credentials for server to server communication).
The GrantTypes class can be used to pick from typical grant type combinations:
Client.AllowedGrantTypes = GrantTypes.CodeAndClientCredentials;
You can also specify the grant types list manually:
Client.AllowedGrantTypes =
{
GrantType.Code,
GrantType.ClientCredentials,
"my_custom_grant_type"
};
While IdentityServer supports all standard grant types, you really only need to know two of them for common application scenarios.
Machine to Machine Communication¶
This is the simplest type of communication. Tokens are always requested on behalf of a client, no interactive user is present.
In this scenario, you send a token request to the token endpoint using the client credentials grant type.
The client typically has to authenticate with the token endpoint using its client ID and secret.
See the Client Credentials Quick Start for a sample how to use it.
Interactive Clients¶
This is the most common type of client scenario: web applications, SPAs or native/mobile apps with interactive users.
Note
Feel free to skip to the summary, if you don’t care about all the technical details.
For this type of clients, the authorization code flow was designed. That flow consists of two physical operations:
- a front-channel step via the browser where all “interactive” things happen, e.g. login page, consent etc. This step results in an authorization code that represents the outcome of the front-channel operation.
- a back-channel step where the authorization code from step 1 gets exchanged with the requested tokens. Confidential clients need to authenticate at this point.
This flow has the following security properties:
- no data (besides the authorization code which is basically a random string) gets leaked over the browser channel
- authorization codes can only be used once
- the authorization code can only be turned into tokens when (for confidential clients - more on that later) the client secret is known
This sounds all very good - still there is one problem called code substitution attack. There are two modern mitigation techniques for this:
OpenID Connect Hybrid Flow
This uses a response type of code id_token to add an additional identity token to the response. This token is signed and protected against substitution.
In addition it contains the hash of the code via the c_hash claim. This allows checking that you indeed got the right code (experts call this a detached signature).
This solves the problem but has the following down-sides:
- the
id_tokengets transmitted over the front-channel and might leak additional (personal identifiable) data - all the mitigitation steps (e.g. crypto) need to be implemented by the client. This results in more complicated client library implementations.
RFC 7636 - Proof Key for Code Exchange (PKCE)
This essentially introduces a per-request secret for code flow (please read up on the details here). All the client has to implement for this, is creating a random string and hashing it using SHA256.
This also solves the substition problem, because the client can prove that it is the same client on front and back-channel, and has the following additional advantages:
- the client implementation is very simple compared to hybrid flow
- it also solves the problem of the absence of a static secret for public clients
- no additional front-channel response artifacts are needed
Summary
Interactive clients should use an authorization code-based flow. To protect against code substitution, either hybrid flow or PKCE should be used. If PKCE is available, this is the simpler solution to the problem.
PKCE is already the official recommendation for native applications and SPAs - and with the release of ASP.NET Core 3 also by default supported in the OpenID Connect handler as well.
This is how you would configure an interactive client:
var client = new Client
{
ClientId = "...",
// set client secret for confidential clients
ClientSecret = { ... },
// ...or turn off for public clients
RequireClientSecret = false,
AllowedGrantTypes = GrantTypes.Code,
RequirePkce = true
};
Interactive clients without browsers or with constrained input devices¶
This grant type is detailed RFC 8628.
This flow outsources user authentication and consent to an external device (e.g. a smart phone). It is typically used by devices that don’t have proper keyboards (e.g. TVs, gaming consoles…) and can request both identity and API resources.
Secrets¶
In certain situations, clients need to authenticate with identityserver, e.g.
- confidential applications (aka clients) requesting tokens at the token endpoint
- APIs validating reference tokens at the introspection endpoint
For that purpose you can assign a list of secrets to a client or an API resource.
Secret parsing and validation is an extensibility point in identityserver, out of the box it supports shared secrets as well as transmitting the shared secret via a basic authentication header or the POST body.
Extension Grants¶
OAuth 2.0 defines standard grant types for the token endpoint, such as password, authorization_code and refresh_token. Extension grants are a way to add support for non-standard token issuance scenarios like token translation, delegation, or custom credentials.
You can add support for additional grant types by implementing the IExtensionGrantValidator interface:
public interface IExtensionGrantValidator
{
/// <summary>
/// Handles the custom grant request.
/// </summary>
/// <param name="request">The validation context.</param>
Task ValidateAsync(ExtensionGrantValidationContext context);
/// <summary>
/// Returns the grant type this validator can deal with
/// </summary>
/// <value>
/// The type of the grant.
/// </value>
string GrantType { get; }
}
The ExtensionGrantValidationContext object gives you access to:
- the incoming token request - both the well-known validated values, as well as any custom values (via the
Rawcollection) - the result - either error or success
- custom response parameters
To register the extension grant, add it to DI:
builder.AddExtensionGrantValidator<MyExtensionsGrantValidator>();
Example: Simple delegation using an extension grant¶
Imagine the following scenario - a front end client calls a middle tier API using a token acquired via an interactive flow (e.g. hybrid flow). This middle tier API (API 1) now wants to call a back end API (API 2) on behalf of the interactive user:
In other words, the middle tier API (API 1) needs an access token containing the user’s identity, but with the scope of the back end API (API 2).
Note
You might have heard of the term poor man’s delegation where the access token from the front end is simply forwarded to the back end. This has some shortcomings, e.g. API 2 must now accept the API 1 scope which would allow the user to call API 2 directly. Also - you might want to add some delegation specific claims into the token, e.g. the fact that the call path is via API 1.
Implementing the extension grant
The front end would send the token to API 1, and now this token needs to be exchanged at IdentityServer with a new token for API 2.
On the wire the call to token service for the exchange could look like this:
POST /connect/token
grant_type=delegation&
scope=api2&
token=...&
client_id=api1.client
client_secret=secret
It’s the job of the extension grant validator to handle that request by validating the incoming token, and returning a result that represents the new token:
public class DelegationGrantValidator : IExtensionGrantValidator
{
private readonly ITokenValidator _validator;
public DelegationGrantValidator(ITokenValidator validator)
{
_validator = validator;
}
public string GrantType => "delegation";
public async Task ValidateAsync(ExtensionGrantValidationContext context)
{
var userToken = context.Request.Raw.Get("token");
if (string.IsNullOrEmpty(userToken))
{
context.Result = new GrantValidationResult(TokenRequestErrors.InvalidGrant);
return;
}
var result = await _validator.ValidateAccessTokenAsync(userToken);
if (result.IsError)
{
context.Result = new GrantValidationResult(TokenRequestErrors.InvalidGrant);
return;
}
// get user's identity
var sub = result.Claims.FirstOrDefault(c => c.Type == "sub").Value;
context.Result = new GrantValidationResult(sub, GrantType);
return;
}
}
Don’t forget to register the validator with DI.
Registering the delegation client
You need a client registration in IdentityServer that allows a client to use this new extension grant, e.g.:
var client = new client
{
ClientId = "api1.client",
ClientSecrets = new List<Secret>
{
new Secret("secret".Sha256())
},
AllowedGrantTypes = { "delegation" },
AllowedScopes = new List<string>
{
"api2"
}
}
Calling the token endpoint
In API 1 you can now construct the HTTP payload yourself, or use the IdentityModel helper library:
public async Task<TokenResponse> DelegateAsync(string userToken)
{
var payload = new
{
token = userToken
};
// create token client
var client = new TokenClient(disco.TokenEndpoint, "api1.client", "secret");
// send custom grant to token endpoint, return response
return await client.RequestCustomGrantAsync("delegation", "api2", payload);
}
The TokenResponse.AccessToken will now contain the delegation access token.
Resource Owner Password Validation¶
If you want to use the OAuth 2.0 resource owner password credential grant (aka password), you need to implement and register the IResourceOwnerPasswordValidator interface:
public interface IResourceOwnerPasswordValidator
{
/// <summary>
/// Validates the resource owner password credential
/// </summary>
/// <param name="context">The context.</param>
Task ValidateAsync(ResourceOwnerPasswordValidationContext context);
}
On the context you will find already parsed protocol parameters like UserName and Password, but also the raw request if you want to look at other input data.
Your job is then to implement the password validation and set the Result on the context accordingly. See the GrantValidationResult documentation.
Refresh Tokens¶
Since access tokens have finite lifetimes, refresh tokens allow requesting new access tokens without user interaction.
Refresh tokens are supported for the following flows: authorization code, hybrid and resource owner password credential flow.
The clients needs to be explicitly authorized to request refresh tokens by setting AllowOfflineAccess to true.
Additional client settings¶
AbsoluteRefreshTokenLifetime- Maximum lifetime of a refresh token in seconds. Defaults to 2592000 seconds / 30 days. Zero allows refresh tokens that, when used with
RefreshTokenExpiration = Slidingonly expire after the SlidingRefreshTokenLifetime is passed. SlidingRefreshTokenLifetime- Sliding lifetime of a refresh token in seconds. Defaults to 1296000 seconds / 15 days
RefreshTokenUsageReUsethe refresh token handle will stay the same when refreshing tokensOneTimethe refresh token handle will be updated when refreshing tokensRefreshTokenExpirationAbsolutethe refresh token will expire on a fixed point in time (specified by the AbsoluteRefreshTokenLifetime)Slidingwhen refreshing the token, the lifetime of the refresh token will be renewed (by the amount specified in SlidingRefreshTokenLifetime). The lifetime will not exceed AbsoluteRefreshTokenLifetime.UpdateAccessTokenClaimsOnRefresh- Gets or sets a value indicating whether the access token (and its claims) should be updated on a refresh token request.
Reference Tokens¶
Access tokens can come in two flavours - self-contained or reference.
A JWT token would be a self-contained access token - it’s a protected data structure with claims and an expiration. Once an API has learned about the key material, it can validate self-contained tokens without needing to communicate with the issuer. This makes JWTs hard to revoke. They will stay valid until they expire.
When using reference tokens - IdentityServer will store the contents of the token in a data store and will only issue a unique identifier for this token back to the client. The API receiving this reference must then open a back-channel communication to IdentityServer to validate the token.
You can switch the token type of a client using the following setting:
client.AccessTokenType = AccessTokenType.Reference;
IdentityServer provides an implementation of the OAuth 2.0 introspection specification which allows APIs to dereference the tokens. You can either use our dedicated introspection handler or use the identity server authentication handler which can validate both JWTs and reference tokens.
The introspection endpoint requires authentication - since the client of an introspection endpoint is an API, you configure the secret on the ApiResource:
var api = new ApiResource("api1")
{
ApiSecrets = { new Secret("secret".Sha256()) }
}
See here for more information on how to configure the IdentityServer authentication middleware for APIs.
Mutual TLS¶
Mutual TLS support in IdentityServer allows for two features:
- Client authentication to endpoints within IdentityServer using a X.509 client certificate
- Use of sender-constrained access tokens from a client to APIs using a X.509 client certificate certificate
Note
See this spec for more information
Client authentication¶
Clients can use a X.509 client certificate as an authentication mechanism to endpoints in IdentityServer.
Validating the X.509 client certificate in IdentityServer¶
It’s the hosting layer’s responsibility to do the actual validation of the client certificate, and then IdentityServer uses (and trusts) this result as part of the client authentication and validation at the application level. This means to use this feature within IdentityServer you must first configure your web server (IIS, Kestrel, etc.) to accept and validate client certificates.
Consult your web server documentation to learn how to do this.
Note
mkcert is a nice utility for creating certificates for development purposes.
Endpoints in IdentityServer for mutual TLS¶
Given that mutual TLS is performed at the TLS channel, it tends to be more convenient to configure distinct endpoints where mutual TLS is expected and/or required.
This allows the existing endpoints in IdentityServer to operate normally without mutual TLS.
In IdentityServer, the mutual TLS endpoints are expected to be located beneath the path ~/connect/mtls.
This means your web server can be configured to require mutual TLS for all requests at and below that path.
As such, IdentityServer’s discovery document reflects those paths:
Mutual TLS configuration in IdentityServer¶
IdentityServer requires additional configuration to utilize the result of the mutual TLS authentication.
First, there must be an authentication handler configured in the hosting application that will surface the result of the client certificate authentication in the web server. There will be one built into ASP.NET Core 3.0, but prior to that the idunno.Authentication.Certificate handler is recommended. For example:
services.AddAuthentication()
.AddCertificate("x509", options =>
{
options.RevocationMode = System.Security.Cryptography.X509Certificates.X509RevocationMode.NoCheck;
options.Events = new CertificateAuthenticationEvents
{
OnValidateCertificate = context =>
{
context.Principal = Principal.CreateFromCertificate(context.ClientCertificate, includeAllClaims:true);
context.Success();
return Task.CompletedTask;
}
};
});
Next, in the IdentityServer options, enable mutual TLS and configure the scheme of the authentication handler registered in the previous step.
For example:
var builder = services.AddIdentityServer(options =>
{
options.MutualTls.Enabled = true;
options.MutualTls.ClientCertificateAuthenticationScheme = "x509";
});
Next, on the IdentityServer builder add the services to DI which will allow for validating the client certificate by calling AddMutualTlsSecretValidators:
builder.AddMutualTlsSecretValidators();
Finally, for the client configuration add to the ClientSecrets collection a secret type of either SecretTypes.X509CertificateName if you wish to authenticate the client from the certificate distinguished name or SecretTypes.X509CertificateThumbprint if you wish to authenticate the client by certificate thumbprint.
For example:
new Client
{
ClientId = "mtls",
AllowedGrantTypes = GrantTypes.ClientCredentials,
AllowedScopes = { "api1" }
ClientSecrets = {
new Secret(@"CN=mtls.test, OU=ROO\ballen@roo, O=mkcert development certificate", "mtls.test")
{
Type = SecretTypes.X509CertificateName
},
// or:
//new Secret("bca0d040847f843c5ee0fa6eb494837470155868", "mtls.test")
//{
// Type = SecretTypes.X509CertificateThumbprint
//},
},
}
Using a client certificate to authenticate to IdentityServer¶
When writing a client to connect to IdentityServer, the HttpClientHandler class provides a convenient mechanism to use a client certificate by adding to the ClientCertificates collection.
The HttpClientHandler can then be used as the message handler in HttpClient.
And then HTTP calls (including using the various IdentityModel extension methods) with the HttpClient will perform client certificate authentication at the TLS channel.
For example:
static async Task<TokenResponse> RequestTokenAsync()
{
var handler = new HttpClientHandler();
var cert = X509.CurrentUser.My.Thumbprint.Find("bca0d040847f843c5ee0fa6eb494837470155868").Single();
handler.ClientCertificates.Add(cert);
var client = new HttpClient(handler);
var disco = await client.GetDiscoveryDocumentAsync(Constants.Authority);
if (disco.IsError) throw new Exception(disco.Error);
var response = await client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
{
Address = disco
.TryGetValue(OidcConstants.Discovery.MtlsEndpointAliases)
.Value<string>(OidcConstants.Discovery.TokenEndpoint)
.ToString(),
ClientId = "mtls",
Scope = "api1"
});
if (response.IsError) throw new Exception(response.Error);
return response;
}
Sender-constrained access tokens¶
Clients can use a X.509 client certificate as a mechanism for sender-constrained access tokens when authenticating to APIs. The use of these sender-constrained access tokens requires the client to use the same X.509 client certificate to authenticate to the API as the one used for IdentityServer.
Confirmation claim¶
When a client obtains an access token and has authenticated with mutual TLS, IdentityServer issues a confirmation claim (or cnf) in the access token.
This value is a hash of the thumbprint of the client certificate used to authenticate with IdentityServer.
This value can be seen in this screen shot of a decoded access token:
The API will then use this value to ensure the client certificate being used at the API matches the confirmation value in the access token.
Validating and accepting a client certificate in APIs¶
As mentioned above for client authentication in IdentityServer, in the API the web server is expected to perform the client certificate validation at the TLS layer.
Aditionally, the API hosting application will need a mechanism to accept the client certificate in order to obtain the thumbprint to perform the confirmation claim validation. Below is an example how an API in ASP.NET Core might be configured for both access tokens and client certificates:
services.AddAuthentication("token")
.AddIdentityServerAuthentication("token", options =>
{
options.Authority = Constants.Authority;
options.RequireHttpsMetadata = false;
options.ApiName = "api1";
options.ApiSecret = "secret";
})
.AddCertificate("x509", options =>
{
options.RevocationMode = System.Security.Cryptography.X509Certificates.X509RevocationMode.NoCheck;
options.Events = new CertificateAuthenticationEvents
{
OnValidateCertificate = context =>
{
context.Principal = Principal.CreateFromCertificate(context.ClientCertificate, includeAllClaims: true);
context.Success();
return Task.CompletedTask;
}
};
});
Finally, a mechanism is needed that runs after the authentication middleware to authenticate the client certificate and compare the thumbprint to the cnf from the access token.
Below is an example implemented in middleware:
app.UseAuthentication();
app.Use(async (ctx, next) =>
{
if (ctx.User.Identity.IsAuthenticated)
{
var cnfJson = ctx.User.FindFirst("cnf")?.Value;
if (!String.IsNullOrWhiteSpace(cnfJson))
{
var certResult = await ctx.AuthenticateAsync("x509");
if (!certResult.Succeeded)
{
await ctx.ChallengeAsync("x509");
return;
}
var cert = ctx.Connection.ClientCertificate;
if (cert == null)
{
await ctx.ChallengeAsync("x509");
return;
}
var thumbprint = cert.Thumbprint;
var cnf = JObject.Parse(cnfJson);
var sha256 = cnf.Value<string>("x5t#S256");
if (String.IsNullOrWhiteSpace(sha256) ||
!thumbprint.Equals(sha256, StringComparison.OrdinalIgnoreCase))
{
await ctx.ChallengeAsync("token");
return;
}
}
}
await next();
});
app.UseMvc();
Once the above middlware succeeds, then the caller has been authenticated with a sender-constrained access token.
Introspection and the confirmation claim¶
When the access token is a JWT, then the confirmation claim is contained in the token as a claim.
When using reference tokens, the claims that the access token represents must be obtained via introspection.
The introspection endpoint in IdentityServer will return a cnf claim for reference tokens obtained via mutual TLS.
Authorize Request Objects¶
Instead of providing all parameters for an authorize request as individual query string parameters, you can package them up in signed JWTs. You can either transmit them by value or by reference to the authorize endpoint - see the spec for more details.
IdentityServer requires the request JWTs to be signed. We support X509 certificates, symmetric and RSA keys. For symmetric and RSA you need to add a JWK secret to the corresponding client, e.g.:
private readonly string _symmetricJwk = @"{ 'kty': 'oct', 'use': 'sig', 'kid': '1', 'k': 'nYA-IFt8xTsdBHe9hunvizcp3Dt7f6qGqudq18kZHNtvqEGjJ9Ud-9x3kbQ-LYfLHS3xM2MpFQFg1JzT_0U_F8DI40oby4TvBDGszP664UgA8_5GjB7Flnrlsap1NlitvNpgQX3lpyTvC2zVuQ-UVsXbBDAaSBUSlnw7SE4LM8Ye2WYZrdCCXL8yAX9vIR7vf77yvNTEcBCI6y4JlvZaqMB4YKVSfygs8XqGGCHjLpE5bvI-A4ESbAUX26cVFvCeDg9pR6HK7BmwPMlO96krgtKZcXEJtUELYPys6-rbwAIdmxJxKxpgRpt0FRv_9fm6YPwG7QivYBX-vRwaodL1TA', 'alg': 'HS256'}";
var client = new Client
{
ClientId = "foo",
ClientSecrets =
{
new Secret
{
Type = IdentityServerConstants.SecretTypes.JsonWebKey,
Value = _symmetricJwk
}
}
}
Note
Microsoft.IdentityModel.Tokens.JsonWebKeyConverter has various helpers to convert keys to JWKs
Because of a bug in Microsoft’s JWT library, X509 certificates cannot be formatted as JWKs right now. You can use the base64 representation instead:
ClientSecrets =
{
new Secret
{
Type = IdentityServerConstants.SecretTypes.X509CertificateBase64,
Value = Convert.ToBase64String(cert.Export(X509ContentType.Cert))
}
}
Passing request JWTs by reference¶
If the request_uri parameter is used, IdentityServer will make an outgoing HTTP call to fetch the JWT from the specified URL.
You can customize the HTTP client used for this outgoing connection, e.g. to add caching or retry logic (e.g. via the Polly library):
builder.AddJwtRequestUriHttpClient(client =>
{
client.Timeout = TimeSpan.FromSeconds(30);
})
.AddTransientHttpErrorPolicy(policy => policy.WaitAndRetryAsync(new[]
{
TimeSpan.FromSeconds(1),
TimeSpan.FromSeconds(2),
TimeSpan.FromSeconds(3)
}));
Note
Request URI processing is disabled by default. Enable on the IdentityServer Options under Endpoints.
Accessing the request object data¶
You can access the validated data from the request object in two ways
- wherever you have access to the
ValidatedAuthorizeRequest, theRequestObjectValuesdictionary holds the values - in the UI code you can call
IIdentityServerInteractionService.GetAuthorizationContextAsync, the resultingAuthorizationRequestobject contains theRequestObjectValuesdictionary as well
Custom Token Request Validation and Issuance¶
You can run custom code as part of the token issuance pipeline at the token endpoint. This allows e.g. for
- adding additional validation logic
- changing certain parameters (e.g. token lifetime) dynamically
For this purpose, implement (and register) the ICustomTokenRequestValidator interface:
/// <summary>
/// Allows inserting custom validation logic into token requests
/// </summary>
public interface ICustomTokenRequestValidator
{
/// <summary>
/// Custom validation logic for a token request.
/// </summary>
/// <param name="context">The context.</param>
/// <returns>
/// The validation result
/// </returns>
Task ValidateAsync(CustomTokenRequestValidationContext context);
}
The context object gives you access to:
- adding custom response parameters
- return an error and error description
- modifying the request parameters, e.g. access token lifetime and type, client claims, and the confirmation method
You can register your implementation of the validator using the AddCustomTokenRequestValidator extension method on the configuration builder.
CORS¶
Many endpoints in IdentityServer will be accessed via Ajax calls from JavaScript-based clients. Given that IdentityServer will most likely be hosted on a different origin than these clients, this implies that Cross-Origin Resource Sharing (CORS) will need to be configured.
Client-based CORS Configuration¶
One approach to configuring CORS is to use the AllowedCorsOrigins collection on the client configuration.
Simply add the origin of the client to the collection and the default configuration in IdentityServer will consult these values to allow cross-origin calls from the origins.
Note
Be sure to use an origin (not a URL) when configuring CORS. For example: https://foo:123/ is a URL, whereas https://foo:123 is an origin.
This default CORS implementation will be in use if you are using either the “in-memory” or EF-based client configuration that we provide.
If you define your own IClientStore, then you will need to implement your own custom CORS policy service (see below).
Custom Cors Policy Service¶
IdentityServer allows the hosting application to implement the ICorsPolicyService to completely control the CORS policy.
The single method to implement is: Task<bool> IsOriginAllowedAsync(string origin).
Return true if the origin is allowed, false otherwise.
Once implemented, simply register the implementation in DI and IdentityServer will then use your custom implementation.
DefaultCorsPolicyService
If you simply wish to hard-code a set of allowed origins, then there is a pre-built ICorsPolicyService implementation you can use called DefaultCorsPolicyService.
This would be configured as a singleton in DI, and hard-coded with its AllowedOrigins collection, or setting the flag AllowAll to true to allow all origins.
For example, in ConfigureServices:
var cors = new DefaultCorsPolicyService(_loggerFactory.CreateLogger<DefaultCorsPolicyService>())
{
AllowedOrigins = { "https://foo", "https://bar" }
};
services.AddSingleton<ICorsPolicyService>(cors);
Note
Use AllowAll with caution.
Mixing IdentityServer’s CORS policy with ASP.NET Core’s CORS policies¶
IdentityServer uses the CORS middleware from ASP.NET Core to provide its CORS implementation. It is possible that your application that hosts IdentityServer might also require CORS for its own custom endpoints. In general, both should work together in the same application.
Your code should use the documented CORS features from ASP.NET Core without regard to IdentityServer.
This means you should define policies and register the middleware as normal.
If your application defines policies in ConfigureServices, then those should continue to work in the same places you are using them (either where you configure the CORS middleware or where you use the MVC EnableCors attributes in your controller code).
If instead you define an inline policy in the use of the CORS middleware (via the policy builder callback), then that too should continue to work normally.
The one scenario where there might be a conflict between your use of the ASP.NET Core CORS services and IdentityServer is if you decide to create a custom ICorsPolicyProvider.
Given the design of the ASP.NET Core’s CORS services and middleware, IdentityServer implements its own custom ICorsPolicyProvider and registers it in the DI system.
Fortunately, the IdentityServer implementation is designed to use the decorator pattern to wrap any existing ICorsPolicyProvider that is already registered in DI.
What this means is that you can also implement the ICorsPolicyProvider, but it simply needs to be registered prior to IdentityServer in DI (e.g. in ConfigureServices).
Discovery¶
The discovery document can be found at https://baseaddress/.well-known/openid-configuration. It contains information about the endpoints, key material and features of your IdentityServer.
By default all information is included in the discovery document, but by using configuration options, you can hide individual sections, e.g.:
services.AddIdentityServer(options =>
{
options.Discovery.ShowIdentityScopes = false;
options.Discovery.ShowApiScopes = false;
options.Discovery.ShowClaims = false;
options.Discovery.ShowExtensionGrantTypes = false;
});
Extending discovery¶
You can add custom entries to the discovery document, e.g:
services.AddIdentityServer(options =>
{
options.Discovery.CustomEntries.Add("my_setting", "foo");
options.Discovery.CustomEntries.Add("my_complex_setting",
new
{
foo = "foo",
bar = "bar"
});
});
When you add a custom value that starts with ~/ it will be expanded to an absolute path below the IdentityServer base address, e.g.:
options.Discovery.CustomEntries.Add("my_custom_endpoint", "~/custom");
If you want to take full control over the rendering of the discovery (and jwks) document, you can implement the IDiscoveryResponseGenerator
interface (or derive from our default implementation).
Adding more API Endpoints¶
It’s a common scenario to add additional API endpoints to the application hosting IdentityServer. These endpoints are typically protected by IdentityServer itself.
For simple scenarios, we give you some helpers. See the advanced section to understand more of the internal plumbing.
Note
You could achieve the same by using either our IdentityServerAuthentication handler or Microsoft’s JwtBearer handler. But this is not recommended since it requires more configuration and creates dependencies on external libraries that might lead to conflicts in future updates.
Start by registering your API as an ApiResource, e.g.:
public static IEnumerable<ApiResource> Apis = new List<ApiResource>
{
// local API
new ApiResource(IdentityServerConstants.LocalApi.ScopeName),
};
..and give your clients access to this API, e.g.:
new Client
{
// rest omitted
AllowedScopes = { IdentityServerConstants.LocalApi.ScopeName },
}
Note
The value of IdentityServerConstants.LocalApi.ScopeName is IdentityServerApi.
To enable token validation for local APIs, add the following to your IdentityServer startup:
services.AddLocalApiAuthentication();
To protect an API controller, decorate it with an Authorize attribute using the LocalApi.PolicyName policy:
[Route("localApi")]
[Authorize(LocalApi.PolicyName)]
public class LocalApiController : ControllerBase
{
public IActionResult Get()
{
// omitted
}
}
Authorized clients can then request a token for the IdentityServerApi scope and use it to call the API.
Discovery¶
You can also add your endpoints to the discovery document if you want, e.g like this:
services.AddIdentityServer(options =>
{
options.Discovery.CustomEntries.Add("local_api", "~/localapi");
})
Advanced¶
Under the covers, the AddLocalApiAuthentication helper does a couple of things:
- adds an authentication handler that validates incoming tokens using IdentityServer’s built-in token validation engine (the name of this handlier is
IdentityServerAccessTokenorIdentityServerConstants.LocalApi.AuthenticationScheme - configures the authentication handler to require a scope claim inside the access token of value
IdentityServerApi - sets up an authorization policy that checks for a scope claim of value
IdentityServerApi
This covers the most common scenarios. You can customize this behavior in the following ways:
- Add the authentication handler yourself by calling
services.AddAuthentication().AddLocalApi(...) - this way you can specify the required scope name yourself, or (by specifying no scope at all) accept any token from the current IdentityServer instance
- Add the authentication handler yourself by calling
Do your own scope validation/authorization in your controllers using custom policies or code, e.g.:
services.AddAuthorization(options => { options.AddPolicy(IdentityServerConstants.LocalApi.PolicyName, policy => { policy.AddAuthenticationSchemes(IdentityServerConstants.LocalApi.AuthenticationScheme); policy.RequireAuthenticatedUser(); // custom requirements }); });
Claims Transformation¶
You can provide a callback to transform the claims of the incoming token after validation. Either use the helper method, e.g.:
services.AddLocalApiAuthentication(principal =>
{
principal.Identities.First().AddClaim(new Claim("additional_claim", "additional_value"));
return Task.FromResult(principal);
});
…or implement the event on the options if you add the authentication handler manually.
Adding new Protocols¶
IdentityServer4 allows adding support for other protocols besides the built-in support for OpenID Connect and OAuth 2.0.
You can add those additional protocol endpoints either as middleware or using e.g. MVC controllers. In both cases you have access to the ASP.NET Core DI system which allows re-using our internal services like access to client definitions or key material.
A sample for adding WS-Federation support can be found here.
Typical authentication workflow¶
An authentication request typically works like this:
- authentication request arrives at protocol endpoint
- protocol endpoint does input validation
- redirection to login page with a return URL set back to protocol endpoint (if user is anonymous)
- access to current request details via the
IIdentityServerInteractionService - authentication of user (either locally or via external authentication middleware)
- signing in the user
- redirect back to protocol endpoint
- access to current request details via the
- creation of protocol response (token creation and redirect back to client)
Useful IdentityServer services¶
To achieve the above workflow, some interaction points with IdentityServer are needed.
Access to configuration and redirecting to the login page
You can get access to the IdentityServer configuration by injecting the IdentityServerOptions
class into your code. This, e.g. has the configured path to the login page:
var returnUrl = Url.Action("Index");
returnUrl = returnUrl.AddQueryString(Request.QueryString.Value);
var loginUrl = _options.UserInteraction.LoginUrl;
var url = loginUrl.AddQueryString(_options.UserInteraction.LoginReturnUrlParameter, returnUrl);
return Redirect(url);
Interaction between the login page and current protocol request
The IIdentityServerInteractionService supports turning a protocol return URL into a
parsed and validated context object:
var context = await _interaction.GetAuthorizationContextAsync(returnUrl);
By default the interaction service only understands OpenID Connect protocol messages.
To extend support, you can write your own IReturnUrlParser:
public interface IReturnUrlParser
{
bool IsValidReturnUrl(string returnUrl);
Task<AuthorizationRequest> ParseAsync(string returnUrl);
}
..and then register the parser in DI:
builder.Services.AddTransient<IReturnUrlParser, WsFederationReturnUrlParser>();
This allows the login page to get to information like the client configuration and other protocol parameters.
Access to configuration and key material for creating the protocol response
By injecting the IKeyMaterialService into your code, you get access to the configured
signing credential and validation keys:
var credential = await _keys.GetSigningCredentialsAsync();
var key = credential.Key as Microsoft.IdentityModel.Tokens.X509SecurityKey;
var descriptor = new SecurityTokenDescriptor
{
AppliesToAddress = result.Client.ClientId,
Lifetime = new Lifetime(DateTime.UtcNow, DateTime.UtcNow.AddSeconds(result.Client.IdentityTokenLifetime)),
ReplyToAddress = result.Client.RedirectUris.First(),
SigningCredentials = new X509SigningCredentials(key.Certificate, result.RelyingParty.SignatureAlgorithm, result.RelyingParty.DigestAlgorithm),
Subject = outgoingSubject,
TokenIssuerName = _contextAccessor.HttpContext.GetIdentityServerIssuerUri(),
TokenType = result.RelyingParty.TokenType
};
Tools¶
The IdentityServerTools class is a collection of useful internal tools that you might need when writing extensibility code
for IdentityServer. To use it, inject it into your code, e.g. a controller:
public MyController(IdentityServerTools tools)
{
_tools = tools;
}
The IssueJwtAsync method allows creating JWT tokens using the IdentityServer token creation engine. The IssueClientJwtAsync is an easier
version of that for creating tokens for server-to-server communication (e.g. when you have to call an IdentityServer protected API from your code):
public async Task<IActionResult> MyAction()
{
var token = await _tools.IssueClientJwtAsync(
clientId: "client_id",
lifetime: 3600,
audiences: new[] { "backend.api" });
// more code
}
Discovery Endpoint¶
The discovery endpoint can be used to retrieve metadata about your IdentityServer - it returns information like the issuer name, key material, supported scopes etc. See the spec for more details.
The discovery endpoint is available via /.well-known/openid-configuration relative to the base address, e.g.:
https://demo.identityserver.io/.well-known/openid-configuration
Note
You can use the IdentityModel client library to programmatically access the discovery endpoint from .NET code. For more information check the IdentityModel docs.
Authorize Endpoint¶
The authorize endpoint can be used to request tokens or authorization codes via the browser. This process typically involves authentication of the end-user and optionally consent.
Note
IdentityServer supports a subset of the OpenID Connect and OAuth 2.0 authorize request parameters. For a full list, see here.
client_id- identifier of the client (required).
request- instead of providing all parameters as individual query string parameters, you can provide a subset or all of them as a JWT
request_uri- URL of a pre-packaged JWT containing request parameters
scope- one or more registered scopes (required)
redirect_uri- must exactly match one of the allowed redirect URIs for that client (required)
response_typeid_tokenrequests an identity token (only identity scopes are allowed)tokenrequests an access token (only resource scopes are allowed)id_token tokenrequests an identity token and an access tokencoderequests an authorization codecode id_tokenrequests an authorization code and identity tokencode id_token tokenrequests an authorization code, identity token and access tokenresponse_modeform_postsends the token response as a form post instead of a fragment encoded redirect (optional)state- identityserver will echo back the state value on the token response, this is for round tripping state between client and provider, correlating request and response and CSRF/replay protection. (recommended)
nonceidentityserver will echo back the nonce value in the identity token, this is for replay protection)
Required for identity tokens via implicit grant.
promptnoneno UI will be shown during the request. If this is not possible (e.g. because the user has to sign in or consent) an error is returnedloginthe login UI will be shown, even if the user is already signed-in and has a valid sessioncode_challenge- sends the code challenge for PKCE
code_challenge_methodplainindicates that the challenge is using plain text (not recommended)S256indicates the challenge is hashed with SHA256login_hint- can be used to pre-fill the username field on the login page
ui_locales- gives a hint about the desired display language of the login UI
max_age- if the user’s logon session exceeds the max age (in seconds), the login UI will be shown
acr_valuesallows passing in additional authentication related information - identityserver special cases the following proprietary acr_values:
idp:name_of_idpbypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)tenant:name_of_tenantcan be used to pass a tenant name to the login UI
Example
GET /connect/authorize?
client_id=client1&
scope=openid email api1&
response_type=id_token token&
redirect_uri=https://myapp/callback&
state=abc&
nonce=xyz
(URL encoding removed, and line breaks added for readability)
Note
You can use the IdentityModel client library to programmatically create authorize requests .NET code. For more information check the IdentityModel docs.
Token Endpoint¶
The token endpoint can be used to programmatically request tokens.
It supports the password, authorization_code, client_credentials, refresh_token and urn:ietf:params:oauth:grant-type:device_code grant types.
Furthermore the token endpoint can be extended to support extension grant types.
Note
IdentityServer supports a subset of the OpenID Connect and OAuth 2.0 token request parameters. For a full list, see here.
client_id- client identifier (required)
client_secret- client secret either in the post body, or as a basic authentication header. Optional.
grant_typeauthorization_code,client_credentials,password,refresh_token,urn:ietf:params:oauth:grant-type:device_codeor customscope- one or more registered scopes. If not specified, a token for all explicitly allowed scopes will be issued.
redirect_uri- required for the
authorization_codegrant type code- the authorization code (required for
authorization_codegrant type) code_verifier- PKCE proof key
username- resource owner username (required for
passwordgrant type) password- resource owner password (required for
passwordgrant type) acr_valuesallows passing in additional authentication related information for the
passwordgrant type - identityserver special cases the following proprietary acr_values:idp:name_of_idpbypasses the login/home realm screen and forwards the user directly to the selected identity provider (if allowed per client configuration)tenant:name_of_tenantcan be used to pass a tenant name to the token endpointrefresh_token- the refresh token (required for
refresh_tokengrant type) device_code- the device code (required for
urn:ietf:params:oauth:grant-type:device_codegrant type)
Example¶
POST /connect/token
client_id=client1&
client_secret=secret&
grant_type=authorization_code&
code=hdh922&
redirect_uri=https://myapp.com/callback
(Form-encoding removed and line breaks added for readability)
Note
You can use the IdentityModel client library to programmatically access the token endpoint from .NET code. For more information check the IdentityModel docs.
UserInfo Endpoint¶
The UserInfo endpoint can be used to retrieve identity information about a user (see spec).
The caller needs to send a valid access token representing the user. Depending on the granted scopes, the UserInfo endpoint will return the mapped claims (at least the openid scope is required).
Example¶
GET /connect/userinfo
Authorization: Bearer <access_token>
HTTP/1.1 200 OK
Content-Type: application/json
{
"sub": "248289761001",
"name": "Bob Smith",
"given_name": "Bob",
"family_name": "Smith",
"role": [
"user",
"admin"
]
}
Note
You can use the IdentityModel client library to programmatically access the userinfo endpoint from .NET code. For more information check the IdentityModel docs.
Device Authorization Endpoint¶
The device authorization endpoint can be used to request device and user codes. This endpoint is used to start the device flow authorization process.
Note
The URL for the end session endpoint is available via the discovery endpoint.
client_id- client identifier (required)
client_secret- client secret either in the post body, or as a basic authentication header. Optional.
scope- one or more registered scopes. If not specified, a token for all explicitly allowed scopes will be issued.
Example¶
POST /connect/deviceauthorization
client_id=client1&
client_secret=secret&
scope=openid api1
(Form-encoding removed and line breaks added for readability)
Note
You can use the IdentityModel client library to programmatically access the device authorization endpoint from .NET code. For more information check the IdentityModel docs.
Introspection Endpoint¶
The introspection endpoint is an implementation of RFC 7662.
It can be used to validate reference tokens (or JWTs if the consumer does not have support for appropriate JWT or cryptographic libraries).
The introspection endpoint requires authentication - since the client of an introspection endpoint is an API, you configure the secret on the ApiResource.
Example¶
POST /connect/introspect
Authorization: Basic xxxyyy
token=<token>
A successful response will return a status code of 200 and either an active or inactive token:
{
"active": true,
"sub": "123"
}
Unknown or expired tokens will be marked as inactive:
{
"active": false,
}
An invalid request will return a 400, an unauthorized request 401.
Note
You can use the IdentityModel client library to programmatically access the introspection endpoint from .NET code. For more information check the IdentityModel docs.
Revocation Endpoint¶
This endpoint allows revoking access tokens (reference tokens only) and refresh token. It implements the token revocation specification (RFC 7009).
token- the token to revoke (required)
token_type_hint- either
access_tokenorrefresh_token(optional)
Example¶
POST /connect/revocation HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token
Note
You can use the IdentityModel client library to programmatically access the revocation endpoint from .NET code. For more information check the IdentityModel docs.
End Session Endpoint¶
The end session endpoint can be used to trigger single sign-out (see spec).
To use the end session endpoint a client application will redirect the user’s browser to the end session URL. All applications that the user has logged into via the browser during the user’s session can participate in the sign-out.
Note
The URL for the end session endpoint is available via the discovery endpoint.
Parameters¶
id_token_hint
When the user is redirected to the endpoint, they will be prompted if they really want to sign-out.
This prompt can be bypassed by a client sending the original id_token received from authentication.
This is passed as a query string parameter called id_token_hint.
post_logout_redirect_uri
If a valid id_token_hint is passed, then the client may also send a post_logout_redirect_uri parameter.
This can be used to allow the user to redirect back to the client after sign-out.
The value must match one of the client’s pre-configured PostLogoutRedirectUris (client docs).
state
If a valid post_logout_redirect_uri is passed, then the client may also send a state parameter.
This will be returned back to the client as a query string parameter after the user redirects back to the client.
This is typically used by clients to round-trip state across the redirect.
Example¶
GET /connect/endsession?id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IjdlOGFkZmMzMjU1OTEyNzI0ZDY4NWZmYmIwOThjNDEyIiwidHlwIjoiSldUIn0.eyJuYmYiOjE0OTE3NjUzMjEsImV4cCI6MTQ5MTc2NTYyMSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo1MDAwIiwiYXVkIjoianNfb2lkYyIsIm5vbmNlIjoiYTQwNGFjN2NjYWEwNGFmNzkzNmJjYTkyNTJkYTRhODUiLCJpYXQiOjE0OTE3NjUzMjEsInNpZCI6IjI2YTYzNWVmOTQ2ZjRiZGU3ZWUzMzQ2ZjFmMWY1NTZjIiwic3ViIjoiODg0MjExMTMiLCJhdXRoX3RpbWUiOjE0OTE3NjUzMTksImlkcCI6ImxvY2FsIiwiYW1yIjpbInB3ZCJdfQ.STzOWoeVYMtZdRAeRT95cMYEmClixWkmGwVH2Yyiks9BETotbSZiSfgE5kRh72kghN78N3-RgCTUmM2edB3bZx4H5ut3wWsBnZtQ2JLfhTwJAjaLE9Ykt68ovNJySbm8hjZhHzPWKh55jzshivQvTX0GdtlbcDoEA1oNONxHkpDIcr3pRoGi6YveEAFsGOeSQwzT76aId-rAALhFPkyKnVc-uB8IHtGNSyRWLFhwVqAdS3fRNO7iIs5hYRxeFSU7a5ZuUqZ6RRi-bcDhI-djKO5uAwiyhfpbpYcaY_TxXWoCmq8N8uAw9zqFsQUwcXymfOAi2UF3eFZt02hBu-shKA&post_logout_redirect_uri=http%3A%2F%2Flocalhost%3A7017%2Findex.html
Note
You can use the IdentityModel client library to programmatically create end_session requests .NET code. For more information check the IdentityModel docs.
Identity Resource¶
This class models an identity resource.
Enabled- Indicates if this resource is enabled and can be requested. Defaults to true.
Name- The unique name of the identity resource. This is the value a client will use for the scope parameter in the authorize request.
DisplayName- This value will be used e.g. on the consent screen.
Description- This value will be used e.g. on the consent screen.
Required- Specifies whether the user can de-select the scope on the consent screen (if the consent screen wants to implement such a feature). Defaults to false.
Emphasize- Specifies whether the consent screen will emphasize this scope (if the consent screen wants to implement such a feature). Use this setting for sensitive or important scopes. Defaults to false.
ShowInDiscoveryDocument- Specifies whether this scope is shown in the discovery document. Defaults to true.
UserClaims- List of associated user claim types that should be included in the identity token.
API Resource¶
This class model an API resource.
Enabled- Indicates if this resource is enabled and can be requested. Defaults to true.
Name- The unique name of the API. This value is used for authentication with introspection and will be added to the audience of the outgoing access token.
DisplayName- This value can be used e.g. on the consent screen.
Description- This value can be used e.g. on the consent screen.
ApiSecrets- The API secret is used for the introspection endpoint. The API can authenticate with introspection using the API name and secret.
UserClaims- List of associated user claim types that should be included in the access token.
Scopes- An API must have at least one scope. Each scope can have different settings.
Scopes¶
In the simple case an API has exactly one scope. But there are cases where you might want to sub-divide the functionality of an API, and give different clients access to different parts.
Name- The unique name of the scope. This is the value a client will use for the scope parameter in the authorize/token request.
DisplayName- This value can be used e.g. on the consent screen.
Description- This value can be used e.g. on the consent screen.
Required- Specifies whether the user can de-select the scope on the consent screen (if the consent screen wants to implement such a feature). Defaults to false.
Emphasize- Specifies whether the consent screen will emphasize this scope (if the consent screen wants to implement such a feature). Use this setting for sensitive or important scopes. Defaults to false.
ShowInDiscoveryDocument- Specifies whether this scope is shown in the discovery document. Defaults to true.
UserClaims- List of associated user claim types that should be included in the access token. The claims specified here will be added to the list of claims specified for the API.
Convenience Constructor Behavior¶
Just a note about the constructors provided for the ApiResource class.
For full control over the data in the ApiResource, use the default constructor with no parameters.
You would use this approach if you wanted to configure multiple scopes per API.
For example:
new ApiResource
{
Name = "api2",
Scopes =
{
new Scope()
{
Name = "api2.full_access",
DisplayName = "Full access to API 2"
},
new Scope
{
Name = "api2.read_only",
DisplayName = "Read only access to API 2"
}
}
}
For simpler scenarios where you only require one scope per API, then several convenience constructors which accept a name are provided.
For example:
new ApiResource("api1", "Some API 1")
Using the convenience constructor is equivalent to this:
new ApiResource
{
Name = "api1",
DisplayName = "Some API 1",
Scopes =
{
new Scope()
{
Name = "api1",
DisplayName = "Some API 1"
}
}
}
Defining API resources in appsettings.json¶
The AddInMemoryApiResource extensions method also supports adding clients from the ASP.NET Core configuration file. This allows you to define static clients directly from the appsettings.json file:
"IdentityServer": {
"IssuerUri": "urn:sso.company.com",
"ApiResources": [
{
"Name": "api1",
"DisplayName": "My API",
"Scopes": [
{
"Name": "api1",
"DisplayName": "My API"
}
]
}
]
}
Then pass the configuration section to the AddInMemoryApiResource method:
AddInMemoryApiResources(configuration.GetSection("IdentityServer:ApiResources"))
Client¶
The Client class models an OpenID Connect or OAuth 2.0 client -
e.g. a native application, a web application or a JS-based application.
Basics¶
Enabled- Specifies if client is enabled. Defaults to true.
ClientId- Unique ID of the client
ClientSecrets- List of client secrets - credentials to access the token endpoint.
RequireClientSecret- Specifies whether this client needs a secret to request tokens from the token endpoint (defaults to
true) AllowedGrantTypes- Specifies the grant types the client is allowed to use. Use the
GrantTypesclass for common combinations. RequirePkce- Specifies whether clients using an authorization code based grant type must send a proof key
AllowPlainTextPkce- Specifies whether clients using PKCE can use a plain text code challenge (not recommended - and default to
false) RedirectUris- Specifies the allowed URIs to return tokens or authorization codes to
AllowedScopes- By default a client has no access to any resources - specify the allowed resources by adding the corresponding scopes names
AllowOfflineAccess- Specifies whether this client can request refresh tokens (be requesting the
offline_accessscope) AllowAccessTokensViaBrowser- Specifies whether this client is allowed to receive access tokens via the browser. This is useful to harden flows that allow multiple response types (e.g. by disallowing a hybrid flow client that is supposed to use code id_token to add the token response type and thus leaking the token to the browser.
Properties- Dictionary to hold any custom client-specific values as needed.
Authentication/Logout¶
PostLogoutRedirectUris- Specifies allowed URIs to redirect to after logout. See the OIDC Connect Session Management spec for more details.
FrontChannelLogoutUri- Specifies logout URI at client for HTTP based front-channel logout. See the OIDC Front-Channel spec for more details.
FrontChannelLogoutSessionRequired- Specifies if the user’s session id should be sent to the FrontChannelLogoutUri. Defaults to true.
BackChannelLogoutUri- Specifies logout URI at client for HTTP based back-channel logout. See the OIDC Back-Channel spec for more details.
BackChannelLogoutSessionRequired- Specifies if the user’s session id should be sent in the request to the BackChannelLogoutUri. Defaults to true.
EnableLocalLogin- Specifies if this client can use local accounts, or external IdPs only. Defaults to true.
IdentityProviderRestrictions- Specifies which external IdPs can be used with this client (if list is empty all IdPs are allowed). Defaults to empty.
UserSsoLifetimeadded in 2.3- The maximum duration (in seconds) since the last time the user authenticated. Defaults to
null. You can adjust the lifetime of a session token to control when and how often a user is required to reenter credentials instead of being silently authenticated, when using a web application.
Token¶
IdentityTokenLifetime- Lifetime to identity token in seconds (defaults to 300 seconds / 5 minutes)
AccessTokenLifetime- Lifetime of access token in seconds (defaults to 3600 seconds / 1 hour)
AuthorizationCodeLifetime- Lifetime of authorization code in seconds (defaults to 300 seconds / 5 minutes)
AbsoluteRefreshTokenLifetime- Maximum lifetime of a refresh token in seconds. Defaults to 2592000 seconds / 30 days
SlidingRefreshTokenLifetime- Sliding lifetime of a refresh token in seconds. Defaults to 1296000 seconds / 15 days
RefreshTokenUsageReUsethe refresh token handle will stay the same when refreshing tokensOneTimethe refresh token handle will be updated when refreshing tokens. This is the default.RefreshTokenExpirationAbsolutethe refresh token will expire on a fixed point in time (specified by the AbsoluteRefreshTokenLifetime)Slidingwhen refreshing the token, the lifetime of the refresh token will be renewed (by the amount specified in SlidingRefreshTokenLifetime). The lifetime will not exceed AbsoluteRefreshTokenLifetime.UpdateAccessTokenClaimsOnRefresh- Gets or sets a value indicating whether the access token (and its claims) should be updated on a refresh token request.
AccessTokenType- Specifies whether the access token is a reference token or a self contained JWT token (defaults to Jwt).
IncludeJwtId- Specifies whether JWT access tokens should have an embedded unique ID (via the jti claim).
AllowedCorsOrigins- If specified, will be used by the default CORS policy service implementations (In-Memory and EF) to build a CORS policy for JavaScript clients.
Claims- Allows settings claims for the client (will be included in the access token).
AlwaysSendClientClaims- If set, the client claims will be sent for every flow. If not, only for client credentials flow (default is false)
AlwaysIncludeUserClaimsInIdToken- When requesting both an id token and access token, should the user claims always be added to the id token instead of requring the client to use the userinfo endpoint. Default is false.
ClientClaimsPrefix- If set, the prefix client claim types will be prefixed with. Defaults to client_. The intent is to make sure they don’t accidentally collide with user claims.
PairWiseSubjectSalt- Salt value used in pair-wise subjectId generation for users of this client.
Consent Screen¶
RequireConsent- Specifies whether a consent screen is required. Defaults to true.
AllowRememberConsent- Specifies whether user can choose to store consent decisions. Defaults to true.
ConsentLifetime- Lifetime of a user consent in seconds. Defaults to null (no expiration).
ClientName- Client display name (used for logging and consent screen)
ClientUri- URI to further information about client (used on consent screen)
LogoUri- URI to client logo (used on consent screen)
Device flow¶
UserCodeType- Specifies the type of user code to use for the client. Otherwise falls back to default.
DeviceCodeLifetime- Lifetime to device code in seconds (defaults to 300 seconds / 5 minutes)
GrantValidationResult¶
The GrantValidationResult class models the outcome of grant validation for extensions grants and resource owner password grants.
The most common usage is to either new it up using an identity (success case):
context.Result = new GrantValidationResult(
subject: "818727",
authenticationMethod: "custom",
claims: optionalClaims);
…or using an error and description (failure case):
context.Result = new GrantValidationResult(
TokenRequestErrors.InvalidGrant,
"invalid custom credential");
In both case you can pass additional custom values that will be included in the token response.
Profile Service¶
Often IdentityServer requires identity information about users when creating tokens or when handling requests to the userinfo or introspection endpoints. By default, IdentityServer only has the claims in the authentication cookie to draw upon for this identity data.
It is impractical to put all of the possible claims needed for users into the cookie, so IdentityServer defines an extensibility point for allowing claims to be dynamically loaded as needed for a user.
This extensibility point is the IProfileService and it is common for a developer to implement this interface to access a custom database or API that contains the identity data for users.
IProfileService APIs¶
GetProfileDataAsync- The API that is expected to load claims for a user. It is passed an instance of
ProfileDataRequestContext. IsActiveAsync- The API that is expected to indicate if a user is currently allowed to obtain tokens. It is passed an instance of
IsActiveContext.
ProfileDataRequestContext¶
Models the request for user claims and is the vehicle to return those claims. It contains these properties:
Subject- The
ClaimsPrincipalmodeling the user. Client- The
Clientfor which the claims are being requested. RequestedClaimTypes- The collection of claim types being requested.
Caller- An identifier for the context in which the claims are being requested (e.g. an identity token, an access token, or the user info endpoint). The constant
IdentityServerConstants.ProfileDataCallerscontains the different constant values. IssuedClaims- The list of
Claims that will be returned. This is expected to be populated by the customIProfileServiceimplementation. AddRequestedClaims- Extension method on the
ProfileDataRequestContextto populate theIssuedClaims, but first filters the claims based onRequestedClaimTypes.
Requested scopes and claims mapping¶
The scopes requested by the client control what user claims are returned in the tokens to the client.
The GetProfileDataAsync method is responsible for dynamically obtaining those claims based on the RequestedClaimTypes collection on the ProfileDataRequestContext.
The RequestedClaimTypes collection is populated based on the user claims defined on the resources that model the scopes.
If the scopes requested are an identity resources, then the claims in the RequestedClaimTypes will be populated based on the user claim types defined in the IdentityResource.
If the scopes requested are an API resources, then the claims in the RequestedClaimTypes will be populated based on the user claim types defined in the ApiResource and/or the Scope.
IsActiveContext¶
Models the request to determine is the user is currently allowed to obtain tokens. It contains these properties:
Subject- The
ClaimsPrincipalmodeling the user. Client- The
Clientfor which the claims are being requested. Caller- An identifier for the context in which the claims are being requested (e.g. an identity token, an access token, or the user info endpoint). The constant
IdentityServerConstants.ProfileDataCallerscontains the different constant values. IsActive- The flag indicating if the user is allowed to obtain tokens. This is expected to be assigned by the custom
IProfileServiceimplementation.
IdentityServer Interaction Service¶
The IIdentityServerInteractionService interface is intended to provide services to be used by the user interface to communicate with IdentityServer, mainly pertaining to user interaction.
It is available from the dependency injection system and would normally be injected as a constructor parameter into your MVC controllers for the user interface of IdentityServer.
IIdentityServerInteractionService APIs¶
GetAuthorizationContextAsync- Returns the
AuthorizationRequestbased on thereturnUrlpassed to the login or consent pages. IsValidReturnUrl- Indicates if the
returnUrlis a valid URL for redirect after login or consent. GetErrorContextAsync- Returns the
ErrorMessagebased on theerrorIdpassed to the error page. GetLogoutContextAsync- Returns the
LogoutRequestbased on thelogoutIdpassed to the logout page. CreateLogoutContextAsync- Used to create a
logoutIdif there is not one presently. This creates a cookie capturing all the current state needed for signout and thelogoutIdidentifies that cookie. This is typically used when there is no currentlogoutIdand the logout page must capture the current user’s state needed for sign-out prior to redirecting to an external identity provider for signout. The newly createdlogoutIdwould need to be round-tripped to the external identity provider at signout time, and then used on the signout callback page in the same way it would be on the normal logout page. GrantConsentAsync- Accepts a
ConsentResponseto inform IdentityServer of the user’s consent to a particularAuthorizationRequest. GetAllUserConsentsAsync- Returns a collection of
Consentfor the user. RevokeUserConsentAsync- Revokes all of a user’s consents and grants for a client.
RevokeTokensForCurrentSessionAsync- Revokes all of a user’s consents and grants for clients the user has signed into during their current session.
AuthorizationRequest¶
ClientId- The client identifier that initiated the request.
RedirectUri- The URI to redirect the user to after successful authorization.
DisplayMode- The display mode passed from the authorization request.
UiLocales- The UI locales passed from the authorization request.
IdP- The external identity provider requested.
This is used to bypass home realm discovery (HRD).
This is provided via the “idp:” prefix to the
acr_valuesparameter on the authorize request. Tenant- The tenant requested.
This is provided via the “tenant:” prefix to the
acr_valuesparameter on the authorize request. LoginHint- The expected username the user will use to login.
This is requested from the client via the
login_hintparameter on the authorize request. PromptMode- The prompt mode requested from the authorization request.
AcrValues- The acr values passed from the authorization request.
ScopesRequested- The scopes requested from the authorization request.
Parameters- The entire parameter collection passed to the authorization request.
ErrorMessage¶
DisplayMode- The display mode passed from the authorization request.
UiLocales- The UI locales passed from the authorization request.
Error- The error code.
RequestId- The per-request identifier. This can be used to display to the end user and can be used in diagnostics.
LogoutRequest¶
ClientId- The client identifier that initiated the request.
PostLogoutRedirectUri- The URL to redirect the user to after they have logged out.
SessionId- The user’s current session id.
SignOutIFrameUrl- The URL to render in an
<iframe>on the logged out page to enable single sign-out. Parameters- The entire parameter collection passed to the end session endpoint.
ShowSignoutPrompt- Indicates if the user should be prompted for signout based upon the parameters passed to the end session endpoint.
ConsentResponse¶
ScopesConsented- The collection of scopes the user consented to.
RememberConsent- Flag indicating if the user’s consent is to be persisted.
Consent¶
SubjectId- The subject id that granted the consent.
ClientId- The client identifier for the consent.
Scopes- The collection of scopes consented to.
CreationTime- The date and time when the consent was granted.
Expiration- The date and time when the consent will expire.
Device Flow Interaction Service¶
The IDeviceFlowInteractionService interface is intended to provide services to be used by the user interface to communicate with IdentityServer during device flow authorization.
It is available from the dependency injection system and would normally be injected as a constructor parameter into your MVC controllers for the user interface of IdentityServer.
IDeviceFlowInteractionService APIs¶
GetAuthorizationContextAsync- Returns the
DeviceFlowAuthorizationRequestbased on theuserCodepassed to the login or consent pages. DeviceFlowInteractionResult- Completes device authorization for the given
userCode.
DeviceFlowAuthorizationRequest¶
ClientId- The client identifier that initiated the request.
ScopesRequested- The scopes requested from the authorization request.
DeviceFlowInteractionResult¶
IsError- Specifies if the authorization request errored.
ErrorDescription- Error description upon failure.
IdentityServer Options¶
IssuerUri- Set the issuer name that will appear in the discovery document and the issued JWT tokens. It is recommended to not set this property, which infers the issuer name from the host name that is used by the clients.
LowerCaseIssuerUri- Set to
falseto preserve the original casing of the IssuerUri. Defaults totrue.
PublicOrigin- The origin of this server instance, e.g. https://myorigin.com. If not set, the origin name is inferred from the request.
AccessTokenJwtType- Specifies the value used for the JWT typ header for access tokens (defaults to
at+jwt).
EmitLegacyResourceAudienceClaim- Emits an
audclaim with the format issuer/resources. That’s needed for some older access token validation plumbing. Defaults to false.
Endpoints¶
Allows enabling/disabling individual endpoints, e.g. token, authorize, userinfo etc.
By default all endpoints are enabled, but you can lock down your server by disabling endpoint that you don’t need.
EnableJwtRequestUri- JWT request_uri processing is enabled on the authorize endpoint. Defaults to
false.
Discovery¶
Allows enabling/disabling various sections of the discovery document, e.g. endpoints, scopes, claims, grant types etc.
The CustomEntries dictionary allows adding custom elements to the discovery document.
Authentication¶
CookieAuthenticationScheme- Sets the cookie authenitcation scheme confgured by the host used for interactive users. If not set, the scheme will inferred from the host’s default authentication scheme. This setting is typically used when AddPolicyScheme is used in the host as the default scheme.
CookieLifetime- The authentication cookie lifetime (only effective if the IdentityServer-provided cookie handler is used).
CookieSlidingExpiration- Specified if the cookie should be sliding or not (only effective if the IdentityServer-provided cookie handler is used).
RequireAuthenticatedUserForSignOutMessage- Indicates if user must be authenticated to accept parameters to end session endpoint. Defaults to false.
CheckSessionCookieName- The name of the cookie used for the check session endpoint.
RequireCspFrameSrcForSignout- If set, will require frame-src CSP headers being emitting on the end session callback endpoint which renders iframes to clients for front-channel signout notification. Defaults to true.
Events¶
Allows configuring if and which events should be submitted to a registered event sink. See here for more information on events.
InputLengthRestrictions¶
Allows setting length restrictions on various protocol parameters like client id, scope, redirect URI etc.
UserInteraction¶
LoginUrl,LogoutUrl,ConsentUrl,ErrorUrl,DeviceVerificationUrl- Sets the URLs for the login, logout, consent, error and device verification pages.
LoginReturnUrlParameter- Sets the name of the return URL parameter passed to the login page. Defaults to returnUrl.
LogoutIdParameter- Sets the name of the logout message id parameter passed to the logout page. Defaults to logoutId.
ConsentReturnUrlParameter- Sets the name of the return URL parameter passed to the consent page. Defaults to returnUrl.
ErrorIdParameter- Sets the name of the error message id parameter passed to the error page. Defaults to errorId.
CustomRedirectReturnUrlParameter- Sets the name of the return URL parameter passed to a custom redirect from the authorization endpoint. Defaults to returnUrl.
DeviceVerificationUserCodeParameter- Sets the name of the user code parameter passed to the device verification page. Defaults to userCode.
CookieMessageThreshold- Certain interactions between IdentityServer and some UI pages require a cookie to pass state and context (any of the pages above that have a configurable “message id” parameter). Since browsers have limits on the number of cookies and their size, this setting is used to prevent too many cookies being created. The value sets the maximum number of message cookies of any type that will be created. The oldest message cookies will be purged once the limit has been reached. This effectively indicates how many tabs can be opened by a user when using IdentityServer.
Caching¶
These setting only apply if the respective caching has been enabled in the services configuration in startup.
ClientStoreExpiration- Cache duration of client configuration loaded from the client store.
ResourceStoreExpiration- Cache duration of identity and API resource configuration loaded from the resource store.
CORS¶
IdentityServer supports CORS for some of its endpoints. The underlying CORS implementation is provided from ASP.NET Core, and as such it is automatically registered in the dependency injection system.
CorsPolicyName- Name of the CORS policy that will be evaluated for CORS requests into IdentityServer (defaults to
"IdentityServer4"). The policy provider that handles this is implemented in terms of theICorsPolicyServiceregistered in the dependency injection system. If you wish to customize the set of CORS origins allowed to connect, then it is recommended that you provide a custom implementation ofICorsPolicyService.
CorsPaths- The endpoints within IdentityServer where CORS is supported. Defaults to the discovery, user info, token, and revocation endpoints.
PreflightCacheDuration- Nullable<TimeSpan> indicating the value to be used in the preflight Access-Control-Max-Age response header. Defaults to null indicating no caching header is set on the response.
CSP (Content Security Policy)¶
IdentityServer emits CSP headers for some responses, where appropriate.
Level- The level of CSP to use. CSP Level 2 is used by default, but if older browsers must be supported then this be changed to
CspLevel.Oneto accomodate them.
AddDeprecatedHeader- Indicates if the older
X-Content-Security-PolicyCSP header should also be emitted (in addition to the standards-based header value). Defaults to true.
Device Flow¶
DefaultUserCodeType- The user code type to use, unless set at the client level. Defaults to Numeric, a 9-digit code.
Interval- Defines the minimum allowed polling interval on the token endpoint. Defaults to 5.
Mutual TLS¶
Enabled- Specifies if MTLS support should be enabled. Defaults to
false.
ClientCertificateAuthenticationScheme- Specifies the name of the authentication handler for X.509 client certificates. Defaults to
"Certificate".
Entity Framework Support¶
An EntityFramework-based implementation is provided for the configuration and operational data extensibility points in IdentityServer. The use of EntityFramework allows any EF-supported database to be used with this library.
The repo for this library is located here and the NuGet package is here.
The features provided by this library are broken down into two main areas: configuration store and operational store support. These two different areas can be used independently or together, based upon the needs of the hosting application.
Configuration Store support for Clients, Resources, and CORS settings¶
If client, identity resource, API resource, or CORS data is desired to be loaded from a EF-supported database
(rather than use in-memory configuration), then the configuration store can be used.
This support provides implementations of the IClientStore, IResourceStore, and the ICorsPolicyService extensibility points.
These implementations use a DbContext-derived class called ConfigurationDbContext to model the tables in the database.
To use the configuration store support, use the AddConfigurationStore extension method after the call to AddIdentityServer:
public IServiceProvider ConfigureServices(IServiceCollection services)
{
const string connectionString = @"Data Source=(LocalDb)\MSSQLLocalDB;database=IdentityServer4.EntityFramework-2.0.0;trusted_connection=yes;";
var migrationsAssembly = typeof(Startup).GetTypeInfo().Assembly.GetName().Name;
services.AddIdentityServer()
// this adds the config data from DB (clients, resources, CORS)
.AddConfigurationStore(options =>
{
options.ConfigureDbContext = builder =>
builder.UseSqlServer(connectionString,
sql => sql.MigrationsAssembly(migrationsAssembly));
});
}
To configure the configuration store, use the ConfigurationStoreOptions options object passed to the configuration callback.
ConfigurationStoreOptions¶
This options class contains properties to control the configuration store and ConfigurationDbContext.
ConfigureDbContext- Delegate of type
Action<DbContextOptionsBuilder>used as a callback to configure the underlyingConfigurationDbContext. The delegate can configure theConfigurationDbContextin the same way if EF were being used directly withAddDbContext, which allows any EF-supported database to be used. DefaultSchemaAllows setting the default database schema name for all the tables in the
ConfigurationDbContextoptions.DefaultSchema = "myConfigurationSchema";
If you need to change the schema for the Migration History Table, you can chain another action to the UseSqlServer:
options.ConfigureDbContext = b =>
b.UseSqlServer(connectionString,
sql => sql.MigrationsAssembly(migrationsAssembly).MigrationsHistoryTable("MyConfigurationMigrationTable", "myConfigurationSchema"));
Operational Store support for authorization grants, consents, and tokens (refresh and reference)¶
If authorization grants, consents, and tokens (refresh and reference) are desired to be loaded from a EF-supported database
(rather than the default in-memory database), then the operational store can be used.
This support provides implementations of the IPersistedGrantStore extensibility point.
The implementation uses a DbContext-derived class called PersistedGrantDbContext to model the table in the database.
To use the operational store support, use the AddOperationalStore extension method after the call to AddIdentityServer:
public IServiceProvider ConfigureServices(IServiceCollection services)
{
const string connectionString = @"Data Source=(LocalDb)\MSSQLLocalDB;database=IdentityServer4.EntityFramework-2.0.0;trusted_connection=yes;";
var migrationsAssembly = typeof(Startup).GetTypeInfo().Assembly.GetName().Name;
services.AddIdentityServer()
// this adds the operational data from DB (codes, tokens, consents)
.AddOperationalStore(options =>
{
options.ConfigureDbContext = builder =>
builder.UseSqlServer(connectionString,
sql => sql.MigrationsAssembly(migrationsAssembly));
// this enables automatic token cleanup. this is optional.
options.EnableTokenCleanup = true;
options.TokenCleanupInterval = 3600; // interval in seconds (default is 3600)
});
}
To configure the operational store, use the OperationalStoreOptions options object passed to the configuration callback.
OperationalStoreOptions¶
This options class contains properties to control the operational store and PersistedGrantDbContext.
ConfigureDbContext- Delegate of type
Action<DbContextOptionsBuilder>used as a callback to configure the underlyingPersistedGrantDbContext. The delegate can configure thePersistedGrantDbContextin the same way if EF were being used directly withAddDbContext, which allows any EF-supported database to be used. DefaultSchema- Allows setting the default database schema name for all the tables in the
PersistedGrantDbContext. EnableTokenCleanup- Indicates whether stale entries will be automatically cleaned up from the database. The default is
false. TokenCleanupInterval- The token cleanup interval (in seconds). The default is 3600 (1 hour).
Database creation and schema changes across different versions of IdentityServer¶
It is very likely that across different versions of IdentityServer (and the EF support) that the database schema will change to accommodate new and changing features.
We do not provide any support for creating your database or migrating your data from one version to another. You are expected to manage the database creation, schema changes, and data migration in any way your organization sees fit.
Using EF migrations is one possible approach to this. If you do wish to use migrations, then see the EF quickstart for samples on how to get started, or consult the Microsoft documentation on EF migrations.
We also publish sample SQL scripts for the current version of the database schema.
ASP.NET Identity Support¶
An ASP.NET Identity-based implementation is provided for managing the identity database for users of IdentityServer. This implementation implements the extensibility points in IdentityServer needed to load identity data for your users to emit claims into tokens.
The repo for this support is located here and the NuGet package is here.
To use this library, configure ASP.NET Identity normally.
Then use the AddAspNetIdentity extension method after the call to AddIdentityServer:
public void ConfigureServices(IServiceCollection services)
{
services.AddIdentity<ApplicationUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();
services.AddIdentityServer()
.AddAspNetIdentity<ApplicationUser>();
}
AddAspNetIdentity requires as a generic parameter the class that models your user for ASP.NET Identity (and the same one passed to AddIdentity to configure ASP.NET Identity).
This configures IdentityServer to use the ASP.NET Identity implementations of IUserClaimsPrincipalFactory, IResourceOwnerPasswordValidator, and IProfileService.
It also configures some of ASP.NET Identity’s options for use with IdentityServer (such as claim types to use and authentication cookie settings).
Training¶
Here are some online, remote and classroom training options to learn more about ASP.NET Core identity & IdentityServer4.
Identity & Access Control for modern Applications (using ASP.NET Core 2 and IdentityServer4)¶
That’s our own three day flagship course (including extensive hands-on labs) that we deliver as part of conferences, on-sites and remote.
The agenda and dates for public training can be found here, contact us for private workshops.
PluralSight courses¶
There are some good courses on PluralSight around identity, ASP.NET Core and IdentityServer.
new
- Securing Angular Apps with OpenID and OAuth2
- ASP.NET Core Identity Management Playbook
- Getting Started with ASP.NET Core and OAuth
- Securing ASP.NET Core with OAuth2 and OpenID Connect
- Understanding ASP.NET Core Security (Centralized Authentication with a Token Service)
older
Blog posts¶
Team posts¶
2019¶
- Scope and claims design in IdentityServer
- Try Device Flow with IdentityServer4
- The State of the Implicit Flow in OAuth2
- An alternative way to secure SPAs (with ASP.NET Core, OpenID Connect, OAuth 2.0 and ProxyKit
- Automatic OAuth 2.0 Token Management in ASP.NET Core
- Encrypting Identity Tokens in IdentityServer4
2018¶
2017¶
- Platforms where you can run IdentityServer4
- Optimizing Tokens for size
- Identity vs Permissions
- Bootstraping OpenID Connect: Discovery
- Extending IdentityServer4 with WS-Federation Support
- Announcing IdentityServer4 RC1
- Getting Started with IdentityServer 4
- IdentityServer 4 SharePoint Integration using WS-Federation
What’s new posts¶
- New in IdentityServer4 v2: Simplified Configuration behind Load-balancers or Reverse-Proxies
- New in IdentityServer4: Clients without Secrets
- New in IdentityServer4: Default Scopes
- New in IdentityServer4: Support for Extension Grants
- New in IdentityServer4: Resource Owner Password Validation
- New in IdentityServer4: Resource-based Configuration
- New in IdentityServer4: Events
Community posts¶
- OAuth 2.0 - OpenID Connect & IdentityServer
- Running IdentityServer4 in a Docker Container
- Connecting Zendesk and IdentityServer 4 SAML 2.0 Identity Provider
- IdentityServer localization using ui_locales
- Self-issuing an IdentityServer4 token in an IdentityServer4 service
- IdentityServer4 on the ASP.NET Team Blog
- Angular2 OpenID Connect Implicit Flow with IdentityServer4
- Full Server Logout with IdentityServer4 and OpenID Connect Implicit Flow
- IdentityServer4, ASP.NET Identity, Web API and Angular in a single Project
- Secure your .NETCore web applications using IdentityServer 4
- ASP.NET Core IdentityServer4 Resource Owner Password Flow with custom UserRepository
- Secure ASP.NET Core MVC with Angular using IdentityServer4 OpenID Connect Hybrid Flow
- Adding an external Microsoft login to IdentityServer4
- Implementing Two-factor authentication with IdentityServer4 and Twilio
- Security Experiments with gRPC and ASP.NET Core 3.0
- ASP.NET Core OAuth Device Flow Client with IdentityServer4
- Securing a Vue.js app using OpenID Connect Code Flow with PKCE and IdentityServer4
- Using an OData Client with an ASP.NET Core API
- OpenID Connect back-channel logout using Azure Redis Cache and IdentityServer4
- Single Sign Out in IdentityServer4 with Back Channel Logout
Videos¶
2019¶
2018¶
2017¶
- 14/09 [Microsoft Learning] – Introduction to IdentityServer for ASP.NET Core - Brock Allen
- 14/06 [NDC Oslo] – Implementing Authorization for Web Applications and APIs
- 22/02 [NDC Mini Copenhagen] – IdentityServer4: New & Improved for ASP.NET Core - Dominick Baier
- 02/02 [DotNetRocks] – IdentityServer4 on DotNetRocks
- 16/01 [NDC London] – IdentityServer4: New and Improved for ASP.NET Core
- 16/01 [NDC London] – Building JavaScript and mobile/native Clients for Token-based Architectures