Skip to content
This repository has been archived by the owner on May 17, 2019. It is now read-only.

Commit

Permalink
Updates for new documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@dtillman
dtillman committed Mar 31, 2017
1 parent 7ae0eb2 commit 4e99f0b
Show file tree
Hide file tree
Showing 3 changed files with 3 additions and 419 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Where appropriate, the components are built and unit tested on Windows, Linux an
Where appropriate, the components and samples have been tested on .NET Core 1.0.0 Preview 2 SDK, .NET 4.5.1, and on ASP.NET Core 1.0.0.

# Usage
See the Readme for each component for more details on how to make use of it in an application.
For more information on how to use these components see the online [Steeltoe documentation](http://steeltoe.io/).

# Nuget Feeds
All new development is done on the dev branch. More stable versions of the components can be found on the master branch. The latest prebuilt packages from each branch can be found on one of two MyGet feeds. Released version can be found on nuget.org.
Expand Down
240 changes: 1 addition & 239 deletions src/Steeltoe.Security.Authentication.CloudFoundry/Readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,242 +8,4 @@ There are two providers to choose from in this package:
* A provider that enables OAuth2 Single Signon with CloudFoundry Security services. Have a look at the Steeltoe [CloudFoundrySingleSignon](https://github.com/SteelToeOSS/Samples/tree/dev/Security/src/CloudFoundrySingleSignon) for a sample app.
* A provider that enables using JWT tokens issued by CloudFoundry Security services for securing REST endpoints. Have a look at the Steeltoe [CloudFoundryJwtAuthentication](https://github.com/SteelToeOSS/Samples/tree/dev/Security/src/CloudFoundryJwtAuthentication) for a sample app.

## Package Name and Feeds

`Steeltoe.Security.Authentication.CloudFoundry`

[Development feed (Less Stable)](https://www.myget.org/gallery/steeltoedev) - https://www.myget.org/gallery/steeltoedev

[Master feed (Stable)](https://www.myget.org/gallery/steeltoemaster) - https://www.myget.org/gallery/steeltoemaster

[Release or Release Candidate feed](https://www.nuget.org/) - https://www.nuget.org/

## Basic Usage
You should have a good understanding of how the new .NET [Configuration model](http://docs.asp.net/en/latest/fundamentals/configuration.html) works and a basic understanding of the `ConfigurationBuilder` and how to add providers to the builder. You should also have a good understanding of how the ASP.NET Core [Startup](https://docs.asp.net/en/latest/fundamentals/startup.html) class is used in configuring the application services and the middleware used in the app. Specfically pay particular attention to the usage of the `Configure` and `ConfigureServices` methods. And finally, you should have a good grasp of [ASP.NET Core Security](https://docs.asp.net/en/latest/security/).

With regard to CloudFoundry, you should have a good understanding of CloudFoundry OAuth2 security services (e.g. [UAA Server](https://github.com/cloudfoundry/uaa) and/or [Pivotal Single Signon](https://docs.pivotal.io/p-identity/)).

In order to use the Security provider you need to do the following:
```
1. Create and bind an instance of a CloudFoundry OAuth2 service to your application.
2. Confiure any additional settings the Security provider will need. (Optional)
3. Add the CloudFoundry configuration provider to the ConfigurationBuilder.
4. Add and Use the security provider in the application.
5. Secure your endpoints
```
## Create & Bind OAuth2 Service
As mentioned above there are a couple OAuth2 services you can use on CloudFoundry. Rather than explaining the steps here to create and bind OAuth2 service to your app, we recommend you read and follow the [Create OAuth2 Service Instance on CloudFoundry](https://github.com/SteelToeOSS/Samples/tree/dev/Security/src/CloudFoundrySingleSignon) section of the Steeltoe [CloudFoundrySingleSignon](https://github.com/SteelToeOSS/Samples/tree/dev/Security/src/CloudFoundrySingleSignon) sample.

Once you have bound the service to the app, the services settings will have been setup in `VCAP_SERVICES` and will be picked up automatically when the app is started by using the `CloudFoundry` configuration provider discussed below during application startup.

## Additional Security provider settings (Optional)
Typically you do not need to configure any additional settings for the security provider. In the below example, we show how to disable certificate validation for the security provider. This is necessary when your app is targeted to run on Windows cells on CloudFoundry and you are using self-signed certificates.
```
{
"Logging": {
"IncludeScopes": false,
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information"
}
},
"security": {
"oauth2": {
"client": {
"validate_certificates": false
}
}
}
.....
}
```

## Add the CloudFoundry Configuration Provider
Next we add the CloudFoundry Configuration provider to the builder (e.g. `AddCloudFoundry()`). This is needed in order to pickup the `VCAP_` Service bindings and add them to the Configuration. Here is some sample code illustrating how this is done:

```
#using Steeltoe.Extensions.Configuration;
public class Startup {
.....
public IConfigurationRoot Configuration { get; private set; }
public Startup(IHostingEnvironment env)
{
// Set up configuration sources.
var builder = new ConfigurationBuilder()
.SetBasePath(env.ContentRootPath)
.AddJsonFile("appsettings.json")
.AddEnvironmentVariables()
.AddCloudFoundry();
Configuration = builder.Build();
}
....
```
## Add and Use the Security Provider
The next step is to Add and Use the Security provider. You will do these two things in `ConfigureServices(..)` and the `Configure(..)` methods of the `Startup` class. How you do this depends on which provider you wish to use.

## Using OAuth2 Single Signon

The `AddCloudFoundryAuthentication()` call configures and adds the CloudFoundry OAuth2 authentication service to the ServiceCollection and the `UseCloudFoundryAuthentication()` call adds the CloudFoundry middleware to the pipeline.
```
using Steeltoe.Security.Authentication.CloudFoundry;
using Steeltoe.Extensions.Configuration;
public class Startup {
.....
public IConfigurationRoot Configuration { get; private set; }
public Startup(...)
{
.....
}
public void ConfigureServices(IServiceCollection services)
{
// Add CloudFoundry authentication service
services.AddCloudFoundryAuthentication(Configuration);
// Add framework services.
services.AddMvc();
...
}
public void Configure(IApplicationBuilder app, ....)
{
....
app.UseStaticFiles();
// Add CloudFoundry middleware to pipeline
app.UseCloudFoundryAuthentication(new CloudFoundryOptions()
{
AccessDeniedPath = new PathString("/Home/AccessDenied")
});
app.UseMvc();
}
....
```
## Using JWT Bearer Tokens

The `AddCloudFoundryJwtAuthentication()` call configures and adds the CloudFoundry JWT authentication service to the ServiceCollection and the `UseCloudFoundryJwtAuthentication()` call adds the CloudFoundry middleware to the pipeline.
```
using Steeltoe.Security.Authentication.CloudFoundry;
using Steeltoe.Extensions.Configuration;
public class Startup {
.....
public IConfigurationRoot Configuration { get; private set; }
public Startup(...)
{
.....
}
public void ConfigureServices(IServiceCollection services)
{
// Add CloudFoundry authentication service
services.AddCloudFoundryJwtAuthentication(Configuration);
// Add framework services.
services.AddMvc();
...
}
public void Configure(IApplicationBuilder app, ....)
{
....
app.UseStaticFiles();
// Add CloudFoundry middleware to pipeline
app.UseCloudFoundryJwtAuthentication();
app.UseMvc();
}
....
```
## Securing Endpoints - Authorize Attribute
Once you have the work done in your startup class you can secure endpoints using the standard ASP.NET Core `Authorize` attribute. You can do this in both ASP.NET Core Web API apps (i.e. using JWT Bearer token Security provider), and normal UI based apps.
```
using Microsoft.AspNetCore.Authentication;
....
public class HomeController : Controller
{
public IActionResult Index()
{
return View();
}
[Authorize]
public IActionResult About()
{
ViewData["Message"] = "Your About page.";
return View();
}
...
}
```
In the case above, if a user attempts to access the `About` endpoint and the user is not authenticated, then the user will be redirected to the OAuth2 server (e.g. UAA Server) to login and become authenticated.

## Securing Endpoints - Using Policies
You can also use ASP.NET Core Policies feature on the endpoints. Here is an example of a Web API endpoint with the `testgroup` policy applied:
```
using Microsoft.AspNetCore.Authentication;
....
[Route("api/[controller]")]
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
[Authorize(Policy = "testgroup")]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
...
}
```

And here is what you need to do in your `Startup` class to create the `testgroup` policy:
```
using Steeltoe.Security.Authentication.CloudFoundry;
using Steeltoe.Extensions.Configuration;
public class Startup {
.....
public IConfigurationRoot Configuration { get; private set; }
public Startup(...)
{
.....
}
public void ConfigureServices(IServiceCollection services)
{
// Add CloudFoundry authentication service
services.AddCloudFoundryJwtAuthentication(Configuration);
// Add testgroup policy mapping to claimtype 'scope'
services.AddAuthorization(options =>
{
options.AddPolicy("testgroup", policy => policy.RequireClaim("scope", "testgroup"));
});
// Add framework services.
services.AddMvc();
...
}
public void Configure(IApplicationBuilder app, ....)
{
....
app.UseStaticFiles();
// Add CloudFoundry middleware to pipeline
app.UseCloudFoundryJwtAuthentication();
app.UseMvc();
}
....
```
In the case above, if an incomming REST request is made to the `api/values` endpoint, and the request does not contain a valid JWT bearer token with a `scope` claim equal to `testgroup` the request will be rejected.
For more information on how to use this component see the online [Steeltoe documentation](http://steeltoe.io/).
Loading

0 comments on commit 4e99f0b

Please sign in to comment.