Introduction to the .NET Access Control Service

Hands-On Lab Introduction to the Access Control Service Lab version: 1.0.0 Last updated: DATE quot;
M/d/yyyyquot;
9/29/200811/16/2009 Contents TOC quot;
Heading 3,2,pp Topic,1,PP Procedure start,3quot;
Overview PAGEREF _Toc245814168 3 Exercise 1: Using ACS with Symmetric Keys PAGEREF _Toc245814169 13 Task 1 - Exploring the Initial Solution PAGEREF _Toc245814170 15 Task 2 - Sign up for .NET Services and create a service namespace PAGEREF _Toc245814171 16 Task 3 - Set the service to accept & validate ACS tokens PAGEREF _Toc245814172 20 Task 4 - Configure the ACS Service Namespace to implement access logic for a specific caller PAGEREF _Toc245814173 25 Task 5 - Configure the client to use ACS to access the Service PAGEREF _Toc245814174 30 Exercise 1: Verification PAGEREF _Toc245814175 33 Exercise 1: Summary PAGEREF _Toc245814176 36 Exercise 2: Using ACS with SAML Tokens PAGEREF _Toc245814177 36 Task 1 - Configure the ACS service to accept users from a directory PAGEREF _Toc245814178 38 Task 2 - Create an “ADFSv2 ready” client PAGEREF _Toc245814179 44 Exercise 2: Verification PAGEREF _Toc245814180 49 Exercise 2: Summary PAGEREF _Toc245814181 50 Summary PAGEREF _Toc245814182 50 Overview The .NET Services Access Control Service (ACS) is a service designed to secure REST web services. ACS allows a REST web services to integrate with both simple clients and enterprise identity technologies using a single code base. ACS simplifies access control by enabling Web service providers to offload the cost and complexity of integrating with various customer identity technologies. Without having to understand and address each of these technologies, Web services can easily integrate with ACS using a simple provisioning process and REST-based management API. Subsequently, the web service can allow ACS to serve as the point of integration for service consumers. This hands-on lab will show you how to take advantage of ACS to manage access control to your REST web services. The lab will explore how to handle access using symmetric keys as credentials, a common practice when accessing REST APIs. ACS extends the common scenario with claims-based access capabilities while maintaining the simplicity of the REST approach. Furthermore, the lab will demonstrate how you can use ACS for easily bridging the gap that traditionally separate the worlds of enterprise services and REST services. You will learn how you can take advantage of preexisting identity infrastructure, such as Active Directory and ADFSv2, for enabling enterprise users to instantly access REST web services. While the samples will be based on .NET and WCF, you will discover that what you will learn about the use of ACS can be easily generalized to other platforms. Objectives In this Hands-On Lab, you will learn how to: Modify your WCF services to take advantage of ACS for handling access control Create and manage ACS Service Namespaces; work with token policies, issuers, scopes and rules Invoke REST web services secured by ACS Obtain tokens from ACS via SAML token, and use them to invoke REST web services System Requirements You must have the following items to complete this lab: Microsoft® Windows® Vista SP2 (32-bits or 64-bits) , Microsoft® Windows Server 2008 SP2 (32-bit or 64-bit), Microsoft® Windows Server 2008 R2, or Microsoft® Windows® 7 RTM (32-bits or 64-bits) Microsoft® .NET Framework 3.5 SP1 Microsoft® Visual Studio 2008 Microsoft® Windows Identity Foundation Runtime Microsoft® Windows PowerShell Setup You must perform the following steps to prepare your computer for this lab. Run the command file SetupLab.cmd located at %YourInstallationFolder%absntroToAccessControlServiceourceetup as administrator (right-click the SetupLab.cmd file and select Run as administrator). This script will just install some code snippets that will be used across the lab and the localhost certificate used in the second exercise by the local STS. Note: For convenience, much of the code is available as Visual Studio code snippets. This command file launches the Visual Studio installer file that installs the code snippets for the lab and then it installs the required certificates to perform this lab. The following screen is shown first. Click Next to continue. Figure 1 Running the Configuration Wizard The following screen shows a summary of the steps the Configuration Wizard will make. Click Next to continue to the prerequisite validation. Figure 2 Summary of steps in the Configuration Wizard The Configuration Wizard will now check for missing dependencies. If missing dependencies are found, the wizard will aid you in downloading and installing them. After fixing the dependencies you may click Rescan to attempt to detect the remaining dependencies. Figure 3 Configuration Wizard showing missing dependencies Finally, when the Configuration Wizard verified that all the prerequisites are in place, click Next to continue with the lab configuration. The next step is to install the Code Snippets. Figure 4 Configuration Wizard showing prerequisites When the Visual Studio Content Installer is shown, choose all items from the list (by default all items are selected) and click Next. Figure 5 Code snippets for exercises A dialog window appears warning that the file is not signed; choose Yes to proceed anyway. Figure 6 Warning dialog window When prompted for the location of the C# snippets, highlight all snippets, click the check box next to My Code Snippets under the Visual Studio 2008 node, and click Next. Figure 7 Installation location for C# code snippets Click Finish to install the code snippets. Figure 8 Summary of the content to be installed The installation should proceed and install all snippets. Figure 9 Installation completed Click Close to dismiss the confirmation dialog. Note: Next, the setup script will proceed by replacing any existing localhost certificate with a new one. If you already have a quot;
localhostquot;
certificate needed by another application, ensure to make a back up copy of it before continue with the lab's certificates installation. You can find more information on how to back up a certificate by Exporting the Certificate with the Private Key on this TechNet link. Once closed the code snippets installer, the setup script will proceed with the certificates installation. If prompted, press Y to continue with the required certificates installation. Figure 10 Certificates installation finished When finished press any key to close the setup console. Note: In addition to the setup script inside the %YourInstallationFolder%absntroToAccessControlServiceourceetup folder, there is a Cleanup.cmd file you can use to uninstall all the code snippets installed by the SetupLab.cmd script. Exercises The following exercises make up this Hands-On Lab: Using ACS with Symmetric Keys Using ACS with SAML Tokens Note: Each exercise is accompanied by a starting solution. These solutions are missing some code sections that are completed through each exercise and therefore will not work if running them directly. Inside each exercise you will also find an end folder where you find the resulting solution you should obtain after completing the exercises. You can use this solution as a guide if you need additional help working through the exercises. Using the Code Snippets With code snippets you have all the code you need at your fingertips. The lab document will tell you exactly when you can use them. For example, Add the following using statements. (Code Snippet – Introduction to ACS Lab - Ex01 Default Usings) C# using System.Linq; using Microsoft.IdentityModel.Claims; To add this code snippet in Visual Studio you simply place the cursor where you'd like the code to be inserted, start typing the snippet name, in this case IntroductionToACSLabEx01DefaultUsings, watch as Intellisense picks up the snippet name, and hit the TAB key twice once the snippet you want is selected. The code will be inserted at the cursor location. To insert a code snippet using the mouse rather than the keyboard (i.e. for web.config file and any other XML document), right-click where you want the code snippet to be inserted, select Insert Snippet... then My Code Snippets and then select the relevant snippet. To learn more about Visual Studio IntelliSense Code Snippets, including how to create your own, please see http://msdn.microsoft.com/en-us/library/ms165392.aspx. Estimated time to complete this lab: 50 minutes Exercise 1: Using ACS with Symmetric Keys Imagine you run a web site that offers weather forecast reports. Your business model has always been selling access to your web pages, but your customers are increasingly pressuring you to provide programmatic access to your forecasts, so that they can be easily integrated in their applications. You want to satisfy their demands, but you don’t want to get caught in managing multiple relationships or invest too much energy in handling access control for your API. Enter the Access Control Service (ACS). You can outsource to ACS most of your access control logic. ACS takes care of authenticating your customers for you, issuing them a token that proves they successfully authenticated and that contains information about their access rights. All you need to do from your application is verifying the presence of such a token in the call, and enforce the access control policies that its content entails. The interaction described above is commonly known as claims-based access, from the fact that the user attributes included in the token are known as claims. A claim is a statement about a user, issued by an authority: if an application receives claims about a user from an authority it trusts, it will assume those claims to be true and act upon them accordingly. This is a very natural process, which we commonly experience in real life without even knowing it: every time you show your driver’s license for proving your age you are using claims. Claims-based access is common practice for enterprise grade SSO solutions, based on open protocols such as WS-Federation, SAML and WS-Trust, however it was not available for REST scenarios until now. ACS implements a new REST-friendly protocol, called WRAP (Web Resource Authorization Protocol), which allows you to request tokens from ACS and use them when invoking REST services. The tokens you obtain from the ACS are Simple Web Tokens, or SWT: their compact format makes them ideal for REST. This exercise will expand on the weather reporting scenario above, and will walk you through the process of: Modifying a WCF service to take advantage of ACS for handling access control Create and manage an ACS Service Namespace; learn how to work with ACS resources (token policies, issuers, scopes and rules) Enable a client to obtain a token from ACS via symmetric key, and use it for invoking the WCF service above in a RESTful way Figure 11 A summary of the scenario enabled by this exercise. The client requests (1) and obtains (2) a SWT token from the Access Control Service. The client then uses the SWT to invoke the service (3) and, upon successful authorization in ACSAuthorizationManager (4), reaches the intended service method. Task 1 - Exploring the Initial Solution The exercise will modify an existing solution, which already contains a WCF service and its client ready for you to try. The service is exposed with a REST-friendly binding, and has no authentication. Let’s take a look at it. Open Microsoft Visual Studio 2008 with administrator privileges. From Start | All Programs | Microsoft Visual Studio 2008, right-click on Microsoft Visual Studio 2008 and select Run as administrator. Open the SimmetricKey.sln solution file located in the %YourInstallationFolder%absntroToAccessControlServiceourcex01-UsingACSWithSymmetricKeyegin folder. Right click on the Service project (in Solution Explorer), and select Debug | Start new instance to run the Service. The web service is a façade to the weather reporting system, and offers two methods corresponding to two different reports for a given zip code: one that spawns three days and another that covers ten days. Figure 12 Weather Service running in console Right click on the Client project (in Solution Explorer), and select Debug | Start new instance to run the Client. The client will request the three days report and the ten days one after the other. We have no authentication or authorization mechanism in place, hence both calls will succeed. Figure 13 Weather Service Client running Close both applications. Both applications may be closed by pressing Enter on their window. Task 2 - Sign up for .NET Services and create a service namespace In this task, you will create a new .NET Services project. Navigate to https://netservices.azure.com. You will be prompted for your Windows Live ID credentials if you are not already signed in. Create a new Project. Type a project name, such as your company name or your name, accept the Terms of Use and click the OK button. Figure 14 Azure .Net Services – Create a new project Now you will add the first Service Namespace to the project just created. A Service Namespace represents a namespace for the Service Bus and the Access Control Service. To do this, click on the name of the newly created Project and then click the Add Service Namespace link. Figure 15 Azure .Net Services – Project Summary Type in a name for your Service Namespace, select a Region for your service to run in, and click the Create button. Make sure to validate the availability of the name first. Service names must be globally unique as they are in the cloud and accessible by whomever you decide to grant access. Please be patient while your service is activated. It can take a few minutes while it is provisioned. You may have to refresh the browser to show the service is active. Figure 16 Azure .Net Services – Creating a Service Namespace Figure 17 Azure .Net Services – Project Summary listing the Service Namespaces Click on the Service Namespace just created and review the information like the management key, the different endpoints to interact with the Access Control Service, etc. Figure 18 The Service Namespace details Note: To sign in at any time, simply navigate to https://netservices.azure.com, click Sign In and provide your Live ID credentials. Clicking the .Net Services tab on the left will list the Services Projects associated with your account. Task 3 - Set the service to accept & validate ACS tokens Your service will need few modifications in order to take advantage of ACS. In summary, you will need to ensure that before your code is invoked the content of the request is inspected, searching for a SWT token. Once verified its presence, you will have to check that it is signed with the correct key (more on this below) and that it contains the claims that your access control policy mandates. WCF provides various extensibility points you can leverage in order to inspect the request before it reaches your service code. In this case, an appropriate way of implementing the checks described above is to derive from the ServiceAuthorizationManager class and embed the necessary logic in it. Once we have our custom ServiceAuthorizationManager class we can insert it in the WCF pipeline, so that it will be automatically executed for us at every service invocation. For the purposes of this lab we are providing a ServiceAuthorizationManager implementation for you, ready to be imported in the WCF service project. In Solution Explorer, right click on the Service project and select Add | Existing Item. Browse to the %YourInstallationFolder%absntroToAccessControlServicex01-UsingACSWithSymmetricKeyssets folder and select ACSAuthorizationManager.cs. Click OK to close the window. Let’s take a quick peek at the ACSAuthorizationManager class. Double-click on the ACSAuthorizationManager.cs file you just imported. The class has just two members and a simple constructor: C# public class ACSAuthorizationManager : ServiceAuthorizationManager { private TokenValidator validator; private string requiredClaimType; public ACSAuthorizationManager(string trustedSolution, string trustedAudienceValue, string trustedSigningKey, string requiredClaimType) { this.validator = new TokenValidator(trustedSolution, trustedAudienceValue, trustedSigningKey); this.requiredClaimType = requiredClaimType; } Note: The TokenValidator class contains the logic that establishes if the incoming token is well formed and has not been tampered with; the requiredClaimType member represents the claim we expect to receive, and on which we want to perform our access control checks. The constructor simply instantiates a new TokenValidator (more on its initialization parameters below) and assigns the requiredClaimtype member. The key method of a ServiceAuthorizationManager is CheckAccessCore. Let’s examine our override: C# protected override bool CheckAccessCore(OperationContext operationContext) { // get the authorization header string authorizationHeader = WebOperationContext.Current.IncomingRequest.Headers[HttpRequestHeader.Authorization]; if (!string.IsNullOrEmpty(authorizationHeader)) { // check that it starts with 'simpleapiauth' if (authorizationHeader.StartsWith(quot;
WRAPv0.8quot;
, StringComparison.OrdinalIgnoreCase)) { // check there is a ' ' between 'simpleapiauth' and the token // no other spaces allowed string[] tokenValues = authorizationHeader.Split(' '); if (tokenValues.Length == 2) { // validate the token if (this.validator.Validate(tokenValues[1])) { // check for an action claim and get the value Dictionary<string, string> claims = this.validator.GetNameValues(tokenValues[1]); // use the operation name to determine the required action value string requiredActionClaimValue = WebOperationContext.Current.IncomingRequest.UriTemplateMatch.RelativePathSegments.First(); string actionClaimValue; if (claims.TryGetValue(this.requiredClaimType, out actionClaimValue)) { // check for quot;
,quot;
delimited values string[] actionClaimValues = actionClaimValue.Split(','); // check for the correct action claim value if (actionClaimValues.Contains(requiredActionClaimValue, StringComparer.OrdinalIgnoreCase)) { return true; } } } } } } WebOperationContext.Current.OutgoingResponse.StatusCode = HttpStatusCode.Unauthorized; WebOperationContext.Current.OutgoingRequest.Headers.Add(quot;
WWW-Authenticatequot;
, quot;
WRAPquot;
); return false; } } Without going too much into details, the method: Inspects the Authorization HTTP header and verifies it is complying with the WRAP protocol Retrieves the token from the header and validates it (more on this later) If the token resulted valid, it retrieves the action corresponding to the method currently being called. It then queries the token to retrieve the values of the claim type indicated by requiredClaimType. If among those values there is the action of the current method, the call is authorized and CheckAccessCore returns True If any of the checks above fail, the method prepares the response to return a 401:Unauthorized code to the caller and exits by returning False As we have seen above, ACSAuthorizationManager relies on the helper class TokenValidator for checking the validity of the incoming token. Also in this case we are providing an implementation for you. In Solution Explorer, right click on the Service project and select Add | Existing Item. Browse to the %YourInstallationFolder%absntroToAccessControlServiceourcex01-UsingACSWithSymmetricKeyssets folder and select TokenValidator.cs. Click OK to close the window. Open TokenValidator.cs by double-clicking on it in Visual Studio. The class TokenValidator contains boilerplate code for performing verifications on the incoming token: let’s take a look at its main parts. The constructor is truly straightforward: C# public TokenValidator(string trustedSolution, string trustedAudienceValue, string trustedSigningKey) { this.trustedSigningKey = trustedSigningKey; this.trustedTokenIssuer = string.Format(acsBaseAddress, trustedSolution); this.trustedAudienceValue = trustedAudienceValue; } Let’s examine the meaning of the parameters it requires: trustedSolution represents the name of your ACS Service Namespace. We will see its meaning in a later task, for now just consider it as a container for the authorization logic stored in ACS, and a part of the address to which you will send requests for tokens. trustedSigningKey represents the key you expect the incoming token to be signed with. It is associated to the authority you trust, in this case an ACS service endpoint. trustedAudienceValue is the intended destination of the call, the address to which we expect the token to be issued for. An unexpected value in this parameter would indicate that the token may have been hijacked from another call The core method of TokenValidator is Validate: C# public bool Validate(string token) { return this.IsHMACValid(token, Convert.FromBase64String(this.trustedSigningKey)) && !this.IsExpired(token) && this.IsIssuerTrusted(token) && this.IsAudienceTrusted(token); } The method uses various utility functions for verifying various characteristics of the token. Is the signature valid? Is the token past its expiration? Is it addressed to its intended audience? And so on. If you want to understand more of the SWT token format, you can examine the implementation of those utility functions: you will discover that the format is extremely simple, and so is the code required to process it. Our service project now contains all the helper code we need for using ACS. Let's modify the service initialization code to include the ACSAuthorizationManager class as appropriate. First, we'll need to add a few parameters that we will have to pass down to ACSAuthorizationManager at initialization time. In Solution Explorer, Service project, double click on the Program.cs file, and add the following code right after the Program class declaration. We described the meaning of all those parameters in the former steps. The Service Namespace and TokenPolicyKey values will be obtained from our ACS settings, and we will fill them in after we will have configured our service namespace in the next task. (Code Snippet – Introduction to ACS Lab - Ex01 Service Constants) C# public class Program { private const string ServiceNamespace = quot;
{insert service namespace here}quot;
; private const string TokenPolicyKey = quot;
{insert token policy key here}quot;
; private const string Audience = quot;
http://localhost/weatherforecastquot;
; private const string RequiredClaimType = quot;
actionquot;
; private const string AcsHostName = quot;
accesscontrol.windows.netquot;
; public static void Main(string[] args) Update the ServiceNamespace value with the Service Namespace you chose in task 2, step 4. C# private const string ServiceNamespace = quot;
; Finally, we will modify the service host to use ACSAuthorizationManager. To do that, in Program.cs add the following code right before the host.Open() invocation: (Code Snippet – Introduction to ACS Lab - Ex01 ACS Instantiation) C# host.AddServiceEndpoint(typeof(IWeatherForecast), binding, new Uri(quot;
)); host.Authorization.ServiceAuthorizationManager = new ACSAuthorizationManager( ServiceNamespace, Audience, TokenPolicyKey, RequiredClaimType); host.Open() That’s it. Our service code is now ready to handle requests secured via ACS: we no longer need to worry about handling relationships, credentials or access policies from within our service. All that’s left for us is telling ACS who should have access to our service, and in what terms. In order to do that, we will use the ACS Management Service to modify our Service Namespace according to our needs. Task 4 - Configure the ACS Service Namespace to implement access logic for a specific caller The way in which you configure your ACS Service Namespace is via the ACS management service. You can use the management service for creating, modifying and deleting the resources that are necessary for driving the token issuing behavior you want to obtain. The management service is REST-based and accepts calls secured via your service namespace managed key, which we have obtained in task 2. The November CTP of ACS provides a command line utility, ACM.exe, which allows you to interact with the management service directly from the command prompt. In this task we will use ACM.exe for setting up our Service Namespace so that it will grant one customer selective access to our weatherreport service. Namely, we will grant to our partner access to the Get3DaysForecast method but we will block calls to any other method. As we go through the steps, we will explain the purpose of the resources we will be creating and the role they play in implementing our access control logic. At the end of the task our ACS Service Namespace will be ready to issue tokens expressing our authorization logic, and we will have generated the symmetric key that our customer will use for obtaining tokens from ACS and invoke our service. Before everything else, we need to configure ACM.exe to refer to our Service Namespace and use our management key: this will ensure that all the commands we will enter will manipulate resources within our namespace and that the calls are authenticated with our management credentials. Without this step, we’d have to specify service name and management key for every command. Locate Acm.exe.config in the %YourInstallationFolder%absntroToAccessControlServiceourcessets folder and open it in Visual Studio. Change the value of the “service” entry to the name of your Service Namespace. Change the value of the entry “mgmtKey” to the value of the management key for your Service (you can find it on the .NET services portal as shown in task 2, step 5) XML <?xml version=quot;
1.0quot;
encoding=quot;
utf-8quot;
?> <configuration> <appSettings> <add key=quot;
servicequot;
value=quot;
{insert service name here}quot;
/> <add key=quot;
mgmtKeyquot;
value=quot;
{insert management key here}quot;
hostquot;
value=quot;
/> </appSettings> </configuration> We are now ready to manage our solution. We have command line templates ready for you to use for every resource you will need to create: all you need to do is copy & paste them from the text file we provide to a Powershell console and fill in the required parameters. You can find the list of commands in %YourInstallationFolder%absntroToAccessControlServiceourcex01-UsingACSWithSymmetricKeyeginetup.ps.txt. The first resource we need to create is a Token Policy. To do this, open a Powershell console, navigate to the %YourInstallationFolder%absntroToAccessControlServiceourcessets folder and paste the [CREATE_TOKENPOLICY] command from Setup.ps.txt. Powershell $tokenpolicyid = .cm.exe create tokenpolicy -name:weatherforecast -autogeneratekey -simpleout Note: A token policy represents a set of parameters that ACS will use for issuing a token. A service namespace can contain multiple token policies. A token policy is defined by four properties: Id: unique identifier which characterizes the resource. Every ACS resource has one: it can be used for constructing the resource URI. The Id is assigned by the service at creation time, hence we don’t need to specify it. DisplayName: a mnemonic moniker assigned to the resource. As for Id, ever ACS resource has one: however it does not have to be unique. The ACM tool represents DisplayName with the parameter name. DefaultTokenLifetimeInSeconds: The number of seconds that the token will be valid for. The ACM tool represents this parameter as timeout: if you don’t specify it, as shown in our command line, the default value of 28800 seconds (8 hours) will be used. SigningKey: The signing key ACS uses to sign tokens issued with this token policy. ACS sign tokens via HMACSHA256 algorithm, using 32 byte keys. ACM gives you the choice of either specify a key value, via –key parameter, or rely on the service to generate one via –autogenerate parameter. Next, we need to create an ACS Scope that will gather all our access control logic that will have to be triggered when a request is sent to the URI of our weather forecast REST service. To do this, copy and paste the command [CREATE_SCOPE] from Setup.ps.txt. Powershell $scopeid = .cm.exe create scope -name:weatherforecast -appliesto:http://localhost/weatherforecast -tokenpolicyid:$tokenpolicyid -simpleout Note: A scope is, as mentioned, the mechanism that ACS uses for associating settings to a given resource URI. As for the token policies, a service namespace can include multiple scopes. Besides the Id and DisplayName properties, common to every ACS resource, a scope is defined by: AppliesTo: The URI of the resource for which we want to specify access control logic. ACM represents this with the –appliesto parameter. TokenPolicyId: The tokens issued for accessing the resource specified in AppliesTo will follow the setting specified by the token policy represented by TokenPolicyId. ACS represents this value with the parameter –tokenpolicyid. The time has come to define the intended audience of our service: we need to tell ACS how to recognize if a call comes from a legitimate source. To do this, copy and paste the command [CREATE_ISSUER] from Setup.ps.txt. Powershell $issuerid = .cm.exe create issuer -name:weatherforecastclient -issuername:weatherforecastclient -autogeneratekey -simpleout Note: An issuer in ACS describes the cryptographic material that a caller will use when requesting a token. It will be used for authenticating the call and deciding which authorization logic should be applied for the specific service consumer. The defining properties of an issuer in ACS are: IssuerName: The name that the issuer will use for identifying itself in the token request. Note that this is different from the Name property, which is just a friendly name and never leaves the boundaries of the management service. ACM uses –issuername for representing this parameter. Algorithm: This parameters determine which kind of signature ACS should expect for tokens coming from this issuer. The possible values are Symmetrick256Key, the default, and X509. We will discuss the X509 option more in depth in the next exercise. CurrentKey: The key that ACS will need to use for verifying the signature of tokens coming from this issuer. If the algorithm is Symmetric256Key this will be a 32-byte SHA-256 key. If algorithm is X509, this will be a base64 encoded certificate. ACM represents this parameter with –key. In our specific example we are using the option –autogeneratekey, which sets the algorithm to Symmetric256Key , creates a new 32-byte key and assigns it to this issuer. This will be the key that we will have to distribute to our intended service consumer, so that it will be able to use it for requesting tokens. We finally have all the settings in place for describing our desired access control logic. In this exercise we will do something extremely simple, we will grant the right to call our Get3DaysForecast method to the issuer we previously defined and we will exclude everybody else. In practice, this means creating an ACS Rule that allows access to the Get3DaysForecast operation for any client associated to the issuer key previously created. To do this, copy and paste the command [CREATE_RULE] from Setup.ps.txt. Powershell .cm.exe create rule -scopeid:$scopeid -inclaimissuerid:$issuerid -inclaimtype:Issuer -inclaimvalue:weatherforecastclient -outclaimtype:action -outclaimvalue:Get3DaysForecast -name:client3days Note: A rule describes the logic that should be executed when a request from a certain issuer to obtain a token for a certain resource is received. Given an incoming claim type and value, it specifies which claim type and value should be included in the token the ACS will issue (according to a given token policy). The value of the outgoing claim will contain an indication if the service should allow access to the resource being requested (if access is denied, there won't be an outgoing claim). The main parameters you need to specify when creating a rule are: -scopeid: The identifier of the scope in which the rule is supposed to be triggered. The rule will be examined whenever a request to the AppliesTo resource of the indicated scope is received -inclaimissuerid: The identifier of the issuer of the token we are examining. This must be a valid (existing) issuer ID. -inclaimtype: The type of the claim in the token we received in the request to ACS for which we want to specify an access control condition -inclaimvalue: Indicates which value of the claim type indicated in inclaimtype should elicit the execution of the rule -outclaimtype: The type of the claim that should be issued by ACS in case all the input conditions are a match with the incoming token. -outclaimvalue: The value of the claim that should be issued by ACS in case all the input conditions are a match with the incoming token. -passthrough: If specified, ACS simply rewrites the input claim type & value in the token it will issue to the requestor. ACS is now ready to handle requests for our service: we just need to make sure that our service will recognize tokens issued according to the token policy we just defined. To do this, first get the token policy key from ACS using the following command. Once the command finished to execute, select the key from the console and perform a right-click (this will put the highlighted text in the clipboard). Don't close the Powershell window, as we will be using it again in the verification part. To get the key, copy and paste the command [GET_TOKENPOLICY_KEY] from Setup.ps.txt. Powershell .cm.exe get tokenpolicy -id:$tokenpolicyid Figure 19 Get the token policy key generated by ACS Paste the token policy key you just copied in the clipboard into the TokenPolicyKey constant on Servicerogram.cs file. C# private const string TokenPolicyKey = quot;
; We are all set for starting to receive calls. All we need is provisioning our customer with the issuer key we generated in step 5; that value and few lines of code for handling ACS token requests is all our customer needs for gaining access to our service. Task 5 - Configure the client to use ACS to access the Service Let’s modify our initial client with the code that is necessary for requesting a token from ACS and using the resulting token for securing the call to the service. In Solution Explorer, Client project, double click on the Program.cs file. Add the following using directives at the beginning of the file for the code we'll be adding later. (Code Snippet – Introduction to ACS Lab - Ex01 Client Usings) C# namespace Client { using System; using System.Collections.Specialized; using System.Linq; using System.Net; using System.ServiceModel; using System.ServiceModel.Security; using System.ServiceModel.Web; using System.Text; using System.Web; public class Program In Program.cs, insert the following code right after the Program class declaration. . We'll update the Service Name and Issuer Key in the next task. (Code Snippet – Introduction to ACS Lab - Ex01 Client Parameters) C# public class Program { private const string ServiceNamespace = quot;
; private const string IssuerName = quot;
weatherforecastclientquot;
; private const string IssuerKey = quot;
{insert issuer key here}quot;
; private const string AcsHostName = quot;
; public static void Main(string[] args) { Change the client to use the issuer key generated in the previous task. To do this, first get the issuer key from ACS using the following command. Once the command generates its output, select the key from the console and do a right click (this will put the highlighted text in the clipboard). To get the issuer key, copy and paste the command [GET_ISSUER_KEY] from Setup.ps.txt. Powershell .cm.exe get issuer -id:$issuerid Figure 20 Get the issuer key generated by ACS Copy the issuer key from the Powershell console and paste it into the IssuerKey constant on Client rogram.cs file. C# private const string IssuerKey = quot;
{insert issuer key here}quot;
; Update the service name (the one you’ve got in Task 2, step 4) used in the client Clientrogram.cs file. To do this, replace the ServiceNamespace constant in the code. C# private const string ServiceNamespace = quot;
; The first thing we need to do in our code is requesting a token from ACS. Add the following code at the end of Program class. (Code Snippet – Introduction to ACS Lab - Ex01 GetACSToken Method) C# ... private static string GetACSToken() { // request a token from ACS WebClient client = new WebClient(); client.BaseAddress = string.Format(quot;
https://{0}.{1}quot;
, ServiceNamespace, AcsHostName); NameValueCollection values = new NameValueCollection(); values.Add(quot;
wrap_namequot;
, IssuerName); values.Add(quot;
wrap_passwordquot;
, IssuerKey); values.Add(quot;
applies_toquot;
, quot;
); byte[] responseBytes = client.UploadValues(quot;
WRAPv0.8quot;
, quot;
POSTquot;
, values); string response = Encoding.UTF8.GetString(responseBytes); return response .Split('&') .Single(value => value.StartsWith(quot;
wrap_token=quot;
, StringComparison.OrdinalIgnoreCase)) .Split('=')[1]; } } } Note: Requesting a token from ACS via WRAP protocol and SWT token format is extremely simple: we just POST a name/value collection to our service namespace, containing the URI of the service we want to invoke and the issuer credentials we configured. At the beginning of the Main method add code to retrieve an ACS token using the GetACSToken method we just added. Insert the following code at the beginning of Main(): (Code Snippet – Introduction to ACS Lab - Ex01 GetACSToken invocation) C# public static void Main(string[] args) { string acsToken = GetACSToken(); ... To invoke the service using the token we received from ACS it's necessary to add it in the quot;
authorizationquot;
HTTP header (there are other ways of doing it, which we won’t explore here: please refer to the online documentation of ACS). To do that, insert the following code right after the OperationContextScope: (Code Snippet – Introduction to ACS Lab - Ex01 Client authorization header) C# using (new OperationContextScope(proxy as IContextChannel)) { string authHeaderValue = quot;
WRAPv0.8quot;
+ quot;
quot;
+ HttpUtility.UrlDecode(acsToken); WebOperationContext.Current.OutgoingRequest.Headers.Add(quot;
authorizationquot;
, authHeaderValue); // call the service and get a response This concludes the steps that a client needs to perform in order to be able to invoke REST services protected by ACS. In the next task we will verify how our new service works. Exercise 1: Verification In order to verify that you have correctly performed all steps in exercise one, proceed as follows: Right click on the Service project (in Solution Explorer), and select Debug | Start new instance to run the Service. Figure 21 Service console Right click on the Client project (in Solution Explorer), and select Debug | Start new instance to run the Client. Figure 22 Client console showing the 3 days forecast but not the 10 days forecast because the user don’t have access to that. Verify that the 3 days forecast is retrieved by looking at the console output. You'll also notice that the console displays an error on the following line. This is exactly in line with expectations: our rule granted this client access only to the Get3DaysForecast method, hence the attempt to access Get10DaysForecast was blocked with a (401) Unauthorized return code. Let’s see how easy it is to manage access control now that ACS takes care of it. We will add an ACS Rule that allows access to the Get10DaysForecast operation. To do this, copy and paste the command [CREATE_RULE_10DAYS] from Setup.ps.txt Powershell .cm.exe create rule -scopeid:$scopeid -inclaimissuerid:$issuerid -inclaimtype:Issuer -inclaimvalue:weatherforecastclient -outclaimtype:action -outclaimvalue:Get10DaysForecast -name:client10days Figure 23 Creating an ACS rule in PowerShell Now that the new rule is in place, the client should be able to access both forecasts. Right click on the Client project (in Solution Explorer), and select Debug | Start new instance to run the Client. Figure 24 Client console showing both forecasts Exercise 1: Summary In this exercise you learned how to modify your existing WCF REST services to rely on ACS for authentication and authorization, and walked through the changes that enable client applications to invoke services protected by ACS. You have been introduced to the main ACS resources and their basic properties, and you have learned how to work with them for implementing simple access control logic. Finally, you experienced first-hand how easy it is to change access control settings for your REST services without having to touch the code of the service itself. This exercise barely scratched the surface of what can be achieved with ACS and claims-based access: in the next exercise we will go a bit deeper and demonstrate slightly more sophisticated rules. Exercise 2: Using ACS with SAML Tokens In the first exercise we have shown how you can use ACS for enabling claims-based access without requiring anything more than the classic tools you’d use in REST API integration scenarios. In this exercise we will explore a more advanced case. ,[object Object]

The idea behind the scenario is very simple. The ADFSv2 instance can be a trusted issuer for your ACS Service Namespace, much like the issuer we defined in task 4 of the former exercise: the only difference is that it will issue tokens in SAML format instead of SWT. A client will request ACS tokens by sending one of such SAML tokens: the claim content of the SAML token is what the ACS will use for determining the content of the token it will issue to the requestor. From now on, it will be business as usual: the service will receive an SWT token, precisely as in shown in the first exercise, and will use it for determining access.

In this exercise you will learn how to modify a client in order to obtain a SAML token from an ADFSv2 instance and use it for requesting a token from ACS. You will also see how you can leverage the ADFSv2 metadata documents for automating part of the settings that the management service needs for configuring access. Finally, you will see how claims allow you to leverage user attributes such as group memberships for creating sophisticated access logic to your REST web service.Figure 25 A summary of the scenario enabled by this exercise. The client requests (1) and obtains (2) a SAML token from the ADFSv2 instance; it uses the same SAML token for requesting a token from ACS (3) and obtains a SWT token in return (4). The client then uses the SWT to invoke the service (5) and, upon successful authorization in ACSAuthorizationManager (6), reaches the intended service method. Task 1 - Configure the ACS service to accept users from a directory In this task we are going to build up on the ACS service we have built in exercise 1. We already have a service namespace and a token policy that our service is configured to trust: what we need to do is define a new issuer, which will represent the ADFSv2 authority, and create the appropriate rules that will process the incoming SAML token and produce access decisions. The exercise will modify an existing solution, which already contains a WCF service and its client ready for you to try. Open Microsoft Visual Studio 2008 with administrator privileges. From Start | All Programs | Microsoft Visual Studio 2008, right-click on Microsoft Visual Studio 2008 and select Run as administrator. Open the ACSWithSAML.sln solution file located in the %YourInstallationFolder%absntroAccessControlServiceourcex02-UsingACSWithSAMLTokensegin folder. In Solution Explorer, Service project, double click on the Program.cs file. Update the ServiceNamespace value with the service namespace you chose in the first exercise, task 2, step 4. C# private const string ServiceNamespace = quot;
; We'll now need to update our service to recognize tokens issued according to the token policy we defined on the first exercise. To do this, first get the token policy key from ACS using the following command in a Powershell console (navigate to %YourInstallationFolder%absntroAccessControlServiceourcessets). Once the command finishes execution, select the key from the console and perform a right-click (this will put the highlighted text in the clipboard). Powershell .cm.exe getall tokenpolicy Figure 26 Get the token policy key generated by ACS Paste the token policy key you just copied in the clipboard into the TokenPolicyKey constant on Servicerogram.cs file. C# private const string TokenPolicyKey = quot;
; Run the local STS that will simulate an ADFSv2. To do this, open a command prompt as administrator on %YourInstallationFolder%absntroToAccessControlServiceourcex02-UsingACSWithSAMLTokensssets and type LocalSTS.exe and keep it open for the rest of the exercise. Figure 27 Running LocalSTS tool Note: ADFSv2 is a server product with specific infrastructure requirements, among which there is Active Directory. Rather than forcing you to download, configure and manage a large virtual machine file, in this hands-on lab we will simulate an ADFSv2 instance with a custom STS written using Windows Identity Foundation. From the developer perspective the experience is absolutely equivalent: the instructions we give here would apply without any modification if the STS would be exposed by an ADFSv2 instance. Now you will configure our STS as a trusted issuer on ACS. ACS is able to automate a large part of the operation, simply by taking advantage of the metadata exposed by the STS itself. In this lab we provide a tool, FedMetadataClient, which will help you to send to the management service the opportune settings. Similarly to what you have done for the ACM tool in exercise 1, you need to configure the FedMetadataClient tool by opening the FedMetadataClient.exe.config file (from LabsntroToAccessControlServiceourcex02-UsingACSWithSAMLTokensssets) and assigning the right values to the management key and service name. You got those two values on Task 2 of the first exercise, on step 4 (when you chose the Service Namespace). XML <?xml version=quot;
1.0quot;
encoding=quot;
utf-8quot;
?> <configuration> <appSettings> <add key=quot;
stsBaseAddressquot;
value=quot;
localhost/localstsquot;
stspathquot;
value=quot;
Trust/13/UserNamequot;
serviceNamespacequot;
value=quot;
acsHostNamequot;
value=quot;
applies_toquot;
value=quot;
mgmtKeyquot;
value=quot;
{insert management key here}quot;
/> </appSettings> </configuration> Run the FedMetadataClient.exe tool. To do this, open command prompt on %YourInstallationFolder%absntroToAccessControlServiceourcex02-UsingACSWithSAMLTokensssets and type FedMetadataClient.exe Figure 28 Running FedMetadataClient from command line The FedMetadataClient tool retrieves all the relevant parameters from the STS and uses them against the management service to create an issuer. Let’s run the ACM tool to get the list of all issuers and verify that the new issuer has been correctly created. To do this, open a Powershell and run the following command. Powershell .cm.exe getall issuer Figure 29 Get the issuer ID for the SAML issuer just created Now that you created a new issuer, you need to retrieve its Id so that you can reference it when you will create the new access rules. Look for the serviceNamespaceSAML issuer, and copy the id: iss_XXXXXX attribute. To do this, select the id using the mouse and right click to place the content on the clipboard. Paste it on the LabsntroToAccessControlServiceourcex02-UsingACSWithSAMLTokenseginetup.ps.txt file on the %adfsissuer% placeholder. You already defined a scope for your service: since you want to create a new rule in that scope, you need to retrieve the scope id in order to reference it. Run the ACM tool to get the scopes and lookup the scope for the weatherforecast service. To do this, open a Powershell and run the following command. Powershell .cm.exe getall scope Figure 30 Get the scope id for the weatherforecast Look for the weatherforecast scope. Copy the id: scp_XXXXXX attribute. To do this, select the id using the mouse and right click to place the content on the clipboard. Paste it on the Setup.ps.txt file on the %scopeid% placeholder. Your new access control rule will be based on the content of the SAML token coming from the ADFSv2 instance of your trusted partner. Let’s say that you know that employees in the security group “Pilots” are meant to have access to the getforecast3days method: all you need to do is creating a rule that issues an action claim with value “Get3DaysForecast” whenever an incoming claim of type http://schemas.xmlsoap.org/claims/Group and value “Pilots” is received from this issuer. Paste in powershell the command from the setup file. Powershell .cm.exe create rule -scopeid:%scopeid% -inclaimissuerid:%adfsissuer% -inclaimtype:http://schemas.xmlsoap.org/claims/Group -inclaimvalue:Pilots -outclaimtype:action -outclaimvalue:Get3DaysForecast -name:pilotsgroup3days Figure 31 Creating a rule to allow calling Get3DaysForecast This is all you need to do for configuring your ACS Service Namespace. Next, we will explore the changes that the client must introduce for successfully obtaining a SWT token from ACS when presenting a SAML token: once that happens, it is business as usual for everything else. Task 2 - Create an “ADFSv2 ready” client In this task you will add to the client the code that retrieves a SAML token from the local STS, send it to ACS, get a SWT token back and finally call the service transmitting the SWT token in an HTTP header. In Solution Explorer, right click on the Client project and select Add Reference. Select the Microsoft.IdentityModel assembly and click OK. This will add the required assembly reference to use Windows Identity Foundation classes. Figure 32 Adding a reference to Microsoft.IdentityModel In Solution Explorer, Client project, double click on the Program.cs file. Add the following using directives at the beginning of the file for the code we'll be adding later. (Code Snippet – Introduction to ACS Lab - Ex02 Client Usings) C# namespace Client { using System; using System.Collections.Specialized; using System.IdentityModel.Tokens; using System.Linq; using System.Net; using System.ServiceModel; using System.ServiceModel.Security; using System.ServiceModel.Web; using System.Text; using System.Web; using Microsoft.IdentityModel.Protocols.WSTrust; using Microsoft.IdentityModel.Protocols.WSTrust.Bindings; The last two namespaces are from Windows Identity Foundation: we will use the classes found there for retrieving the SAML token from the local STS. Add the following constants in the body of the Program class. (Code Snippet – Introduction to ACS Lab - Ex02 Client constants) C# public class Program { private const string ServiceNamespace = quot;
; private const string AcsHostName = quot;
; private const string StsBaseAddress = quot;
localhost/localstsquot;
; private const string StsPath = quot;
Trust/13/UserNamequot;
; public static void Main(string[] args) Update the Service Namespace (the one you entered in Task 2 of the first exercise, step 4) used in the client Clientrogram.cs file. To do this, replace the ServiceNamespace constant in the code. C# private const string ServiceNamespace = quot;
; Add the following lines of code to call the local STS and receive a SAML token in return. The SAML token will then be sent to ACS to be exchanged with a SWT token. Note: The order of these instructions aim at helping you understand what it takes for a client to be able to use ACS, hence it follows a top-down approach. The code won’t compile at this point, but it eventually will, once you will have followed the instructions in the next 3 steps (Code Snippet – Introduction to ACS Lab - Ex02 Client call STS) C# public static void Main(string[] args) { string stsAddress = string.Format(quot;
https://{0}/{1}quot;
, StsBaseAddress, StsPath); string acsSTSAddress = string.Format(quot;
https://{0}.{1}/WRAPv0.8quot;
, ServiceNamespace, AcsHostName); string samlAssertion = GetSamlAssertion(stsAddress, acsSTSAddress); string acsToken = GetACSToken(samlAssertion); Add the definition of the GetSamlAssertion method, which gets a token from the local STS. To do that, copy the following code at the end of the Program class. (Code Snippet – Introduction to ACS Lab - Ex02 GetSamlAssertion Method) C# ... public static void Main(string[] args) { ... } private static string GetSamlAssertion(string stsAddress, string acsStsAddress) { WSTrustChannelFactory trustChannelFactory = new WSTrustChannelFactory( new WindowsWSTrustBinding(SecurityMode.TransportWithMessageCredential), new EndpointAddress(new Uri(stsAddress))); trustChannelFactory.TrustVersion = TrustVersion.WSTrust13; RequestSecurityToken rst = new RequestSecurityToken(WSTrust13Constants.RequestTypes.Issue, WSTrust13Constants.KeyTypes.Bearer); rst.AppliesTo = new EndpointAddress(acsStsAddress); rst.TokenType = Microsoft.IdentityModel.Tokens.SecurityTokenTypes.Saml2TokenProfile11; WSTrustChannel channel = (WSTrustChannel)trustChannelFactory.CreateChannel(); GenericXmlSecurityToken token = channel.Issue(rst) as GenericXmlSecurityToken; return token.TokenXml.OuterXml; } The code here takes advantage of the object model for Windows Identity Foundation, and specifically of the WSTrustChannel class which makes it easy to send issuing requests to a WS-Trust STS. The code in step 5 makes use of the GetACSToken method, which gets a token from ACS based on the SAML token. Add the definition of GetACSToken by coping the following code at the end of Program class. (Code Snippet – Introduction to ACS Lab - Ex02 GetACSToken Method) C# public class Program { ... private static string GetSamlAssertion(string stsAddress, string acsStsAddress) ... private static string GetACSToken(string samlAssertion) { WebClient tokenClient = new WebClient(); tokenClient.BaseAddress = string.Format(quot;
https://{0}.{1}quot;
, ServiceNamespace, AcsHostName); NameValueCollection values = new NameValueCollection(); values.Add(quot;
wrap_SAMLquot;
, samlAssertion); values.Add(quot;
applies_toquot;
, quot;
); byte[] responseBytes = tokenClient.UploadValues(quot;
WRAPv0.8quot;
, values); string response = Encoding.UTF8.GetString(responseBytes); return response .Split('&') .Single(value => value.StartsWith(quot;
wrap_token=quot;
, StringComparison.OrdinalIgnoreCase)) .Split('=')[1]; } } You can see how the method body here closely resembles the code we used in exercise 1 for performing a similar function with a symmetric key. Add the code that will add the ACS token in the authorization HTTP header. To do that, add the following code right before calling the service. (Code Snippet – Introduction to ACS Lab - Ex02 WRAP Header) C# using (new OperationContextScope(proxy as IContextChannel)) { string authHeaderValue = quot;
WRAPv0.8quot;
+ quot;
quot;
+ HttpUtility.UrlDecode(acsToken); WebOperationContext.Current.OutgoingRequest.Headers.Add(quot;
authorizationquot;
, authHeaderValue); // call the service and get a response try { ... Exercise 2: Verification In order to verify that you have correctly performed all steps in exercise two, proceed as follows: Right click on the Service project (in Solution Explorer), and select Debug | Start new instance to run the Service. Figure 33 Service console Right click on the Client project (in Solution Explorer), and select Debug | Start new instance to run the Client. Figure 34 Client console showing the 3 days forecast but not the 10 days forecast because the user doesn’t have access to that. Verify that the 3 days forecast is retrieved by looking at the console output. You'll also notice that the console displays an error on the following line. This is exactly in line with expectations: our rule granted this client access only to the Get3DaysForecast method , hence the attempt to access Get10DaysForecast was blocked with a (401) Unauthorized return code. This happened because the STS generated a SAML token with a group claim with value “Pilots” and we created an ACS rule that transform the group claim “Pilots” to Get3DaysForecast. Note: as an optional exercise, you can try to create a second rule that would grant access to the Get10DaysForecast action for the “Pilots” group. Hint: you can follow the same procedure we illustrated in the verification section of exercise 1. Exercise 2: Summary In this exercise you have learned how to take advantage of ADFSv2 identities for managing access control to REST services. What made the scenario possible is the ability of the Access Control Service of processing SAML tokens issued by ADFSv2, transforming the claims from the incoming SAML assertion in authorization directives in the resulting SWT token. Exercise 2 used the same service you developed in exercise 1: however the entire exercise 2 was completed without touching the code of the service. The service was already configured to trust SWT tokens issued by ACS, hence all it was needed for enabling a new service consumer was few calls to the ACS management service. Summary By completing this Hands-On Lab you have learned how to: Modify your WCF services to take advantage of ACS for handling access control Create and manage ACS Service Namespaces; work with token policies, issuers, scopes and rules Invoke REST web services secured by ACS Obtain tokens from ACS via SAML token, and use them to invoke REST web services You can easily generalize what you have learned here to different scenarios or technologies: since all you need is an HTTP-capable client, it is easy to imagine how to apply the steps you have seen in this lab for requesting tokens from the widest range of platforms, devices and programming styles. As you have seen in the two exercises, once your REST services are configured to trust ACS it does not really matter which technology or credentials your clients will use: your services are decoupled from those changes. When advanced capabilities are available, ACS is ready to take advantage of them: you can use what you learned in exercise 2 for taking advantage of your investment in Active Directory and ADFSv2 for extending to the REST world the sophisticated claims-based access control policies that until now were available only to WS-* stacks. We hope that the lab inspired you to think about how the ACS can help you solve your access control challenges, and we invite you to experiment with the SDK and all the rest of the learning material Microsoft offers on this topic.

Introduction to the .NET Access Control Service

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (20)

Similar a Introduction to the .NET Access Control Service

Similar a Introduction to the .NET Access Control Service (20)

Más de butest

Más de butest (20)

Introduction to the .NET Access Control Service