You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
***Authentication flows**: The server handles the authentication flows. There are specific endpoints for login / logout. While the browser is involved with these authentication flows, because the user is redirected to and from the identity provider, the actual browserbased application will never see the authentication tokens. These are exchanged for a code on the server only.
33
-
***Cookies**: After successful authentication, a cookie is added. This cookie protects all subsequent calls to the apis. When using this type of authentication, **CSRF protection** is very important.
34
-
***Access to apis**: The BFF can expose embedded apis (which are embedded in the BFF itself) or proxy calls to remote api's (which is more common in a microservice environment). While proxying, it will exchange the authentication cookie for an access token.
35
-
***Session Management**: The BFF can manage the users session. This can either be cookiebased session management or storagebased session management.
32
+
***Authentication flows**: The server handles the authentication flows. There are specific endpoints for login / logout. While the browser is involved with these authentication flows, because the user is redirected to and from the identity provider, the browser-based application will never see the authentication tokens. These are exchanged for a code on the server only.
33
+
***Cookies**: After successful authentication, a cookie is added. This cookie protects all subsequent calls to the APIs. When using this type of authentication, **CSRF protection** is very important.
34
+
***Access to APIs**: The BFF can expose embedded APIs (which are hosted by the BFF itself) or proxy calls to remote APIs (which is more common in a microservice environment). While proxying, it will exchange the authentication cookie for an access token.
35
+
***Session Management**: The BFF can manage the users session. This can either be cookie-based session management or storage-based session management.
36
36
37
37
38
38
## Internals
39
39
Duende.BFF builds on widely used tools and frameworks, including ASP.NET Core's OpenID Connect and cookie authentication
40
-
handlers, YARP, and Duende.AccessTokenManagement. Duende.BFF combines these tools and adds additional security and
40
+
handlers, YARP, and [Duende.AccessTokenManagement](/accesstokenmanagement/index.mdx). Duende.BFF combines these tools and adds additional security and
41
41
application features that are useful with a BFF architecture so that you can focus on providing application logic
42
42
instead of security logic:
43
43
@@ -50,7 +50,7 @@ contributors to this library, we think it is a well implemented and flexible imp
50
50
51
51
### ASP.NET Cookie Handler
52
52
53
-
Duende.BFF uses ASP.NET's Cookie handler for session management. The Cookie handler provides a claims-based identity to
53
+
Duende.BFF uses ASP.NET's Cookie handler for session management. The cookie handler provides a claims-based identity to
54
54
the application persisted in a digitally signed and encrypted cookie that is protected with modern cookie security
55
55
features, including the Secure, HttpOnly and SameSite attributes. The handler also provides absolute and sliding session
56
56
support, and has a flexible extensibility model, which Duende.BFF uses to
Copy file name to clipboardExpand all lines: src/content/docs/bff/architecture/multi-frontend.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,7 +29,7 @@ The Duende BFF V4 library doesn't ship with an abstraction to store or read fron
29
29
30
30
## A Typical Example
31
31
32
-
Consider an enterprise that hosts multiple browser based applications. Each of these applications is developed by a separate team and as such, has it's own deployment schedule.
32
+
Consider an enterprise that hosts multiple browser based applications. Each of these applications is developed by a separate team and as such, has its own deployment schedule.
33
33
34
34
There are some internal-facing applications that are exclusively used by internal employees. These internal employees are all present in Microsoft Entra ID, so these internal-facing applications should directly authenticate against Microsoft Entra ID. These applications also use several internal APIs, that due to the sensitivity, should not be accessible by external users. However, they also use some of the more common APIs. These apps are only accessible via an internal DNS name, such as `https://app1.internal.example.com`.
35
35
@@ -60,9 +60,9 @@ After your application's logic is executed, there are two middlewares registered
60
60
61
61
5.`MapRemoteRoutesMiddleware` - This will handle any configured remote routes. Note, it will not handle plain YARP calls, only routes that are specifically added to a frontend.
62
62
63
-
6.`ProxyIndexMiddleware` - If configured, this proxy the `index.html` to start the browser based app.
63
+
6.`ProxyIndexMiddleware` - If configured, this proxies the `index.html` to start the browser based app.
64
64
65
-
If you don't want this automatic mapping of BFF middleware, you can turn it off using `BffOptions.AutomaticallyRegisterBffMiddleware`. Please note then you're responsible for manually adding the middlewares:
65
+
If you don't want this automatic mapping of BFF middleware, you can turn it off using `BffOptions.AutomaticallyRegisterBffMiddleware`. When doing so, you'll need to manually register and add the middlewares:
// Only add this if you want to proxy to remote api's.
78
+
//NOTE: Only add this if you want to proxy remote APIs.
79
79
app.UseBffRemoteRoutes();
80
80
81
81
app.MapBffManagementEndpoints();
@@ -84,17 +84,17 @@ app.UseBffIndexPages();
84
84
app.Run();
85
85
```
86
86
87
-
## Authentication architecture
87
+
## Authentication Architecture
88
88
89
-
When you use multiple frontends, you can't rely on [manual authentication configuration](../fundamentals/session/handlers.mdx#manually-configuring-authentication). This is because each frontend requires it's own scheme, and potentially it's own OpenID Connect and Cookie configuration.
89
+
When you use multiple frontends, you can't rely on [manual authentication configuration](../fundamentals/session/handlers.mdx#manually-configuring-authentication). This is because each frontend requires its own scheme, and potentially its own OpenID Connect and Cookie configuration.
90
90
91
91
The BFF registers a dynamic authentication scheme, which automatically configures the OpenID Connect and Cookie Scheme's on behalf of the frontends. It does this using a custom `AuthenticationSchemeProvider` called `BffAuthenticationSchemeProvider` to return appropriate authentication schemes for each frontend.
92
92
93
93
The BFF will register two schemes:
94
-
*'duende-bff-oidc'.
95
-
*'duende-bff-cookie'.
94
+
*`duende-bff-oidc`
95
+
*`duende-bff-cookie`
96
96
97
97
Then, if there are no default authentication schemes registered, it will register 'duende_bff_cookie' schemes as the `AuthenticationOptions.DefaultScheme`, and 'duende_bff_oidc' as the `AuthenticationOptions.DefaultAuthenticateScheme` and `AuthenticationOptions.DefaultSignOutScheme`. This will ensure that calls to `Authenticate()` or `Signout()` will use the appropriate schemes.
98
98
99
-
If you're using multiple frontends, then the BFF will create dynamic schemes with the following signature: 'duende_bff_oidc_[frontendname]' and 'duende_bff_cookie_[frontendname]'. This ensures that every frontend can use it's own OpenID Connect and Cookie settings.
99
+
If you're using multiple frontends, then the BFF will create dynamic schemes with the following signature: `duende_bff_oidc_[frontendname]` and `duende_bff_cookie_[frontendname]`. This ensures that every frontend can use its own OpenID Connect and Cookie settings.
//You can also add custom transformers, such as this one that adds an additional header
87
+
//You can also add custom transformers, such as this one that adds an additional header
88
88
context.AddRequestHeader("custom", "with value");
89
89
90
90
});
91
-
92
91
```
93
92
94
-
The default transformbuilder performs these transforms:
93
+
The default transform builder performs these transforms:
95
94
96
95
```csharp
97
96
context.AddRequestHeaderRemove("Cookie");
98
97
context.AddPathRemovePrefix(localPath);
99
98
context.AddBffAccessToken(localPath);
100
99
```
101
100
102
-
For more information, also see the [yarp documentation on transforms](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/yarp/transforms?view=aspnetcore-9.0)
101
+
For more information, also see the [YARP documentation on transforms](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/yarp/transforms?view=aspnetcore-9.0)
103
102
104
-
### Changing the default transformer.
103
+
### Changing The Default Transformer
105
104
106
105
You can change the default transformer builder delegate by registering one in the services collection:
The back-channel logout endpoint has several extensibility points organized into two interfaces. The *IBackChannelLogoutEndpoint* is the toplevel abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic or to change how it validates incoming requests. When the back-channel logout endpoint receives a valid request, it revokes sessions using the *ISessionRevocationService*.
15
+
The back-channel logout endpoint has several extensibility points organized into two interfaces. The `IBackChannelLogoutEndpoint` is the top-level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic or to change how it validates incoming requests. When the back-channel logout endpoint receives a valid request, it revokes sessions using the `ISessionRevocationService`.
16
16
17
17
## Request Processing
18
-
You can add custom logic to the endpoint by implementing the *IBackChannelLogoutEndpoint* .
18
+
You can add custom logic to the endpoint by implementing the `IBackChannelLogoutEndpoint` .
19
19
20
-
*ProcessRequestAsync* is the toplevel function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
20
+
`ProcessRequestAsync` is the top-level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
@@ -31,4 +31,4 @@ public class CustomizedBackChannelLogoutService : IBackChannelLogoutEndpoint
31
31
32
32
33
33
## Session Revocation
34
-
The back-channel logout service will call the registered session revocation service to revoke the user session when it receives a valid logout token. To customize the revocation process, implement the *ISessionRevocationService*.
34
+
The back-channel logout service will call the registered session revocation service to revoke the user session when it receives a valid logout token. To customize the revocation process, implement the `ISessionRevocationService`.
You can add your own implementation by overriding the default after calling *AddBff()*.
28
+
You can add your own implementation by overriding the default after calling `AddBff()`.
29
29
30
-
The management endpoint services all inherit from the *IBffEndpointEndpoint*, which provides a general-purpose mechanism to add custom logic to the endpoints.
30
+
The management endpoint services all inherit from the `IBffEndpointEndpoint`, which provides a general-purpose mechanism to add custom logic to the endpoints.
31
31
32
32
```csharp
33
33
publicinterfaceIBffEndpointService
@@ -36,6 +36,6 @@ public interface IBffEndpointService
36
36
}
37
37
```
38
38
39
-
None of the endpoint services contain additional members beyond *ProcessRequestAsync*.
39
+
None of the endpoint services contain additional members beyond `ProcessRequestAsync`.
40
40
41
41
You can customize the behavior of the endpoints either by implementing the appropriate interface or by extending the default implementation of that interface. In many cases, extending the default implementation is preferred, as this allows you to keep most of the default behavior by calling the base *ProcessRequestAsync* from your derived class. Several of the default endpoint service implementations also define virtual methods that can be overridden to customize their behavior with more granularity.
The BFF login endpoint has extensibility points in two interfaces. The *ILoginEndpoint* is the toplevel abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic. The *IReturnUrlValidator* ensures that the *returnUrl* parameter passed to the login endpoint is safe to use.
15
+
The BFF login endpoint has extensibility points in two interfaces. The `ILoginEndpoint` is the top-level abstraction that processes requests to the endpoint. This service can be used to add custom request processing logic. The `IReturnUrlValidator` ensures that the `returnUrl` parameter passed to the login endpoint is safe to use.
16
16
17
17
## Request Processing
18
-
*ProcessRequestAsync* is the top level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
18
+
19
+
`ProcessRequestAsync` is the top-level function called in the endpoint service and can be used to add arbitrary logic to the endpoint.
19
20
20
21
For example, you could take whatever actions you need before normal processing of the request like this:
21
22
@@ -29,4 +30,5 @@ public Task ProcessRequestAsync(HttpContext context, CancellationToken ct)
29
30
```
30
31
31
32
## Return URL Validation
32
-
To prevent open redirector attacks, the *returnUrl* parameter to the login endpoint must be validated. You can customize this validation by implementing the *IReturnUrlValidator* interface. The default implementation enforces that return urls are local.
33
+
34
+
To prevent open redirector attacks, the `returnUrl` parameter to the login endpoint must be validated. You can customize this validation by implementing the `IReturnUrlValidator` interface. The default implementation enforces that return URLs are local.
0 commit comments