Lab by PBB69y

VIEWS: 5 PAGES: 50

									Hands-On Lab
Introduction to the Access Control Service
Lab version: 1.0.0

Last updated: 11/10/2011
CONTENTS

OVERVIEW ................................................................................................................................................... 3

EXERCISE 1: USING ACS WITH SYMMETRIC KEYS ............................................................................. 13
       Task 1 - Exploring the Initial Solution.................................................................................................. 15
       Task 2 - Sign up for .NET Services and create a service namespace ................................................... 16
       Task 3 - Set the service to accept & validate ACS tokens ................................................................... 20
       Task 4 - Configure the ACS Service Namespace to implement access logic for a specific caller ........ 25
       Task 5 - Configure the client to use ACS to access the Service ........................................................... 30
   Exercise 1: Verification ............................................................................................................................ 33
   Exercise 1: Summary ............................................................................................................................... 36

EXERCISE 2: USING ACS WITH SAML TOKENS ................................................................................... 36
       Task 1 - Configure the ACS service to accept users from a directory ................................................. 37
       Task 2 - Create an “ADFSv2 ready” client ........................................................................................... 43
   Exercise 2: Verification ............................................................................................................................ 48
   Exercise 2: Summary ............................................................................................................................... 49

SUMMARY .................................................................................................................................................. 49
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.
    1. Run the command file SetupLab.cmd located at
       %YourInstallationFolder%\Labs\IntroToAccessControlService\Source\Setup 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.

    2. The following screen is shown first. Click Next to continue.
   Figure 1
   Running the Configuration Wizard
3. 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


4. 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


5. 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


6. 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


7. A dialog window appears warning that the file is not signed; choose Yes to proceed anyway.




   Figure 6
   Warning dialog window


8. 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


9. Click Finish to install the code snippets.
   Figure 8
   Summary of the content to be installed


10. The installation should proceed and install all snippets.
   Figure 9
   Installation completed


11. 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 "localhost" 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


    12. When finished press any key to close the setup console.

 Note: In addition to the setup script inside the
 %YourInstallationFolder%\Labs\IntroToAccessControlService\Source\Setup 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:
    1. Using ACS with Symmetric Keys
    2. 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,
    1. 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
    1. 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.
    2. Open the SimmetricKey.sln solution file located in the
       %YourInstallationFolder%\Labs\IntroToAccessControlService\Source\Ex01-
       UsingACSWithSymmetricKey\Begin folder.
    3. 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


    4. 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


    5. 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.
    1. Navigate to https://netservices.azure.com. You will be prompted for your Windows Live ID
       credentials if you are not already signed in.
    2. 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


3. 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
4. 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


5. 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.
    1. 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%\Labs\IntroToAccessControlService\Ex01-
       UsingACSWithSymmetricKey\Assets folder and select ACSAuthorizationManager.cs. Click OK
       to close the window.
    2. 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.Authoriz
ation];

    if (!string.IsNullOrEmpty(authorizationHeader))
    {
        // check that it starts with 'simpleapiauth'
        if (authorizationHeader.StartsWith("WRAPv0.8",
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.RelativePathSegme
nts.First();

                        string actionClaimValue;
                            if (claims.TryGetValue(this.requiredClaimType, out
   actionClaimValue))
                            {
                           // check for "," 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("WWW-
   Authenticate", "WRAP");
       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
3. 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%\Labs\IntroToAccessControlService\Source\Ex01-
    UsingACSWithSymmetricKey\Assets folder and select TokenValidator.cs. Click OK to close the
    window.
4. 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.
5. 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 = "{insert service namespace
   here}";
          private const     string   TokenPolicyKey = "{insert token policy key here}";
          private const     string   Audience = "http://localhost/weatherforecast";
          private const     string   RequiredClaimType = "action";
          private const     string   AcsHostName = "accesscontrol.windows.net";

           public static void Main(string[] args)



6. Update the ServiceNamespace value with the Service Namespace you chose in task 2, step 4.
   C#
   private const string ServiceNamespace = "{insert service namespace here}";



7. 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("http://localhost/weatherforecast"));

   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.
    1. 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%\Labs\IntroToAccessControlService\Source\Assets folder and open
       it in Visual Studio.
    2. 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="1.0" encoding="utf-8" ?>
        <configuration>
          <appSettings>
       <add key="service" value="{insert service name here}"/>
       <add key="mgmtKey" value="{insert management key here}" />
       <add key="host" value="accesscontrol.windows.net"/>
     </appSettings>
   </configuration>



3. 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%\Labs\IntroToAccessControlService\Source\Ex01-
   UsingACSWithSymmetricKey\Begin\Setup.ps.txt.
   The first resource we need to create is a Token Policy. To do this, open a Powershell console,
   navigate to the %YourInstallationFolder%\Labs\IntroToAccessControlService\Source\Assets
   folder and paste the [CREATE_TOKENPOLICY] command from Setup.ps.txt.
   Powershell
   $tokenpolicyid = .\acm.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.
4. 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 = .\acm.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.



5. 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 = .\acm.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.



6. 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
   .\acm.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.



7. 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
   .\acm.exe get tokenpolicy -id:$tokenpolicyid




   Figure 19
   Get the token policy key generated by ACS


8. Paste the token policy key you just copied in the clipboard into the TokenPolicyKey constant on
   Service\Program.cs file.
   C#
   private const string TokenPolicyKey = "{insert token policy key here}";
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.
    1. 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



    2. 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 = "{insert service namespace here}";
            private const string        IssuerName = "weatherforecastclient";
            private const string        IssuerKey = "{insert issuer key here}";
            private const string        AcsHostName = "accesscontrol.windows.net";

             public static void Main(string[] args)
             {
3. 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
   .\acm.exe get issuer -id:$issuerid




   Figure 20
   Get the issuer key generated by ACS


4. Copy the issuer key from the Powershell console and paste it into the IssuerKey constant on
   Client \Program.cs file.
   C#
   private const string IssuerKey = "{insert issuer key here}";



5. Update the service name (the one you’ve got in Task 2, step 4) used in the client
   Client\Program.cs file. To do this, replace the ServiceNamespace constant in the code.
   C#
   private const string ServiceNamespace = "{insert service namespace here}";



6. 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("https://{0}.{1}",
   ServiceNamespace, AcsHostName);

                 NameValueCollection values = new NameValueCollection();
                 values.Add("wrap_name", IssuerName);
                 values.Add("wrap_password", IssuerKey);
                 values.Add("applies_to", "http://localhost/weatherforecast");

                 byte[] responseBytes = client.UploadValues("WRAPv0.8", "POST",
   values);

                 string response = Encoding.UTF8.GetString(responseBytes);

               return response
                   .Split('&')
                   .Single(value => value.StartsWith("wrap_token=",
   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.



7. 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();
   ...
    8. To invoke the service using the token we received from ACS it's necessary to add it in the
       "authorization" 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 = "WRAPv0.8" + " " +
        HttpUtility.UrlDecode(acsToken);

            WebOperationContext.Current.OutgoingRequest.Headers.Add("authorization",
        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:
    1. Right click on the Service project (in Solution Explorer), and select Debug | Start new instance
       to run the Service.
   Figure 21
   Service console


2. 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.


3. 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.
4. 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
   .\acm.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


5. 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.
Let’s say you want to make your REST service available to the users stored in a business repository such
as Active Directory: this is a common requirement, but one that traditional approaches to REST security
fail to address. ACS solves this situation: if that repository has an ADFSv2 instance associated to it, ACS
can easily leverage it for enabling AD accounts to securely invoke REST services.
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.
    1. 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.
    2. Open the ACSWithSAML.sln solution file located in the
       %YourInstallationFolder%\Labs\IntroAccessControlService\Source\Ex02-
       UsingACSWithSAMLTokens\Begin folder.
3. 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 = "{insert service namespace here}";



4. 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%\Labs\IntroAccessControlService\Source\Assets). 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
   .\acm.exe getall tokenpolicy




   Figure 26
   Get the token policy key generated by ACS


5. Paste the token policy key you just copied in the clipboard into the TokenPolicyKey constant on
   Service\Program.cs file.
   C#
   private const string TokenPolicyKey = "{insert token policy key here}";
6. Run the local STS that will simulate an ADFSv2. To do this, open a command prompt as
   administrator on %YourInstallationFolder%\Labs\IntroToAccessControlService\Source\Ex02-
   UsingACSWithSAMLTokens\Assets 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.



7. 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 Labs\IntroToAccessControlService\Source\Ex02-
   UsingACSWithSAMLTokens\Assets) 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="1.0" encoding="utf-8" ?>
   <configuration>
     <appSettings>
       <add key="stsBaseAddress" value="localhost/localsts"/>
       <add key="stspath" value="Trust/13/UserName"/>
       <add key="serviceNamespace" value="{insert service namespace here}"/>
       <add key="acsHostName" value="accesscontrol.windows.net"/>
       <add key="applies_to" value="http://localhost/weatherforecast"/>
       <add key="mgmtKey" value="{insert management key here}"/>
     </appSettings>
   </configuration>



8. Run the FedMetadataClient.exe tool. To do this, open command prompt on
   %YourInstallationFolder%\Labs\IntroToAccessControlService\Source\Ex02-
   UsingACSWithSAMLTokens\Assets and type FedMetadataClient.exe




   Figure 28
   Running FedMetadataClient from command line


9. 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
   .\acm.exe getall issuer
   Figure 29
   Get the issuer ID for the SAML issuer just created


10. 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 Labs\IntroToAccessControlService\Source\Ex02-
    UsingACSWithSAMLTokens\Begin\Setup.ps.txt file on the %adfsissuer% placeholder.
11. 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
   .\acm.exe getall scope
   Figure 30
   Get the scope id for the weatherforecast


12. 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.
13. 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
   .\acm.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.
    1. 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


2. 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.
3. 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 = "{insert service namespace here}";
       private const string       AcsHostName = "accesscontrol.windows.net";
       private const string       StsBaseAddress = "localhost/localsts";
       private const string       StsPath = "Trust/13/UserName";

        public static void Main(string[] args)



4. Update the Service Namespace (the one you entered in Task 2 of the first exercise, step 4) used
   in the client Client\Program.cs file. To do this, replace the ServiceNamespace constant in the
   code.
   C#
   private const string ServiceNamespace = "{insert service namespace here}";



5. 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("https://{0}/{1}", StsBaseAddress,
   StsPath);
       string acsSTSAddress = string.Format("https://{0}.{1}/WRAPv0.8",
   ServiceNamespace, AcsHostName);

        string samlAssertion = GetSamlAssertion(stsAddress, acsSTSAddress);
        string acsToken = GetACSToken(samlAssertion);
6. 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.
7. 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("https://{0}.{1}",
   ServiceNamespace, AcsHostName);

             NameValueCollection values = new NameValueCollection();
             values.Add("wrap_SAML", samlAssertion);
             values.Add("applies_to", "http://localhost/weatherforecast");

             byte[] responseBytes = tokenClient.UploadValues("WRAPv0.8", values);
             string response = Encoding.UTF8.GetString(responseBytes);

           return response
              .Split('&')
              .Single(value => value.StartsWith("wrap_token=",
   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.
8. 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 = "WRAPv0.8" + " " +
   HttpUtility.UrlDecode(acsToken);
       WebOperationContext.Current.OutgoingRequest.Headers.Add("authorization",
   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:
    1. Right click on the Service project (in Solution Explorer), and select Debug | Start new instance
       to run the Service.




        Figure 33
        Service console


    2. 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.


    3. 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.

								
To top