API Security Part 2 - Consent Vs Authorization

In part 1 I wrote about how to go about choosing the format of the tokens, a little bit about contents of the token and how to obtain tokens. In this article I will delve a more in to OAuth 2.0 and its terminologies

OAuth is a sort of “protocol of protocols” or “meta protocol,” meaning that it provides a useful starting point for other protocols (e.g., OpenID Connect, User Managed Access[UMA]). The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

OAuth is a scalable delegation protocol. The main thing you need to know is that OAuth 2.0 provides a way for apps to gain limited access to a user's protected resources (think of bank account or any other sensitive information a user might wish to access from an app) without the need for the user to divulge their login credentials to the app. OAuth was designed to ask the permission (consent) from the users who owns the data, whether they want it provide access to applications to access their data.

Beginning with OAuth is important because it solves several important needs that most API providers have, including:

• Delegated access
• Reduction of password sharing between users and third parties (the so-called password "anti-pattern")
• Revocation of access

Actors in OAuth2

Client -- Also called "the app". It can be an app running on a mobile device or a traditional web app or the developer portal. The app makes requests to the resource server for protected assets on behalf of the resource owner. The resource owner must give the app permission to access the protected resources.

Resource owner (RO) -- Also called an "end user". This is generally the person (or other entity) who is capable of granting access to a protected resource. For example, if an app needs to use data from one of your social media sites, then you are the resource owner -- the only person who can grant the app access to your data

Resource server (RS)-- Think of the resource server as a service like Sentience Service, or Weather API proxy or Crime data proxy, or an HR service on your intranet, or a partner service on your B2B extranet. API runtime is a resource server whenever OAuth token validation is required to process API requests. The resource server needs authorization before it will serve up protected resources to the app

Authorization server (AS) -- The authorization server is implemented in compliance with the OAuth 2.0 specification, and it is responsible for validating authorization grants and issuing the access tokens that give the app access to the user's data on the resource server.

User Agent -- the agent used by the Resource Owner to interact with the Client, for example a browser or a native application.

So the most common example that everyone provides is that of the pictures stored by a user in some Cloud Storage like Instagram or picasa for a printing service. 

• Alice wants to print her Google Picasa photos using a third party online photo printing service.
• Alice protects her Google Picasa photo albums using a password.
• Alice does not want to share her password.
• Using OAuth, Alice will grant access to the third party printing service the ability to read her photo.

Here the user Alice has given consent to share her pictures with the printing service. This is a very simple use case which doesn't really have much business obligations. How can it not be for authorization, you may be wondering? The “authorization” of the client by the Resource Owner is really consent. This consent may be enough for the user, but not enough for the API. The API is the one that’s actually authorizing the request. It probably takes into account the rights granted to the client by the Resource Owner, but that consent, in and of its self, is not authorization. Lets get into a more real enterprise scenario

Lets see a real world example:

You formed a Resident Owners Association for your Residential Layout, which is responsible for managing the common amenities used by all the residents of the Layout. The residents form an managing committee for which you are appointed as the Treasurer and authorize you to operate the bank accounts on behalf of the committee. Actually what they are doing is they have given consent using their Discretionary Access Control to operate the Bank account.

But how will the Bank know that you are the new Treasurer? How will the bank honor your new Requests for doing the transactions on the Residential Owner Association account?

Here the Bank follows the Mandatory Access Control, where it asks the Association Managing Committee to submit an application stating that you have been appointed as the new Treasurer and be allowed to transact on the account on behalf of the association with all the committee members signatures. Once this application is processed, whenever you do a transaction, the bank will first check whether the transaction was initiated by you and then also check if you are authorized Treasurer for the association. Suppose, you moved out of the association and a new treasurer is appointed and the bank is not submitted a new application with the new Treasurer's name, then if he transacts on the association account, the bank will reject and not honor the transaction.

If we map the above entities with OAuth 2.0 Terms

• Residents Owners Association -- Resource Owner
• Managing Committee -- Authorization Server
• Bank [ where the association account its account] -- Resource Server
• Association Bank account -- Resource
• Treasurer -- Client

Let’s establish an example of an organization Example.com, that leverages multiple cloud benefits sites that are aggregated as part of its HR offering. NationalPensionScheme Benefits and ADPSaaS are two of the providers used by Example.com. Alice is an employee at Example.com and wishes to leverage these HR services. The benefits providers need her social security number (SSN) in order to evaluate whether the employee is eligible for certain government entitlements. The diagram below depicts and an API client from each provider. Note the PII (Personally Identifiable Information) label on the SSN field

Example.com exposes their employee data to these benefits providers via a SCIM (System for Cross-Domain Identity Management) interface. For those that glaze over looking at JSON, just read the bold print. The username (alice) is used as a key for retrieving attributes of the user. Metadata, including the PII tag, is returned in the response.

GET /Users/alice?attributes=social_security_number
Returns:
HTTP/1.1 200 OK
Content-Type: application/json
Location: https://..../v1/Users/alice
ETag: W/"a330fce5443561"
{
	"schemas" :["urn:scim:schemas:core:1.0"],
	"id":"alice",
	"scocial_security_number":"555-66-4321",
	"Meta":{
		"type":"pii",
		"created":"2016-08-01T1B:29:49.793Z",
		"lastModified":"2016-08-01T1B:29:49.793Z",
		"location":"https://..../v1/Users/alice",
		"version":"W\/\"a330fce5443561\""
	}
}

Example.com wants to give its employees the ability to opt-in or opt-out of letting benefits providers leverage certain HR attributes like Social Security Number. They have defined a set of scopes at the level of granularity of the APIs:

• view-social_security_number
• view-email
• view-name

If an employee opts-out of any of these scopes, Example.com shall not return those attribute values to the NationalPensionScheme benefits providers. Employees would be given the option on the NationalPensionScheme Benefits site on leg one of this three-legged, authorization code OAuth flow:

Once Alice approves of NationalPensionScheme of using her SSN, Example.com will issue an access token that acts as a key for the Resource Server to retrieve which scopes Alice has approved of and the Resource Server has the responsibility to enforce these scopes.

The provider may want to know what scopes are available, so that it can ask for specific scopes required for its application:

https://api.exampl.com/api/oauth/authorize?clientId=NationalPensionScheme&response_type=code&scope=view-scocial-security_number&redirect_uri=https%3A%2FNationalPensionScheme.com

Most OAuth implementations will allow all scopes to be requested by default (the absence of asking for any one or more specific scopes), but there may be a significant number of scopes that the provider may not want employees to have to wade through. For this reason, scope definition tends to be static and changing design on the fly is not realistic, as it would require coordination with all of the consumers of that service. It’s not a matter of how granular scopes can be be, it’s just that the lifecycle of change and the dependencies make it unrealistic.

The diagram below shows the relation of the scope approvals by the employee Alice with the API Client, the Resource Server and the service.

Allowing the employees to determine what access the API client may have is a Discretionary Access Control (DAC) model. The Wikipedia entry provides an excellent definition:

“The controls are discretionary in the sense that a subject with a certain access permission is capable of passing that permission (perhaps indirectly) on to any other subject (unless restrained by mandatory access control)”.

Let’s confirm that OAuth scopes fits the description of DAC. The first subject here, is the employee (Alice) who passing on the permission to view her profile attributes to NationalPensionSchemeBenefits (specifically, the API Client). 

That fits. Let’s understand the disclaimer at the end, though. The term Mandatory Access Control (MAC) is used, so let’s pull out a definition of MAC from Wikipedia:

“Any operation by any subject on any object is tested against the set of authorization rules (aka policy) to determine if the operation is allowed.”

These definitions provide rationale for complimenting an OAuth solution with Externalized Dynamic Authorization. Externalized Dynamic Authorization defines a MAC policy that may complement DAC or override or restrain DAC policies. MAC policies may be more top-down, and typically representing the interests of the stewards of the data. Let’s continue with Example.com having a MAC policy:

External benefits providers must have annual training in handling Example.com employee attributes that are labeled as Personally Identifiable Information (PII).

Even if Alice approves of her SSN being shared with NationalPensionSchemeBenefits, if the organization is not in good standing, it may be in Example.com’s interests not to share Alice’s PII with the provider. The MAC policy overrides the DAC policy.

The Resource Server essentially has two primary criteria for allowing the social security number to be returned to the client. You have the scope-based DAC policy (Did Alice approve of having her social security number shared with NationalPensionScheme) and the dynamic MAC policy (Does the NationalPensionScheme provider meet its training requirements to allow Example.com to share its employee’s PII?) The example above doesn’t use the scope as context in the authorization request to the Entitlement Store - Policy Decision Point (PDP). This is just a matter of design, where the Policy Enforcement Point might make to separate enforcements for these two concerns with different error handling.