Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates for v4 #330

Merged
merged 36 commits into from
Nov 22, 2024
Merged
Changes from 1 commit
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
5f8c41b
Update Welcome documentation
bart-vmware Oct 7, 2024
ebd37dc
Update Bootstrap documentation
bart-vmware Oct 2, 2024
1e8d625
Update Configuration documentation
bart-vmware Oct 2, 2024
88c8a9f
Update Logging documentation
bart-vmware Oct 3, 2024
d88fe24
Update Management documentation
bart-vmware Oct 4, 2024
b9e43d6
Update File Shares documentation
bart-vmware Oct 4, 2024
ca060d9
Update Connectors documentation
bart-vmware Oct 4, 2024
6380ad9
Update Discovery documentation
bart-vmware Oct 4, 2024
7836649
Update Initializr documentation
bart-vmware Oct 21, 2024
f041480
Update Tracing documentation (needs work)
bart-vmware Nov 18, 2024
f744ffb
Update Security documentation (needs work)
bart-vmware Nov 18, 2024
2441919
update metadata-layer-changed filter
TimHess Nov 18, 2024
2a9bd55
Guides: add top banner to every file, revert preliminary changes (pac…
bart-vmware Nov 19, 2024
9762915
Apply suggestions from code review
bart-vmware Nov 20, 2024
7451f2e
Review feedback: remove note for old Tanzu versions
bart-vmware Nov 20, 2024
c5abcd2
Review feedback: remove conference materials
bart-vmware Nov 20, 2024
f4011ca
Apply suggestions from code review
bart-vmware Nov 20, 2024
b792b1a
Review feedback: update banner for Steeltoe v2
bart-vmware Nov 20, 2024
fba618a
Review feedback: update remaining banners with suggested text
bart-vmware Nov 20, 2024
b0ad843
Review feedback: recommend BootstrapLogger
bart-vmware Nov 20, 2024
14aa9ee
Review feedback: remove the note that only Eureka can be used with di…
bart-vmware Nov 20, 2024
70cc3c2
Review feedback: clarify exposure settings
bart-vmware Nov 20, 2024
fc2ff27
Review feedback: remove Windows-only note on thread dumps
bart-vmware Nov 20, 2024
3d49b48
Review feedback: update another banner for v2
bart-vmware Nov 20, 2024
16cb0b9
Review feedback: Updated banners for messaging guide
bart-vmware Nov 20, 2024
c030760
Review feedback: Add note for 'beans'
bart-vmware Nov 20, 2024
7cdf9cc
Apply suggestions from code review
bart-vmware Nov 21, 2024
4cec129
Review feedback: Add KeysToSanitize
bart-vmware Nov 21, 2024
c616ab9
Review feedback: repeat tip on AddAllActuators
bart-vmware Nov 21, 2024
5088f63
Review feedback: indicate defaults for SBA
bart-vmware Nov 21, 2024
b7a16a2
Trim trailing whitespace in *.md, ensure blank line before EOF
bart-vmware Nov 21, 2024
ab7887b
Replace TABs with spaces in *.md
bart-vmware Nov 21, 2024
e303565
Trim trailing whitespace in other non-binary files, ensure blank line…
bart-vmware Nov 21, 2024
fe2d569
Replace TABs with spaces in other non-binary files
bart-vmware Nov 21, 2024
8da7c4a
Review feedback: clarify CF security
bart-vmware Nov 21, 2024
0b1a165
Review feedback: alternate port doesn't apply to /cloudfoundryapplica…
bart-vmware Nov 21, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update Security documentation (needs work)
  • Loading branch information
bart-vmware committed Nov 19, 2024
commit f744ffb7ccab9633ce211539784f8beafdcf17cf
4 changes: 2 additions & 2 deletions api/v3/security/mtls.md
Original file line number Diff line number Diff line change
@@ -45,7 +45,7 @@ The above example will create self-signed certificates with an OrgId of `a8fef16

### Securing Endpoints

In order to use identity certificates for authorization in a service application, services need to be configured and activated and polices need to be applied.
In order to use identity certificates for authorization in a service application, services need to be configured and activated and policies need to be applied.

#### Adding and using services

@@ -76,7 +76,7 @@ public void Configure(IApplicationBuilder app, ...)

>These steps are only required on services that are receiving mTLS-secured requests

#### Applying Authorization Polices
#### Applying Authorization Policies

Steeltoe includes policies for validating that a request came from an application in the same org or the space. Once you have done the work in the `Startup` class, you can secure endpoints by using the standard ASP.NET Core `Authorize` attribute with one of these security policies.

4 changes: 2 additions & 2 deletions api/v4/security/jwt-authentication.md
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@ Many resources are available for understanding JWT (for example, see [JWT IO](ht

## Usage

This library is an extension of ASP.NET Security. For the documentation from Microsoft, visit [ASP.NET Core Security](https://learn.microsoft.com/aspnet/core/security/).
This library supplements ASP.NET Security. For the documentation from Microsoft, visit [ASP.NET Core Security](https://learn.microsoft.com/aspnet/core/security).

This package uses JSON Web Tokens (JWT) and builds on JWT Security services provided by ASP.NET Core Security. You should take some time to understand both before proceeding to use this provider.

@@ -100,7 +100,7 @@ Activate authentication and authorization services after routing services, but b
```csharp
WebApplication app = builder.Build();

// Use forwarded headers so that links generate correctly behind a reverse-proxy (eg: when in Cloud Foundry)
// Use forwarded headers so that links generate correctly behind a reverse proxy (eg: when in Cloud Foundry)
app.UseForwardedHeaders(new ForwardedHeadersOptions { ForwardedHeaders = ForwardedHeaders.XForwardedHost | ForwardedHeaders.XForwardedProto });

app.UseRouting();
16 changes: 8 additions & 8 deletions api/v4/security/mtls.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Resource Protection using Mutual TLS in ASP.NET Core

This component builds on top of [ASP.NET Core's Certificate Authentication](https://docs.microsoft.com/aspnet/core/security/authentication/certauth), with the addition of automatic configuration for [Cloud Foundry Instance Identity certificates](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html) and authorization policies based on certificate data. Additionally, resources are included for automatically generating certificates for local development that resemble what is found on the platform.
This component builds on top of [ASP.NET Core's Certificate Authentication](https://learn.microsoft.com/aspnet/core/security/authentication/certauth), with the addition of automatic configuration for [Cloud Foundry Instance Identity certificates](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html) and authorization policies based on certificate data. Additionally, resources are included for automatically generating certificates for local development that resemble what is found on the platform.

## Usage

In order to use this provider, the following steps are required:

1. Add NuGet package reference
1. Add identity certificates to configuration
1. Add identity certificates to the configuration
1. Configure authentication and authorization services
1. Include services in ASP.NET Core pipeline
1. Include services in the ASP.NET Core pipeline
1. Secure endpoints
1. Attach certificate to requests to secured endpoints

@@ -24,7 +24,7 @@ To use Certificate Authorization, you need to add a reference to the `Steeltoe.S

In a Cloud Foundry environment, instance identity certificates are automatically provisioned (and rotated on a regular basis) for each application instance. Steeltoe provides the `AddAppInstanceIdentityCertificate` extension method to find the location of the certificate files from the environment variables `CF_INSTANCE_CERT` and `CF_INSTANCE_KEY`. When running outside of Cloud Foundry, this method will automatically generate similar certificates. Use the optional parameters to coordinate `organizationId` and/or `spaceId` between your applications to facilitate communication when running outside of Cloud Foundry.

This code adds the certificate paths to configuration for use later (and generates the instance identity certificate when running outside Cloud Foundry):
This code adds the certificate paths to the configuration for use later (and generates the instance identity certificate when running outside Cloud Foundry):

```csharp
using Steeltoe.Common.Certificates;
@@ -43,7 +43,7 @@ When running locally, the code shown above will create a chain of self-signed ce

### Securing Endpoints

In order to authorize incoming requests using an identity certificate, services need to be configured and activated, and polices need to be applied.
In order to authorize incoming requests using an identity certificate, services need to be configured and activated, and policies need to be applied.

#### Adding and using services

@@ -54,7 +54,7 @@ Several steps need to happen before certificate authorization policies can be us
1. Certificate forwarding needs to be configured (so that ASP.NET reads the certificate out of an HTTP Header)
1. Authentication services need to be added
1. Authorization services and policies need to be added
1. Middleware need to be activated
1. Middleware needs to be activated

Fortunately, all of the requirements can be satisfied with a handful of extension methods:

@@ -87,7 +87,7 @@ app.UseCertificateAuthorization();
Steeltoe exposes some of the policy-related components directly if more customized scenarios are required:

```csharp
// AuthorizationPolicyBuilder extensions
// AuthorizationPolicyBuilder setup
builder.Services.AddAuthorizationBuilder().AddOrgAndSpacePolicies()
.AddDefaultPolicy("sameOrgAndSpace", authorizationPolicyBuilder => authorizationPolicyBuilder.RequireSameOrg().RequireSameSpace());

@@ -103,7 +103,7 @@ builder.Services.AddAuthorizationBuilder().AddOrgAndSpacePolicies()
> [!NOTE]
> These steps are only required on applications that are receiving certificate-authorized requests.

#### Applying Authorization Polices
#### Applying Authorization Policies

As implied by the name of the extension method `AddOrgAndSpacePolicies` from the previous section on this page, Steeltoe provides policies for validating that a request came from an application in the same org or the same space. You can secure endpoints by using the standard ASP.NET Core `Authorize` attribute with one of these security policies.

7 changes: 4 additions & 3 deletions api/v4/security/redis-key-storage-provider.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Redis Key Storage Provider

By default, ASP.NET Core stores the key ring on the local file system. Local file system usage in a Cloud Foundry environment is unworkable and violates the [twelve-factor guidelines](https://12factor.net/) for developing cloud native applications. By using the Steeltoe Redis key storage provider, you can reconfigure the data protection service to use Redis on Cloud Foundry for storage.
By default, ASP.NET Core stores the key ring on the local file system. Local file system usage in a Cloud Foundry environment is unworkable and violates the [twelve-factor guidelines](https://12factor.net/) for developing cloud-native applications. By using the Steeltoe Redis key storage provider, you can reconfigure the data protection service to use Redis on Cloud Foundry for storage.

## Usage

@@ -32,9 +32,10 @@ cf bind-service myApp myRedisCache
cf restage myApp
```

>The preceding commands are for the Redis service provided by TAS. If you use a different service, you have to adjust the `create-service` command.
> [!NOTE]
> The preceding commands are for the Redis service provided by Tanzu Platform for Cloud Foundry. If you use a different service, you have to adjust the `create-service` command.

Once the service is bound to your application, the settings are available in `VCAP_SERVICES`.
Once the service is bound to your application, the configuration settings are available in `VCAP_SERVICES`.

### Add Redis IConnectionMultiplexer

6 changes: 3 additions & 3 deletions api/v4/security/sso-open-id.md
Original file line number Diff line number Diff line change
@@ -4,7 +4,7 @@ Single Sign-on with OpenID Connect helps you use a [UAA Server](https://github.c

## Usage

This library is an extension of ASP.NET Security. For the documentation from Microsoft, visit [ASP.NET Core Security](https://learn.microsoft.com/aspnet/core/security/).
This library supplements ASP.NET Security. For the documentation from Microsoft, visit [ASP.NET Core Security](https://learn.microsoft.com/aspnet/core/security).

Steps involved in using this library:

@@ -103,7 +103,7 @@ Direct ASP.NET Core to activate authentication and authorization services after
```csharp
WebApplication app = builder.Build();

// Use forwarded headers so that links generate correctly behind a reverse-proxy (eg: when in Cloud Foundry)
// Use forwarded headers so that links generate correctly behind a reverse proxy (eg: when in Cloud Foundry)
app.UseForwardedHeaders(new ForwardedHeadersOptions { ForwardedHeaders = ForwardedHeaders.XForwardedHost | ForwardedHeaders.XForwardedProto });

app.UseRouting();
@@ -151,7 +151,7 @@ public class HomeController : Controller

The preceding example establishes the following security rules:

* If a user attempts to access the `About` action and the user is not authenticated, the user is redirected to the OAuth server (such as a UAA Server) to login.
* If a user attempts to access the `About` action and the user is not authenticated, the user is redirected to the OAuth server (such as a UAA Server) to log in.
* If an authenticated user attempts to access the `TestGroup` action but does not meet the restrictions established by the referenced policy, the user is denied access.

### Cloud Foundry Single SignOn Service