Skip to content

Commit f520570

Browse files
maartenbamaartenba
authored
Merge pull request #767 from DuendeSoftware/better-template-docs
Refine IdentityServer template documentation and examples
2 parents bd1a737 + 0a18351 commit f520570

File tree

1 file changed

+222
-20
lines changed

1 file changed

+222
-20
lines changed

‎src/content/docs/identityserver/overview/packaging.mdx

Lines changed: 222 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ redirect_from:
1111
- /identityserver/v7/overview/packaging/
1212
---
1313

14-
import { LinkCard, CardGrid } from "@astrojs/starlight/components";
14+
import {LinkCard, CardGrid} from "@astrojs/starlight/components";
1515

1616
## Product
1717

@@ -23,7 +23,7 @@ The licensed and supported libraries can be accessed via NuGet:
2323

2424
## Templates
2525

26-
Contains Duende templates for the `dotnet` CLI to help jump start your Duende-powered solutions.
26+
Contains Duende templates for the `dotnet` CLI to help jump-start your Duende-powered solutions.
2727

2828
:::note
2929
You may have a previous version of Duende templates (`Duende.IdentityServer.Templates`) installed on your machine.
@@ -37,26 +37,228 @@ dotnet new -i Duende.Templates
3737
```
3838

3939
<CardGrid>
40-
<LinkCard
41-
description="NuGet Package for IdentityServer Templates"
42-
href="https://www.nuget.org/packages/Duende.Templates"
43-
title="Templates"
44-
target="_blank"
45-
/>
46-
<LinkCard
47-
description="Source code for IdentityServer Templates"
48-
href="https://github.com/DuendeSoftware/IdentityServer.Templates"
49-
title="Source Code"
50-
/>
40+
<LinkCard
41+
description="NuGet Package for IdentityServer Templates"
42+
href="https://www.nuget.org/packages/Duende.Templates"
43+
title="Templates"
44+
target="_blank"
45+
/>
46+
<LinkCard
47+
description="Source code for IdentityServer Templates"
48+
href="https://github.com/DuendeSoftware/IdentityServer.Templates"
49+
title="Source Code"
50+
/>
5151
</CardGrid>
5252

53-
## UI
53+
Running the command `dotnet new list duende` should give you a list of the following templates
5454

55-
Duende IdentityServer does not contain any UI, because this is always custom to the project.
56-
We still provide you with
57-
the [IdentityServer Quickstart UI](https://github.com/DuendeSoftware/products/tree/main/identity-server/templates/src/UI)
58-
as a starting point for your modifications.
55+
```bash
56+
Template Name Short Name Language Tags
57+
---------------------------------------------------------- -------------------- -------- -------------------------
58+
Duende BFF Host using a Remote API duende-bff-remoteapi [C#] Web/Duende/BFF
59+
Duende BFF using a Local API duende-bff-localapi [C#] Web/Duende/BFF
60+
Duende BFF with Blazor autorender duende-bff-blazor [C#] Web/Duende/BFF
61+
Duende IdentityServer Empty duende-is-empty [C#] Web/Duende/IdentityServer
62+
Duende IdentityServer Quickstart UI (UI assets only) duende-is-ui [C#] Web/IdentityServer
63+
Duende IdentityServer with ASP.NET Core Identity duende-is-aspid [C#] Web/Duende/IdentityServer
64+
Duende IdentityServer with Entity Framework Stores duende-is-ef [C#] Web/Duende/IdentityServer
65+
Duende IdentityServer with In-Memory Stores and Test Users duende-is-inmem [C#] Web/Duende/IdentityServer
66+
Duende IdentityServer duende-is [C#] Web/Duende/IdentityServer
67+
```
68+
69+
## Template Descriptions
70+
71+
In this section, we'll discuss what each IdentityServer template offers and why you would choose to start with it. While there are similarities across templates, there are nuances that can make for better starting points depending on your particular use case.
72+
73+
We'll start with the simplest templates and then move to the most feature-rich ones. Many of these templates build on each other's work, so moving from one to another is straightforward.
74+
75+
:::note
76+
All templates currently target .NET 8.0, but you can alter the target framework after creating the project to target higher framework versions.
77+
:::
78+
79+
All templates are provided as a starting point for your customization. Using the templates, you assume development responsibility for the choices, alterations, and inevitable deployment of your IdentityServer instance.
80+
81+
### Duende IdentityServer Empty
82+
83+
You want to run the following command to start using the **Duende IdentityServer Empty** template.
84+
85+
```bash
86+
dotnet new duende-is-empty
87+
```
88+
89+
Once created, this template has three essential files: `Config`, `HostingExtensions`, and `Program`.
90+
91+
You can modify the `Config` file to add clients, scopes, and claims, as all configurations are from in-memory objects.
92+
93+
```csharp
94+
public static class Config
95+
{
96+
public static IEnumerable<IdentityResource> IdentityResources =>
97+
new IdentityResource[]
98+
{
99+
new IdentityResources.OpenId()
100+
};
101+
102+
public static IEnumerable<ApiScope> ApiScopes =>
103+
new ApiScope[]
104+
{ };
105+
106+
public static IEnumerable<Client> Clients =>
107+
new Client[]
108+
{ };
109+
}
110+
```
111+
112+
This template doesn't include user interface elements, so it doesn't support OpenID Connect unless you add those UI elements. You can do so by running the UI-only template of `duende-is-ui`.
113+
114+
```bash
115+
dotnet new duende-is-ui --project <name of web app>
116+
```
117+
118+
The executed command will add Razor Pages to your web project. You will need to add Razor Pages to your `HostingExtensions` file.
119+
120+
```csharp
121+
using Serilog;
122+
123+
internal static class HostingExtensions
124+
{
125+
public static WebApplication ConfigureServices(this WebApplicationBuilder builder)
126+
{
127+
builder.Services.AddRazorPages();
128+
129+
builder.Services.AddIdentityServer()
130+
.AddInMemoryIdentityResources(Config.IdentityResources)
131+
.AddInMemoryApiScopes(Config.ApiScopes)
132+
.AddInMemoryClients(Config.Clients)
133+
.AddLicenseSummary();
134+
135+
return builder.Build();
136+
}
137+
138+
public static WebApplication ConfigurePipeline(this WebApplication app)
139+
{
140+
app.UseSerilogRequestLogging();
141+
142+
if (app.Environment.IsDevelopment())
143+
{
144+
app.UseDeveloperExceptionPage();
145+
}
146+
147+
app.UseStaticFiles();
148+
app.UseRouting();
149+
150+
app.UseIdentityServer();
151+
app.UseAuthorization();
152+
app.MapRazorPages().RequireAuthorization();
153+
154+
return app;
155+
}
156+
}
157+
```
158+
159+
### Duende IdentityServer with In-Memory Stores and Test Users
160+
161+
The `duende-is-inmem` template is similar to the `duende-is-empty` and `duende-is-ui` templates combined into a single project template.
162+
163+
```bash
164+
dotnet new duende-is-inmem
165+
```
166+
167+
This template differs from others in that we have defined some starting clients, scopes, and claims for common development scenarios and a speedier development experience.
168+
169+
```csharp
170+
// Config.cs
171+
public static class Config
172+
{
173+
public static IEnumerable<IdentityResource> IdentityResources =>
174+
new IdentityResource[]
175+
{
176+
new IdentityResources.OpenId(),
177+
new IdentityResources.Profile(),
178+
};
179+
180+
public static IEnumerable<ApiScope> ApiScopes =>
181+
new ApiScope[]
182+
{
183+
new ApiScope("scope1"),
184+
new ApiScope("scope2"),
185+
};
186+
187+
public static IEnumerable<Client> Clients =>
188+
new Client[]
189+
{
190+
// m2m client credentials flow client
191+
new Client
192+
{
193+
ClientId = "m2m.client",
194+
ClientName = "Client Credentials Client",
195+
196+
AllowedGrantTypes = GrantTypes.ClientCredentials,
197+
ClientSecrets = { new Secret("511536EF-F270-4058-80CA-1C89C192F69A".Sha256()) },
198+
199+
AllowedScopes = { "scope1" }
200+
},
201+
202+
// interactive client using code flow + pkce
203+
new Client
204+
{
205+
ClientId = "interactive",
206+
ClientSecrets = { new Secret("49C1A7E1-0C79-4A89-A3D6-A37998FB86B0".Sha256()) },
207+
208+
AllowedGrantTypes = GrantTypes.Code,
209+
210+
RedirectUris = { "https://localhost:44300/signin-oidc" },
211+
FrontChannelLogoutUri = "https://localhost:44300/signout-oidc",
212+
PostLogoutRedirectUris = { "https://localhost:44300/signout-callback-oidc" },
213+
214+
AllowOfflineAccess = true,
215+
AllowedScopes = { "openid", "profile", "scope2" }
216+
},
217+
};
218+
}
219+
```
220+
221+
This template is a great starting point for proof of concepts and a learning tool for developers experiencing OAuth 2.0 and OpenID Connect in the .NET space for the first time.
222+
223+
### Duende IdentityServer with Entity Framework Stores
224+
225+
For developers looking to quickly go to a production-like environment, starting with the `duende-is-ef` template is a great starting point.
226+
227+
```bash
228+
dotnet new duende-is-ef
229+
```
230+
231+
This template stores all operational and configuration data of the IdentityServer instance in your chosen data storage, utilizing EF Core's ability to target multiple database engines.
232+
233+
The template targets SQLite by default, but we have included scripts to easily swap out and regenerate migrations for your database.
234+
235+
[Read more about the Entity Framework Core setup here.](/identityserver/data/ef)
236+
237+
### Duende IdentityServer Quick Start
238+
239+
The quick start template is our most feature-rich offering and a great starting point for developers who want a simple yet effective UI/UX experience.
240+
241+
```bash
242+
dotnet new duende-is
243+
```
244+
245+
The template is built on the Entity Framework Core template but provides an administrative UI for managing clients, scopes, and claims against a database storage engine. It also has a diagnostics dashboard showing system information, including the licensing tier and features currently used in your IdentityServer deployment.
246+
247+
#### Third-party Dependencies
248+
249+
This template includes several third-party dependencies:
250+
251+
- [Serilog](https://serilog.net/)
252+
- [Bootstrap 5](https://getbootstrap.com)
253+
- [Bootstrap 5 tags](https://github.com/lekoala/bootstrap5-tags)
254+
- [JQuery](https://jquery.org)
255+
- [Entity Framework Core](https://learn.microsoft.com/en-us/ef/core/)
256+
257+
### Duende IdentityServer with ASP.NET Core Identity
258+
259+
The **Duende IdentityServer with ASP.NET Core Identity** template integrates with ASP.NET Identity to
260+
provide you with an instance of Duende IdentityServer that has a user store powered by the Microsoft
261+
library.
59262

60-
## Source Code
263+
[Please read our ASP.NET Identity documentation](/identityserver/aspnet-identity/), to learn more about this integration.
61264

62-
You can find the Duende IdentityServer source code on [GitHub](https://github.com/duendesoftware/IdentityServer).

0 commit comments

Comments
 (0)