Using XACML Policies as OAuth Scope Hal Lockhart Oracle I have been exploring the possibility of expressing the Scope of an OAuth Access Token by using XACML policies. In this document I will first describe the requirements for an OAuth Access Token Scope, next I will describe some alternative approaches to expressing the Scope and the thought process that led me to this proposal, then I will describe the actual processing steps to generate the Scope, with some examples, following that I will discuss the benefits of this approach and finally I will list the new work required to implement this approach along with some areas which merit further study. Authorization Token Requirements The OAuth Authorization Framework [RFC 6749] permits many different message flows. In general, the initial set of message exchanges result in the issuance to the Client of an Access Grant. This may be in a number of different forms, but generally represents the Identity or Authority of the Resource Owner who is granting access rights. This Grant is presented to the Authorization Server Based on the grant (and its own policies) the Authorization Server issues an Access Token to the Client which presents it to the Resource Server in an Application request. An Access Token can take one of two general forms. It can be a handle or artifact; alternatively it can be an Assertion or self-contained token. A handle is compact reference to some internal information held by the Authorization Server. The Resource Server processes it by querying the Authorization Server for the referenced information. The format of the handle, the referenced information and the query protocol are intended to be proprietary, i.e. not standardized. A self-contained token as the name implies, can be interpreted by the Resource Server without consulting the Authorization Server. Along with the Access Token the Authorization Server provides a parameter called Scope. Actually OAuth uses the term Scope in two different ways, in an Access Token Request (or in the case of Implicit Grant Authorization Request) and in an Access Token Response. These strictly speaking should be called the Requested Scope and the Issued Scope. OAuth implies that they are in the same format (It says that they are space-delimited strings and that if there are multiple strings their order does not matter, and each string adds an additional access range to the requested scope. ) 1. As we will see later there are good reasons why we might want to use different formats for Requested Scope and Issued Scope. If Issued Scope is standardized it should have agreed upon syntax and semantics indicating what the Resource Server should allow the client to do. It should be general enough to cover all kinds of resources and forms of usage. Resource Servers should be able to use it to determine of a given requested access falls within the scope. There should be a well defined procedure for the Authorization Server to 1
determine what scope to issue given the identity of the Resource Owner and the Client. Interpreting the Scope should not require information which is not usually available to the Resource Server, such as the Attributes of the Resource Owner. Designing a Format for Issued Scope When the Issued Scope is a handle to something like a session within the Authorization Server, there is no need for anything else to be known outside of the Authorization Server. The Resource Server just gives the value to the Authorization Server via a proprietary interface and finds out what to do. The downside is that the Authorization Server ends up being closely coupled to the Resource Server, both in the sense of interdependent design and of being a potential performance bottleneck. It also means the Authorization Server must manage this information, persisting and garbage collecting it as needed. Therefore it is attractive to define some form of self-contained Access Token, limited by Issued Scope. The simplest scheme for expressing Issued Scope is to come up with a small number of access patterns and associate a symbol with each. For example, suppose we are giving a friend some access to our files on a Cloud-based server. The options (defined by the Cloud provider for this site) might be Reader, Editor or Admin. The Resource Server will know what combination of actual actions on specific resources is allowed for each. For example, Readers are allowed to read all files, Editors are allowed to read all files and edit documents, and Admins are allowed to read and write everything including configuration files. This scheme corresponds to Roles in an RBAC model, although of course we could just as well use 1,2,3 instead of Reader, Editor & Admin. It is my understanding that this kind of approach is widely used in OAuth deployments today. To see the limitations of this approach, suppose I want to make my mom a Reader but I don t want her to read the poetry my girlfriend wrote me. Or perhaps I want someone to be the editor of only documents in a certain project. The only solution is to define some new roles. This means we must update all the Authorization Servers and Resource Servers. This may be a particular problem if they are operated by different organizations. Further, as Roles multiply, it will get harder and harder to remember what each allows. This problem of exploding numbers of Roles has already been seen in large organizations using an RBAC approach in non-oauth systems. Further, if the resource owner is expected to explicitly pick the Role (or Roles in a cumulative model) the changes will ripple up to the UI and the human user. (Negative user feedback on changes to the Facebook access control model have been well publicized.) Finally, some of the OAuth protocol flows have subtle interactions between the message exchanges, credentials presented and redirects on the one hand and the contents of the Access Token 2 on the other. It is possible that a change to the model for expressing Scope could change the security properties of the entire OAuth handshake in certain pathological cases. Instead of Roles, suppose we try to express what is allowed directly. For example, the user wants to read file X, we put r-x in the Issued Scope. The obvious problem with this is that if we want to do something else, say write file Y, we will have to repeat all or part of the OAuth handshake and obtain another Access Token. This will result in an excessive number of message exchanges. Additionally, either the 2
Resource Server will have to allow us to present a whole bunch of tokens at one time and sift through them to find the one that applies to the current request or the client will have to keep track of which token allows what. What we need is a notation which is more flexible. We need something that says we can do these things to these resources and these other things to these other resources. We also may wish to put other constraints on the access, such as time of day, day or week, network location, etc. We need to be able to cover multiple resources in a single expression, such as all the files under /user/hal or all the files with the public value of the classification attribute. This all sounds just like an XACML policy 3. Instead of inventing some new syntax and defining rules for matching requests against it we can easily construct a policy which expresses all these kinds of things and use it as the Issued Scope. Any XACML PDP can tell us if the access is allowed under that policy. However, obviously we cannot write the policies by hand to cover every case. If we were to devise a scheme to pick one of several canned policies to be used in different cases, we have essentially devolved to the RBAC scheme I just described, except for making it more complicated by introducing XACML. The good news is we can use an XACML PDP to select the policies for us. Normally we call the PDP, providing Attribute values and it tells us if the access is permitted or not. In XACML 3.0 a feature was added which allows the PEP to optionally request the Identifiers of the policies that were applicable to the decision. We can then obtain these policies from the policy repository and use them as the Issued Scope. (The XACML TC has plans to create a JSON representation of policies as an alternative to the current XML representation.) The Resource Server can plug the policies from the Issued Scope into its own XACML PDP to determine if the request is within the specified scope. We can make this work without the use of the XACML 3.0 Admin/Delegation Profile, by treating the Resource Owner as the subject, since the User Managed Access model says that a Resource Owner can delegate whatever he can do. (With some other tricks, we can reduce the Issued Scope to less than what the Resource Owner can do if that is what we want.) The basic technique is to provide an XACML Decision Request in the OAuth Requested Scope. The Resource Identifier should be one of the Resources that the Client intends to access. The XACML PDP associated with the Authorization Server evaluates its policies and if the request is allowed, returns Permit and the list of applicable policies. A more sophisticated version of this can utilize the Admin/Delegation Profile to arbitrarily control what the Resource Owner can delegate, which might be less or more than he himself can do directly. I have not worked out all the details of this case, but there seems to be a good alignment between OAuth and XACML 3.0 delegation. Decapitated Policies But not so fast, I hear you saying. The Resource Server typically has no knowledge of the Attributes of the Resource Owner (Access Subject in XACML terminology). How is it going to evaluate the policies it receives in the Issued Scope? The answer is, we make a pass through the policies and wherever an Attribute in the category Access Subject appears, we take the value of the Attribute and substitute it as a constant into the policy in 3
place of the reference to the Attribute value. I call this process decapitation. The result is a decapitated policy. Strictly speaking that is all we have to do. However, to improve efficiency of evaluation and reduce the size of the policies in the Access Token, we can perform a simple optimization to remove any constant terms in the policies. A couple of examples will show what I mean. Suppose the policy (in English for clarity) is: If Subject Attribute Group equals user and Resource Attribute Class equals private permit access. Since we have checked that the Resource Owner has the proper Subject Attribute and the UMA model says that she can delegate to a Client whatever she can do, we can plug in user as the value of the Subject Attribute called Group. This makes the policy: If user equals user and Resource Attribute Class equals private permit access. A simple optimization reduces this to: If Resource Attribute Class equals private permit access. Here is a slightly more complicated example. If Subject Attribute Group equals user and Resource Attribute Name matches Regex( /user/ +Subject Attribute Username+ /* ) permit access. The intent here is that the file must be located in the directory tree belonging to the Resource Owner. A Regular Expression is used to match the name of the file against the directory name. Assuming the Resource Owner s Username is hal this becomes: If user equals user and Resource Attribute Name matches Regex( /user/ + hal + /* ) permit access. This optimizes to: If Resource Attribute Name matches Regex( /user/ + hal + /* ) permit access. Or even to: If user equals user and Resource Attribute Name matches Regex( /user/hal/* ) permit access. The technique of using decapitated policies to express Issued Scope can be looked at in more than one way. The way I like to think about it is that it reveals that the fundamental process of access control using OAuth evaluates attributes to determine if access should be allowed, just as the classic PEP-PDP 4
model does. The difference is that the Subject processing has been separated in time and space from the processing of other Attributes such as Resource or Action. (We have to use the full policy initially, since we need to know if the Resource Owner can do something in particular.) This allows a party (Resource Server) to evaluate the decapitated policies without any knowledge of the Subject because it trusts the Authorization Server to have done the Subject checks previously. Benefits of this Approach I believe this approach has the following benefits. Provides a general, flexible way of expressing Issued Scope suitable to any problem domain. Provides a simple way of generating the policies as a function of what the Client is trying to do. Gives a means to express policies for OAuth which is the same as for resources protected by the classic model. Enables the use of XACML Delegation for full generality. Even major revisions of a particular AS/RS access model only require a change to policies. Next Steps Most of the pieces of this solution already exist. For example there are a number of Open Source XACML PDPs supporting XACML 2.0 or 3.0, in addition to a number of good commercial products. Other than actually coding a solution which sends and receives the OAuth messages the following things need to be done. The XACML TC needs to increase the priority of specifying policies in JSON. The API to retrieve policies by Identifier has never been standardized, but most implementations have it in some form. To be useful as described here, we probably need an imbedded PDP with in memory policy store. Therefore it makes sense to define this as a programming API not a network request. This can easily be done in the OpenAz Project. I suspect the main issue will be capping the functionality. The decapitation algorithm needs to be specified formally and in detail, including variations (if any) required to support distinct OAuth usecases and message flows. Currently XACML PDPs do not support the input of policies with decision requests except in the context of the Admin/Delegation Profile. This will need to be relaxed. Future Topics I believe the following subjects merit further study. How Obligations fit into this proposal. 5
How other XACML Subject Categories relate to this scheme. How to make use of the Admin/Delegation Profile in the context of OAuth. What if any role the XACML 3.0 access-permitted function might play with OAuth. 1 The meaning of Scope is not actually defined by OAuth 2.0 except by the circular statement that it defines the scope of the access request. However everyone understands that Scope indicates what the client is allowed to do. 2 It is necessary to be careful about the use of the term Access Token. RFC 6740 uses it in more than one way. For example, in section 5.1, access token clearly means the required first parameter of the entity-body of the Access Token Response, which also may include type, expires, refresh token and scope. Whereas in section 7, the term access token clearly refers to all the parameters in the entity-body of the Access Token Response. In section 1.4 it is difficult to determine which meaning is intended, since it says that it is usually opaque to the client which clearly is not true of expires, but in the same breath talks about tokens representing specific scopes. In this document I use Access Token to refer to all the parameters collectively, including scope. 3 Ignoring many important details, an XACML policy is a series of logical expressions which use attributes (including names) of the subject, resource, action and environment associated with an access request. If an expression is false it does not apply. If it is true, the Effect (e.g. Permit) of the policy is asserted. If there are conflicting Effects, a rule like Default Deny is used to resolve the conflict. The important thing to understand is that given some set of information, static or dynamic, the XACML PDP will decide to Permit or Deny the access request. 6