Introduction

Authorizations definition and implementation is one of the important protection measure of an application. They are defined in the creation phase of the project and, even if authorization issues are found when the application is initially released and submitted to a security audit before to go live, the most significant number of issues related to authorization came in the maintenance lifetime of the application.

This situation is often explained by the fact that features are added/modified and no review of the authorizations was performed on the application before the publishing of the new release, for cost or time issue reason.

Context

In order to try to address this situation, it’s can be interesting to automate the evaluation of the authorizations definition and implementation on the application. This, to constantly ensure that implementation of the authorizations in the application is consistent with the authorizations definition.

An authorization is often composed by 2 elements (also named dimensions): The Feature and the Logical Role that can access it (sometime a third dimension named Data is added in order to define a access that include a filtering at business data level).

The representation of the different combinations of these 2 dimensions is often named an Authorization matrix and is often formalized in an Microsoft Excel file.

During a test of an authorization, a Logical Role is also called a Point Of View.

Objective

This article describe a proposition of implementation in order to automate the tests of an authorization matrix.

This article use the assumption that 2 dimensions are used to represents an authorization for the technical proposition described and take as example a application exposing REST services.

The objective is to provide starting ideas/hints in order to create a tailored way of testing of the authorization matrix for the target application.

Proposition

In order to achieve the full automation of the evaluation of the authorization matrix, the following actions has been performed:

  1. Formalize the authorization matrix in a pivot format file allowing:

    1. The processing by a program in a easy way.
    2. To be read and updated by a human for the follow-up of the authorization combinations.
    3. Hierarchy in the information in order to easily materialize the different combinations.
    4. The maximum possible of independence from the technology and design used to implements the application exposing the features.

  2. Create a set of integration tests that fully use the authorization matrix pivot file as input source in order to evaluate the different combinations with:

    1. The minimum possible of maintenance when the authorization matrix pivot file is updated.
    2. A clear indication, in case of failed test, of the source authorization combination that do not respect the authorization matrix.

Authorization matrix pivot file

The XML format has been used to formalize the authorization matrix.

The XML structure contains 3 main sections:

  • Node roles: This node describe the possible logical roles used in the system, is used to provide a list and the explanation of the different roles (authorization level).
  • Node services: This node list and describe the available services exposed by the system and the associated logical role(s) that can call them.
  • Node services-testing: This node provide a test payload for each service if the service use input data other than coming from url or path.

This is an example of the XML used to represents the authorization:

Placeholders (values between {}) are used to mark location where test value must be placed by the integration tests if needed

  1.   <?xml version="1.0" encoding="UTF-8"?>
  2.   <!--
  3.       This file materialize the authorization matrix for the different 
  4.       services exposed by the system.
  6.       It will be used by the tests as a input sources for the different tests cases:
  7.       1) Evaluate legitimate access and is correct implementation
  8.       2) Identify not legitimate access (authorization definition issue 
  9.       on service implementation)
  11.       The "name" attribute is used for identify uniquely a SERVICE or a ROLE.
  12.   -->
  13.   <authorization-matrix>
  15.       <!-- Describe the possible logical roles used in the system, is used here to 
  16.       provide a list+explanation
  17.       of the different roles (authorization level) -->
  18.       <roles>
  19.           <role name="ANONYMOUS" 
  20.           description="Indicate that no authorization is needed"/>
  21.           <role name="BASIC" 
  22.           description="Role affected to a standard user (lowest access right just above anonymous)"/>
  23.           <role name="ADMIN" 
  24.           description="Role affected to a administrator user (highest access right)"/>
  25.       </roles>
  27.       <!-- List and describe the available services exposed by the system and the associated 
  28.       logical role(s) that can call them -->
  29.       <services>
  30.           <service name="ReadSingleMessage" uri="/{messageId}" http-method="GET" 
  31.           http-response-code-for-access-allowed="200" http-response-code-for-access-denied="403">
  32.               <role name="ANONYMOUS"/>
  33.               <role name="BASIC"/>
  34.               <role name="ADMIN"/>
  35.           </service>
  36.           <service name="ReadAllMessages" uri="/" http-method="GET" 
  37.           http-response-code-for-access-allowed="200" http-response-code-for-access-denied="403">
  38.               <role name="ANONYMOUS"/>
  39.               <role name="BASIC"/>
  40.               <role name="ADMIN"/>
  41.           </service>
  42.           <service name="CreateMessage" uri="/" http-method="PUT" 
  43.           http-response-code-for-access-allowed="200" http-response-code-for-access-denied="403">
  44.               <role name="BASIC"/>
  45.               <role name="ADMIN"/>
  46.           </service>
  47.           <service name="DeleteMessage" uri="/{messageId}" http-method="DELETE" 
  48.           http-response-code-for-access-allowed="200" http-response-code-for-access-denied="403">
  49.               <role name="ADMIN"/>
  50.           </service>
  51.       </services>
  53.       <!-- Provide a test payload for each service if needed -->
  54.       <services-testing>
  55.           <service name="ReadSingleMessage">
  56.               <payload/>
  57.           </service>
  58.           <service name="ReadAllMessages">
  59.               <payload/>
  60.           </service>
  61.           <service name="CreateMessage">
  62.               <payload content-type="application/json">
  63.                   {"content":"test"}
  64.               </payload>
  65.           </service>
  66.           <service name="DeleteMessage">
  67.               <payload/>
  68.           </service>
  69.       </services-testing>
  71.   </authorization-matrix>

Integration tests

Integration tests are implemented using a maximum of factorized code and one test case by Point Of View (POV) has been created in order to group the verifications by profile of access level (logical role) and facilitate the rendering/identification of the errors.

Parsing, object mapping and access to the authorization matrix information has been implemented using XML marshalling/unmarshalling built-in features provided by the technology used to implements the tests (JAXB here) in order to limit the code to the one in charge of performing the tests.

This the implementation of the integration tests case class:

  1.   import org.owasp.pocauthztesting.enumeration.SecurityRole;
  2.   import org.owasp.pocauthztesting.service.AuthService;
  3.   import org.owasp.pocauthztesting.vo.AuthorizationMatrix;
  4.   import org.apache.http.client.methods.CloseableHttpResponse;
  5.   import org.apache.http.client.methods.HttpDelete;
  6.   import org.apache.http.client.methods.HttpGet;
  7.   import org.apache.http.client.methods.HttpPut;
  8.   import org.apache.http.client.methods.HttpRequestBase;
  9.   import org.apache.http.entity.StringEntity;
  10.   import org.apache.http.impl.client.CloseableHttpClient;
  11.   import org.apache.http.impl.client.HttpClients;
  12.   import org.junit.Assert;
  13.   import org.junit.BeforeClass;
  14.   import org.junit.Test;
  15.   import org.xml.sax.InputSource;
  16.   import javax.xml.bind.JAXBContext;
  17.   import javax.xml.parsers.SAXParserFactory;
  18.   import javax.xml.transform.Source;
  19.   import javax.xml.transform.sax.SAXSource;
  20.   import java.io.File;
  21.   import java.io.FileInputStream;
  22.   import java.util.ArrayList;
  23.   import java.util.List;
  24.   import java.util.Optional;
  26.   /**
  27.    * Integration Test cases in charge of validate the correct implementation of the authorization matrix.
  28.    * Create on test case by logical role that will test access on all services exposed by the system.
  29.    * Implements here focus on readability
  30.    */
  31.   public class AuthorizationMatrixIT {
  33.       /**
  34.        * Object representation of the authorization matrix
  35.        */
  36.       private static AuthorizationMatrix AUTHZ_MATRIX;
  38.       private static final String BASE_URL = "http://localhost:8080";
  41.       /**
  42.        * Load the authorization matrix in objects tree
  43.        *
  44.        * @throws Exception If any error occurs
  45.        */
  46.       @BeforeClass
  47.       public static void globalInit() throws Exception {
  48.           try (FileInputStream fis = new FileInputStream(new File("authorization-matrix.xml"))) { 
  49.               SAXParserFactory spf = SAXParserFactory.newInstance();
  50.               spf.setFeature("http://xml.org/sax/features/external-general-entities", false);
  51.               spf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
  52.               spf.setFeature("http://apache.org/xml/features/nonvalidating/load-external-dtd", false);
  53.               Source xmlSource = new SAXSource(spf.newSAXParser().getXMLReader(), new InputSource(fis));
  54.               JAXBContext jc = JAXBContext.newInstance(AuthorizationMatrix.class);
  55.               AUTHZ_MATRIX = (AuthorizationMatrix) jc.createUnmarshaller().unmarshal(xmlSource);
  56.           }
  57.       }
  59.       /**
  60.        * Test access to the services from a anonymous user.
  61.        *
  62.        * @throws Exception
  63.        */
  64.       @Test
  65.       public void testAccessUsingAnonymousUserPointOfView() throws Exception {
  66.           //Run the tests - No access token here
  67.           List<String> errors = executeTestWithPointOfView(SecurityRole.ANONYMOUS, null);
  68.           //Verify the test results
  69.           Assert.assertEquals("Access issues detected using the ANONYMOUS USER point of view:\n" + formatErrorsList(errors), 0, errors.size());
  70.       }
  72.       /**
  73.        * Test access to the services from a basic user.
  74.        *
  75.        * @throws Exception
  76.        */
  77.       @Test
  78.       public void testAccessUsingBasicUserPointOfView() throws Exception {
  79.           //Get access token representing the authorization for the associated point of view
  80.           String accessToken = generateTestCaseAccessToken("basic", SecurityRole.BASIC);
  81.           //Run the tests
  82.           List<String> errors = executeTestWithPointOfView(SecurityRole.BASIC, accessToken);
  83.           //Verify the test results
  84.           Assert.assertEquals("Access issues detected using the BASIC USER point of view:\n " + formatErrorsList(errors), 0, errors.size());
  85.       }
  87.       /**
  88.        * Test access to the services from a administrator user.
  89.        *
  90.        * @throws Exception
  91.        */
  92.       @Test
  93.       public void testAccessUsingAdministratorUserPointOfView() throws Exception {
  94.           //Get access token representing the authorization for the associated point of view
  95.           String accessToken = generateTestCaseAccessToken("admin", SecurityRole.ADMIN);
  96.           //Run the tests
  97.           List<String> errors = executeTestWithPointOfView(SecurityRole.ADMIN, accessToken);
  98.           //Verify the test results
  99.           Assert.assertEquals("Access issues detected using the ADMIN USER point of view:\n" + formatErrorsList(errors), 0, errors.size());
  100.       }
  102.       /**
  103.        * Evaluate the access to all service using the point of view (POV) specified.
  104.        *
  105.        * @param pointOfView Point of view to use
  106.        * @param accessToken Access token that is linked to the point of view in terms of authorization.
  107.        * @return List of errors detected
  108.        * @throws Exception If any error occurs
  109.        */
  110.       private List<String> executeTestWithPointOfView(SecurityRole pointOfView, String accessToken) throws Exception {
  111.           List<String> errors = new ArrayList<>();
  112.           String errorMessageTplForUnexpectedReturnCode = "The service '%s' when called with POV '%s' return a response code %s that is not the expected one in allowed or denied case.";
  113.           String errorMessageTplForIncorrectReturnCode = "The service '%s' when called with POV '%s' return a response code %s that is not the expected one (%s expected).";
  114.           String fatalErrorMessageTpl = "The service '%s' when called with POV %s meet the error: %s";
  116.           //Get the list of services to call
  117.           List<AuthorizationMatrix.Services.Service> services = AUTHZ_MATRIX.getServices().getService();
  119.           //Get the list of services test payload to use
  120.           List<AuthorizationMatrix.ServicesTesting.Service> servicesTestPayload = AUTHZ_MATRIX.getServicesTesting().getService();
  122.           //Call all services sequentially (no special focus on performance here)
  123.           services.forEach(service -> {
  124.               //Get the service test payload for the current service
  125.               String payload = null;
  126.               String payloadContentType = null;
  127.               Optional<AuthorizationMatrix.ServicesTesting.Service> serviceTesting = servicesTestPayload.stream().filter(srvPld -> srvPld.getName().equals(service.getName())).findFirst();
  128.               if (serviceTesting.isPresent()) {
  129.                   payload = serviceTesting.get().getPayload().getValue();
  130.                   payloadContentType = serviceTesting.get().getPayload().getContentType();
  131.               }
  132.               //Call the service and verify if the response is consistent
  133.               try {
  134.                   //Call the service
  135.                   int serviceResponseCode = callService(service.getUri(), payload, payloadContentType, service.getHttpMethod(), accessToken);
  136.                   //Check if the role represented by the specified point of view is defined for the current service
  137.                   Optional<AuthorizationMatrix.Services.Service.Role> role = service.getRole().stream().filter(r -> r.getName().equals(pointOfView.name())).findFirst();
  138.                   boolean accessIsGrantedInAuthorizationMatrix = role.isPresent();
  139.                   //Verify behavior consistency according to the response code returned and the authorization configured in the matrix
  140.                   if (serviceResponseCode == service.getHttpResponseCodeForAccessAllowed()) {
  141.                       //Roles is not in the list of role allowed to access to the service so it's an error
  142.                       if (!accessIsGrantedInAuthorizationMatrix) {
  143.                           errors.add(String.format(errorMessageTplForIncorrectReturnCode, service.getName(), pointOfView.name(), serviceResponseCode,
  144.                            service.getHttpResponseCodeForAccessDenied()));
  145.                       }
  146.                   } else if (serviceResponseCode == service.getHttpResponseCodeForAccessDenied()) {
  147.                       //Roles is in the list of role allowed to access to the service so it's an error
  148.                       if (accessIsGrantedInAuthorizationMatrix) {
  149.                           errors.add(String.format(errorMessageTplForIncorrectReturnCode, service.getName(), pointOfView.name(), serviceResponseCode,
  150.                            service.getHttpResponseCodeForAccessAllowed()));
  151.                       }
  152.                   } else {
  153.                       errors.add(String.format(errorMessageTplForUnexpectedReturnCode, service.getName(), pointOfView.name(), serviceResponseCode));
  154.                   }
  155.               } catch (Exception e) {
  156.                   errors.add(String.format(fatalErrorMessageTpl, service.getName(), pointOfView.name(), e.getMessage()));
  157.               }
  160.           });
  162.           return errors;
  163.       }
  165.       /**
  166.        * Call a service with a specific payload and return the HTTP response code received.
  167.        * Delegate this step in order to made the test cases more easy to maintain.
  168.        *
  169.        * @param uri                URI of the target service
  170.        * @param payloadContentType Content type of the payload to send
  171.        * @param payload            Payload to send
  172.        * @param httpMethod         HTTP method to use
  173.        * @param accessToken        Access token to specify to represent the identity of the caller
  174.        * @return The HTTP response code received
  175.        * @throws Exception If any error occurs
  176.        */
  177.       private int callService(String uri, String payload, String payloadContentType, String httpMethod, String accessToken) throws Exception {
  178.           int rc;
  180.           //Build the request - Use Apache HTTP Client in order to be more flexible in the combination
  181.           HttpRequestBase request;
  182.           String url = (BASE_URL + uri).replaceAll("\\{messageId\\}", "1");
  183.           switch (httpMethod) {
  184.               case "GET":
  185.                   request = new HttpGet(url);
  186.                   break;
  187.               case "DELETE":
  188.                   request = new HttpDelete(url);
  189.                   break;
  190.               case "PUT":
  191.                   request = new HttpPut(url);
  192.                   if (payload != null) {
  193.                       request.setHeader("Content-Type", payloadContentType);
  194.                       ((HttpPut) request).setEntity(new StringEntity(payload.trim()));
  195.                   }
  196.                   break;
  197.               default:
  198.                   throw new UnsupportedOperationException(httpMethod + " not supported !");
  199.           }
  200.           request.setHeader("Authorization", (accessToken != null) ? accessToken : "");
  203.           //Send the request and get the HTTP response code
  204.           try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
  205.               try (CloseableHttpResponse httpResponse = httpClient.execute(request)) {
  206.                   //Don't care here about the response content...
  207.                   rc = httpResponse.getStatusLine().getStatusCode();
  208.               }
  209.           }
  211.           return rc;
  212.       }
  214.       /**
  215.        * Generate a JWT token the user and role specified.
  216.        *
  217.        * @param login User login
  218.        * @param role  Authorization logical role
  219.        * @return The JWT token
  220.        * @throws Exception If any error occurs during the creation
  221.        */
  222.       private String generateTestCaseAccessToken(String login, SecurityRole role) throws Exception {
  223.           return new AuthService().issueAccessToken(login, role);
  224.       }
  227.       /**
  228.        * Format a list of errors to a printable string
  229.        *
  230.        * @param errors Error list
  231.        * @return Printable string
  232.        */
  233.       private String formatErrorsList(List<String> errors) {
  234.           StringBuilder buffer = new StringBuilder();
  235.           errors.forEach(e -> buffer.append(e).append("\n"));
  236.           return buffer.toString();
  237.       }
  238.   }

In case of detection of a authorization issue(s) the output is the following:

  1. testAccessUsingAnonymousUserPointOfView(org.owasp.pocauthztesting.AuthorizationMatrixIT)  
  2. Time elapsed: 1.009 s  ### FAILURE
  3. java.lang.AssertionError:
  4. Access issues detected using the ANONYMOUS USER point of view:
  5.     The service 'DeleteMessage' when called with POV 'ANONYMOUS' return 
  6.     a response code 200 that is not the expected one (403 expected).
  8.     The service 'CreateMessage' when called with POV 'ANONYMOUS' return 
  9.     a response code 200 that is not the expected one (403 expected).
  11. testAccessUsingBasicUserPointOfView(org.owasp.pocauthztesting.AuthorizationMatrixIT)  
  12. Time elapsed: 0.05 s  ### FAILURE!
  13. java.lang.AssertionError:
  14. Access issues detected using the BASIC USER point of view:
  15.     The service 'DeleteMessage' when called with POV 'BASIC' return 
  16.     a response code 200 that is not the expected one (403 expected).

Rendering of the authorization matrix for audit / review

Even if the authorization matrix is stored in a human readable format (XML), it can be interesting to provide an on-the-fly rendering representation of the XML file in order to facilitate the review, audit and discussion about the authorization matrix in order to spot potential inconsistencies.

The Following XSL stylesheet can be used:

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  3.   <xsl:template match="/">
  4.     <html>
  5.       <head>
  6.         <title>Authorization Matrix</title>
  7.         <link rel="stylesheet" 
  8.         href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.6/css/bootstrap.min.css" 
  9.         integrity="sha384-rwoIResjU2yc3z8GV/NPeZWAv56rSmLldC3R/AZzGRnGxQQKnKkoFVhFQhNUwEyJ" 
  10.         crossorigin="anonymous" />
  11.       </head>
  12.       <body>
  13.         <h3>Roles</h3>
  14.         <ul>
  15.           <xsl:for-each select="authorization-matrix/roles/role">
  16.             <xsl:choose>
  17.               <xsl:when test="@name = 'ADMIN'">
  18.                 <div class="alert alert-warning" role="alert">
  19.                   <strong>
  20.                     <xsl:value-of select="@name" />
  21.                   </strong>
  22.                   :
  23.                   <xsl:value-of select="@description" />
  24.                 </div>
  25.               </xsl:when>
  26.               <xsl:when test="@name = 'BASIC'">
  27.                 <div class="alert alert-info" role="alert">
  28.                   <strong>
  29.                     <xsl:value-of select="@name" />
  30.                   </strong>
  31.                   :
  32.                   <xsl:value-of select="@description" />
  33.                 </div>
  34.               </xsl:when>
  35.               <xsl:otherwise>
  36.                 <div class="alert alert-danger" role="alert">
  37.                   <strong>
  38.                     <xsl:value-of select="@name" />
  39.                   </strong>
  40.                   :
  41.                   <xsl:value-of select="@description" />
  42.                 </div>
  43.               </xsl:otherwise>
  44.             </xsl:choose>
  45.           </xsl:for-each>
  46.         </ul>
  47.         <h3>Authorizations</h3>
  48.         <table class="table table-hover table-sm">
  49.           <thead class="thead-inverse">
  50.             <tr>
  51.               <th>Service</th>
  52.               <th>URI</th>
  53.               <th>Method</th>
  54.               <th>Role</th>
  55.             </tr>
  56.           </thead>
  57.           <tbody>
  58.             <xsl:for-each select="authorization-matrix/services/service">
  59.               <xsl:variable name="service-name" select="@name" />
  60.               <xsl:variable name="service-uri" select="@uri" />
  61.               <xsl:variable name="service-method" select="@http-method" />
  62.               <xsl:for-each select="role">
  63.                 <tr>
  64.                   <td scope="row">
  65.                     <xsl:value-of select="$service-name" />
  66.                   </td>
  67.                   <td>
  68.                     <xsl:value-of select="$service-uri" />
  69.                   </td>
  70.                   <td>
  71.                     <xsl:value-of select="$service-method" />
  72.                   </td>
  73.                   <td>
  74.                     <xsl:variable name="service-role-name" select="@name" />
  75.                     <xsl:choose>
  76.                       <xsl:when test="@name = 'ADMIN'">
  77.                         <div class="alert alert-warning" role="alert">
  78.                           <xsl:value-of select="@name" />
  79.                         </div>
  80.                       </xsl:when>
  81.                       <xsl:when test="@name = 'BASIC'">
  82.                         <div class="alert alert-info" role="alert">
  83.                           <xsl:value-of select="@name" />
  84.                         </div>
  85.                       </xsl:when>
  86.                       <xsl:otherwise>
  87.                         <div class="alert alert-danger" role="alert">
  88.                           <xsl:value-of select="@name" />
  89.                         </div>
  90.                       </xsl:otherwise>
  91.                     </xsl:choose>
  92.                   </td>
  93.                 </tr>
  94.               </xsl:for-each>
  95.             </xsl:for-each>
  96.           </tbody>
  97.         </table>
  98.       </body>
  99.     </html>
  100.   </xsl:template>
  101. </xsl:stylesheet>

Example of the rendering:

RenderingExample

Sources of the prototype

Github repository