Identityserver4 Documentation Release 1.0.0
Total Page:16
File Type:pdf, Size:1020Kb
IdentityServer4 Documentation Release 1.0.0 Brock Allen, Dominick Baier Jul 27, 2021 Introduction 1 The Big Picture 3 1.1 Authentication..............................................4 1.2 API Access................................................5 1.3 OpenID Connect and OAuth 2.0 – better together............................5 1.4 How IdentityServer4 can help......................................5 2 Terminology 7 2.1 IdentityServer..............................................7 2.2 User....................................................8 2.3 Client...................................................8 2.4 Resources.................................................8 2.5 Identity Token..............................................8 2.6 Access Token...............................................8 3 Supported Specifications 9 3.1 OpenID Connect.............................................9 3.2 OAuth 2.0................................................9 4 Packaging and Builds 11 4.1 IdentityServer4 main repo........................................ 11 4.2 Quickstart UI............................................... 11 4.3 Access token validation handler..................................... 11 4.4 Templates................................................. 12 4.5 Dev builds................................................ 12 5 Support and Consulting Options 13 5.1 Free support............................................... 13 5.2 Commercial support........................................... 13 6 Demo Server 15 7 Contributing 17 7.1 How to contribute?............................................ 17 7.2 General feedback and discussions?................................... 17 7.3 Bugs and feature requests?........................................ 17 7.4 Contributing code and content...................................... 17 7.5 Contribution projects........................................... 18 i 8 Overview 19 8.1 Preparation................................................ 19 9 Protecting an API using Client Credentials 21 9.1 Source Code............................................... 21 9.2 Preparation................................................ 21 9.3 Setting up the ASP.NET Core application................................ 21 9.4 Defining an API Scope.......................................... 22 9.5 Defining the client............................................ 23 9.6 Configuring IdentityServer........................................ 23 9.7 Adding an API.............................................. 24 9.7.1 The controller.......................................... 25 9.7.2 Adding a Nuget Dependency.................................. 25 9.7.3 Configuration.......................................... 25 9.8 Creating the client............................................ 26 9.9 Calling the API.............................................. 28 9.10 Authorization at the API......................................... 29 9.11 Further experiments........................................... 30 10 Interactive Applications with ASP.NET Core 31 10.1 Adding the UI.............................................. 31 10.2 Creating an MVC client......................................... 32 10.3 Adding support for OpenID Connect Identity Scopes.......................... 34 10.4 Adding Test Users............................................ 34 10.5 Adding the MVC Client to the IdentityServer Configuration...................... 34 10.6 Testing the client............................................. 35 10.7 Adding sign-out............................................. 37 10.8 Getting claims from the UserInfo endpoint............................... 38 10.9 Further Experiments........................................... 39 10.10 Adding Support for External Authentication.............................. 40 10.11 Adding Google support......................................... 40 10.12 Further experiments........................................... 41 11 ASP.NET Core and API access 43 11.1 Modifying the client configuration.................................... 43 11.2 Modifying the MVC client........................................ 44 11.3 Using the access token.......................................... 44 11.4 Managing the access token........................................ 45 12 Adding a JavaScript client 47 12.1 New Project for the JavaScript client.................................. 47 12.2 Modify hosting.............................................. 47 12.3 Add the static file middleware...................................... 48 12.4 Reference oidc-client........................................... 48 12.5 Add your HTML and JavaScript files.................................. 48 12.6 Add a client registration to IdentityServer for the JavaScript client................... 51 12.7 Allowing Ajax calls to the Web API with CORS............................ 51 12.8 Run the JavaScript application...................................... 52 13 Using EntityFramework Core for configuration and operational data 57 13.1 IdentityServer4.EntityFramework.................................... 57 13.2 Using SqlServer............................................. 58 13.3 Database Schema Changes and Using EF Migrations.......................... 58 13.4 Configuring the Stores.......................................... 58 13.5 Adding Migrations............................................ 59 ii 13.6 Initializing the Database......................................... 59 13.7 Run the client applications........................................ 61 14 Using ASP.NET Core Identity 63 14.1 New Project for ASP.NET Core Identity................................. 63 14.2 Inspect the new project.......................................... 64 14.2.1 IdentityServerAspNetIdentity.csproj.............................. 64 14.2.2 Startup.cs............................................ 64 14.2.3 Config.cs............................................ 64 14.2.4 Program.cs and SeedData.cs.................................. 65 14.2.5 AccountController....................................... 65 14.3 Logging in with the MVC client..................................... 66 14.4 What’s Missing?............................................. 69 15 Startup 71 15.1 Configuring services........................................... 71 15.2 Key material............................................... 71 15.3 In-Memory configuration stores..................................... 72 15.4 Test stores................................................ 72 15.5 Additional services............................................ 72 15.6 Caching.................................................. 73 15.7 Configuring the pipeline......................................... 73 16 Defining Resources 75 16.1 Identity Resources............................................ 75 16.2 APIs................................................... 76 16.2.1 Scopes.............................................. 77 16.2.2 Authorization based on Scopes................................. 77 16.2.3 Parameterized Scopes...................................... 78 16.2.4 API Resources......................................... 79 16.2.5 Migration steps to v4...................................... 81 17 Defining Clients 83 17.1 Defining a client for server to server communication.......................... 83 17.2 Defining an interactive application for use authentication and delegated API access.......... 84 17.3 Defining clients in appsettings.json................................... 84 18 Sign-in 87 18.1 Cookie authentication.......................................... 87 18.2 Overriding cookie handler configuration................................. 87 18.3 Login User Interface and Identity Management System......................... 88 18.4 Login Workflow............................................. 88 18.5 Login Context.............................................. 89 18.6 Issuing a cookie and Claims....................................... 89 19 Sign-in with External Identity Providers 91 19.1 Adding authentication handlers for external providers......................... 91 19.2 The role of cookies............................................ 91 19.3 Triggering the authentication handler.................................. 92 19.4 Handling the callback and signing in the user.............................. 93 19.5 State, URL length, and ISecureDataFormat............................... 94 20 Windows Authentication 97 20.1 On Windows using IIS hosting...................................... 97 iii 21 Sign-out 101 21.1 Removing the authentication cookie................................... 101 21.2 Notifying clients that the user has signed-out.............................. 101 21.3 Sign-out initiated by a client application................................. 102 22 Sign-out of External Identity Providers 103 23 Federated Sign-out 105 24 Federation Gateway 107 24.1 Implementation.............................................. 108 25 Consent 109 25.1 Consent Page............................................... 109 25.2 Authorization Context.......................................... 109 25.3 Informing IdentityServer of the consent result.............................. 110 25.4 Returning the user to the authorization endpoint............................ 110 26 Protecting APIs 111 26.1 Validating reference tokens....................................... 112 26.2 Supporting both JWTs and reference tokens............................... 112 27 Deployment 113 27.1 Typical architecture........................................... 113 27.2 Configuration data...........................................