Tutorial: How to leverage Access Control Service using SDK

Overview

This tutorial explains how developers can easily use the AppFabric SDK to write PHP applications that use the Access Control Services provided by AppFabric.

For more information about AppFabric ACS please refer to MSDN documenation

AppFabric SDK for PHP Developers provides classes to:

Retrieve different types of tokens from ACS
Validate ACS Token
Validate Claims

The following sections provide examples of the above functionality. Once you have installed and configured the SDK, you can follow the examples below.

Go to Top

Retrieving Token from ACS

The following code snippet demonstrates how to use the SDK to get ACS Token.

We first create a Scope object, which represents what kind of token we desire. In this case we want a SimpleApiAuth token. ACS requires the requestor to provide scope name and issuer key values to produce the token.

Note that scope creation and other such ACS management functions can be achieved using tge ACM tool provided by the .NET SDK for Microsoft AppFabric (Nov 2009 CTP Release). More information about the ACM tool can be found under Access Control samples provided along with that SDK under the following path “{Installation folder of .NET SDK}\Samples\AccessControl\ExploringFeatures\Management\AcmTool\Readme.htm”

  try 
  {			  
	$acmHostName = DotNetServicesEnvironment::getACMHostName();
	$serviceName = “phpservice”;
	$scope = new Scope(“simpleAPIAuth”);

	$scope->setIssuerName(ACS_TRUSTED_ISSUER);
	$scope->setIssuerSecret( ACS_TRUSTED_SECRET_KEY);
	$scope->setAppliesTo(“http://localhost/SalesDashboard/”);

	$simpleApiAuthService = new SimpleApiAuthService($acmHostName,
            $serviceName);
	$simpleApiAuthService->setScope($scope);
	$token = $simpleApiAuthService->getACSToken();

   }    
   catch(Exception $e)
   {
	throw($e);
   }

Result:

Go to Top

Token Validation

We can use ACS tokens for validating requests from client applications. One way to achieve this is retrieving the token as described above and passing it in the header to the service application. The service application will serve only the requests that have valid tokens in their headers.

The validateToken function of the TokenValidator class returns true if the passed token is valid. The function requires the signing key (obtained from ACS while creating service) for validation.

   try
   {
	$tokenValidator = new TokenValidator("phpservice", 
            "http://localhost/SalesDashboard/", $signingKey , $token);
	if($tokenValidator-> validate()) {
	     echo “Validate token success";
	else{
	     echo "Validate token failed";
	}
   }
   catch(Exception $e)
   {
	throw($e);
   }

Go to Top

Validating Claims

Tokens contain claims that can be used to track the access rights of the requestor. Suppose we have a Create Order Service that provides services like addition of new Sales Order. A request for addition should have a token that has claims required for addition. E.g. CreateOrder = true.

We can now use the validateClaims method of TokenValidator class to check if the client has the claims necessary for getting the desired service.

The following code will return true if the token has claims “CreateOrder =true”

   try
   {	
       $requiredClaims = array('CreateOrder'=>true);
       if(ValidateClaimUtil:: ValidateClaims($requiredClaims, "phpservice", 
           http://localhost/SalesDashboard/, $signingKey))
       {
           echo "Valid claims for create order";
       } 
       else
       {
	   echo "Create Order not allowed";
       }	
   }
   catch(Exception $e)
   {
       throw($e);
   }

The Credentials class has the authentication details required by ACS for retrieving token.
Each token type requires different types of credential values:

Simple API Auth token

Scope name
Issuer key

Simple web token

Simple web token

Shared secret token

Issuer name
secret

SAML token

SAML token

E.g. for Shared Secret Token the credentials object will be initialized as follows:

   try
   {
       $scope = new Scope(SHARED_SECRET);
       $scope->setIssuerName(ACS_TRUSTED_ISSUER);
       $scope->setIssuerSecret(ACS_TRUSTED_SECRET_KEY);
       $scope->setServiceNamespaceDomain(ACS_TRUSTED_SERVICE);
       $scope->setServiceURI(REQUEST_URI_STR);
       $scope->setAppliesTo(APPLIES_TO);
       $obj = new SharedSecret($acmHostName, $serviceName);
   }
   catch(Exception $e)
   {
       throw($e);
   }

Acquiring Different Types of Tokens

Simple API Auth: Acquiring SimpleAPIAuth token using getACSToken() of class SimpleApiAuthService.

  try
  {
      $acmHostName = DotNetServicesEnvironment::getACMHostName();
      $serviceName = ACS_TRUSTED_SERVICE;
      $scope = new Scope(SIMPLE_API_AUTH);

      $scope->setIssuerName(ACS_TRUSTED_SCOPENAME);
      $scope->setIssuerSecret(ACS_TRUSTED_ISSUER_KEY);
      $scope->setAppliesTo(ACS_TRUSTED_AUDIENCE);

      $simpleApiAuthService = new SimpleApiAuthService
          ($acmHostName, $serviceName);
      $simpleApiAuthService->setScope($scope);
			
      $token = $simpleApiAuthService->getACSToken();
   }	
   catch(Exception $e)
   {
      throw($e);
   }

Shared Secret Key: Acquiring SharedSecretKey token using getACSToken() from class SharedSecret.

   try
   {
       $scope = new Scope(SHARED_SECRET);
       $scope->setIssuerName(ACS_TRUSTED_ISSUER);
       $scope->setIssuerSecret(ACS_TRUSTED_SECRET_KEY);
       $scope->setServiceNamespaceDomain(ACS_TRUSTED_SERVICE);
       $scope->setServiceURI(REQUEST_URI_STR);
       $scope->setAppliesTo(APPLIES_TO);

       $obj = new SharedSecret($acmHostName, $serviceName);
       $obj->setScope($scope);	
       $token = $obj->getACSToken();
   }
   catch(Exceprion $e)					
   {
       throw($e);
   }

Simple Web Token: Acquiring SimpleWebToken using getACSToken()from class SWT

  try
  {
      $acmHostName = DotNetServicesEnvironment::getACMHostName();
      $serviceName = ACS_TRUSTED_SERVICE;
      $scope = new Scope(SIMPLE_WEB);
      $token_ = "Issuer=".urldecode(ACS_TRUSTED_ISSUER);  

      $computedSignature = base64_encode(hash_hmac('sha256', $token_, 
           base64_decode(ACS_TRUSTED_SECRET_KEY), true));

      $computedSimpleWebTokenString = $token_."&HMACSHA256=".urlencode
          ($computedSignature);
      $scope->setSimpleWebToken($computedSimpleWebTokenString);
      $scope->setServiceURI(REQUEST_URI_STR);
      $scope->setAppliesTo(APPLIES_TO);

      $obj = new SWT($acmHostName, $serviceName);
      $obj->setScope($scope);
      $token = $obj->getACSToken();
  }
  catch (Exception $e)
  {
      throw($e);
  }

Go to Top