A people that values its privileges above its principles soon loses both.
—Dwight D. Eisenhower, 34th president of the United States, from first inaugural address
The previous chapters covered the mechanics of authorizing an API call and authenticating a user. This chapter will discuss authorization vs. the enforcement of access policy and how identity protocols can be used to help implement them.
Authorization vs. Policy Enforcement
In governing what a user or application can do, there are two distinct functions. We use the term authorization for the granting of privileges. In contrast, access policy enforcement is defined as the act of checking that someone has been granted the necessary privilege before responding to a request for a protected resource. For example, if you buy a theater ticket, the ticket constitutes your authorization to attend the performance. On the night of the performance, the ticket taker at the door enforces policy by checking to ensure that only authorized patrons (with tickets) enter the theater.
Authorization may be granted well in advance of a resource being requested or at the time of requesting access. It may be done by the entity containing the requested resource or by a trusted third party with the authorization information conveyed securely to the policy enforcement point. Access policy enforcement is done at the time a resource request is made and ideally at an enforcement point within or close to the protected resource to reduce the possibility of it being bypassed.
Levels of Authorization and Access Policy Enforcement
Level 1 – Whether an entity can access an application or API at all
Level 2 – What functions an entity can use in an application or API
Level 3 – What data an entity can access or operate on
Level 1 – Application or API Access
Application-Level Access Policy Enforcement
Level 2 – Functional Access
Functional -level authorization and access policy enforcement govern what an entity can do within an application or API. For example, a junior accounting clerk in the finance department might be able to access the corporate accounting system and enter individual journal entries but not perform a month-end close. This level of authorization and access policy enforcement tends to be application specific. It may leverage information about a user stored elsewhere, such as roles or groups in a directory service, but is often enforced within an application or API.
Level 3 – Data Access
A third level of authorization and access policy enforcement governs access to particular subsets of data. If functional-level access policy enforcement defines the functions an entity can do, data-level access policy further restricts access to specific data. For example, in a sales order entry application, a user with the role “regional sales manager” may be authorized at a functional level to view sales orders, but data-level access policy restricts them to a specific region indicated in their user profile’s “Sales region” attribute. Data-level access may be enforced within an application or API or in an underlying storage layer.
User vs. Application Authorization
We will cover two situations that require authorization and access policy enforcement. The first governs what a user (or entity) can do in an application, and the second controls what an application can request of an API.
A user needs authorization to perform various functions within an application. The application may render the application’s user interface based on a user’s authorized privileges so it doesn’t display features a user cannot use. In addition, when a user makes a request, the application back end or API must check that the user has the necessary authorization for the request before executing it.
An application requires authorization to call a protected API. If the content at the API is owned by the user of the application, the access requires the user’s authorization. This scenario is often found in consumer-facing applications. If the content at the API is accessed by the application on its own behalf, an authorization server grants the authorization to the application based on permissions previously configured by the administrator of the authorization server.
Authorization and the specification of access policy.
Delivery of authorization information to enforcement point (if needed)
Enforcement of the access policy by the enforcement point
We will discuss these three steps first for users and then applications.
User Authorization
The specification of authorization is a complex topic. So many schemes have been invented for this over the years that covering them is outside the scope of this book. We will assume that access policy is represented in a set of attributes associated with a user or application and describe how OIDC and SAML 2.0 can be used to deliver authorization information about a user to an application and how OAuth 2.0 can be used to authorize access to APIs and how this supports access policy enforcement. The attributes used to convey authorization for users can vary, but the most common fall into two categories.
User Profile Attributes
A user’s identity may be granted authorization based on roles which they’ve been assigned in a role-based access control (RBAC)i model, membership in a group or access control list (ACL), or individual user profile attributes evaluated by rules as part of an attribute-based access control (ABAC)ii, iii model. These attributes are relatively static factors that remain the same, regardless of where the user is or what device they are using at the time of accessing a protected resource.
If such authorization information is specified outside an application, such as in a corporate directory service or policy service, but accessible by the identity provider authenticating a user, these attributes can be delivered to the application by the identity provider. If authorization is specified in the application, the identity provider can deliver an identifier for the authenticated user to the application so it can retrieve the necessary authorization information about the user.
The authorization step to grant a user privileges is typically done in advance of the user making a request in an application. For example, if a new employee joins a company’s finance team, the business may authorize the employee to access its accounting application by assigning the user roles in a corporate identity system on the new hire’s first day. For a consumer-facing application, a user may be assigned access-related user profile attributes when they purchase a particular subscription level for the service.
Transactional User Attributes
Authorization may also be based upon factors that are part of the user’s physical environment at the time of authentication or accessing a protected resource. Such factors can include the user’s geographic location, whether the user is inside or outside a corporate firewall, or whether the user’s device is certified as adhering to certain security configuration standards. The day of the week or time of day may be factors as well as the strength of authentication mechanism used. These factors are captured at the time of authentication rather than being part of the user’s profile. Such factors, if captured by an identity provider, can also be provided to applications in the form of claims in a security token.
Delivery
Delivering Authorization Attributes to an Application
- 1.
User redirected to login at the OIDC OpenID Provider.
- 2.
The ID Token includes the user’s purchased subscription.
- 3.
Subscription data in ID Token is used to determine the list of movies displayed.
- 4.
User selects a movie to view.
- 5.
Application back end checks the user has required subscription level for their selected movie.
In the example, the information in the ID Token about a user’s subscription level is used to display to the user the movies they are entitled to rent. It is also used to perform access policy enforcement. Even though the front end restricted the list of movies to what the user can view, a malicious user might find a way to get around this, so the access policy enforcement check is made in the application back end where it cannot be circumvented. This example uses OIDC, but applications using SAML 2.0 can follow a similar model, obtaining authorization data from the SAML 2.0 assertion.
Enforcement
Validate the ID Token is a correctly formatted JWT (JSON Web Token)
Validate the signature on the ID Token
Check that the token has not expired
Check the issuer is the correct OpenID Provider
Check the intended audience for the token is the application
Be sure to check the documentation for your OpenID Provider for the exact validation steps required for their implementation. Once the ID Token has been validated, the application can use the claims within the token for access policy enforcement.
Application Authorization
The second case of authorization and policy enforcement is that of applications calling APIs.
Application Attributes
Application requests to call APIs on a user’s behalf are authorized by the user, but requests to call APIs on their own behalf are authorized by an authorization server based on configured policy. This policy is typically configured in advance of an application calling an API. Unless the number of applications or APIs is quite large, the policy specification is often expressed by indicating the specific applications authorized to call specific APIs and which endpoints and actions can be accessed. If OAuth 2.0 is used, the policy may be specified in terms of scopes, such as “get:documents”.
Authorization
An application that makes an OAuth 2.0 request for authorization to call an API specifies its requested scopes as a parameter to the authorization request. For example, an application requesting an access token for an OpenID provider’s UserInfo Endpoint to retrieve user attributes might use “scope = openid profile email”. An application calling a custom API to retrieve a user’s documents might request a scope of “get:documents”.
With the authorization code and implicit grant types, the requested API resources are owned by the user, so the OAuth 2.0 authorization server will prompt the user, displaying the requested scopes, and obtain the user’s consent for the application’s request before issuing an access token. With the client credentials grant, the requested API resources are owned by the application, and the privileges granted to each application are specified in the authorization server (or a policy server accessed from it), and it will use that information to decide whether a request is allowed before issuing an access token.
Delivery
Regardless of whether the protected resource is owned by the user or the application, if the request is authorized, the authorization server will issue an access token to the application for the requested API. An authorization server may allow adding additional custom claims to an access token, such as claims about the user, including data on privileges such as roles. Additional claims may be useful to an API in enforcing access. Support for extensibility via custom claims and attributes about users may vary by individual authorization server implementations.
Enforcement
An API must validate an access token and perform access policy enforcement to make sure the application’s request is permitted before responding. The steps to validate and obtain information about an access token will vary depending on the authorization server’s implementation for access tokens. You should check the authorization server documentation for details about how to validate any tokens it issues. Once the access token has been validated, the API can use the information in the token, including any custom claims if allowed, to perform its access policy enforcement before responding to the request.
Summary
Authorization involves the granting of privileges, whereas access policy enforcement is a check done at the time a resource is requested, to validate the requestor has been granted the requisite privileges for the request. Authorization and access policy enforcement may be used to govern what a user can do in an application as well as whether an application can make a request to an API. User authorization may be based on static factors in a user’s profile and/or dynamic factors evaluated at the time of authentication, both of which can be delivered to an application in a security token. Application authorization may be based on scopes approved by a user or an authorization server and manifested in an access token delivered to an application and used to call an API. In the next chapter, we’ll discuss a sample application and how it uses OIDC and OAuth 2.0 together for authorizing access to APIs.
Key Points
Authorization is the granting of privileges to access protected resources.
Access policy enforcement is done when a request is made and checks if a requestor has been granted sufficient authorization for the request.
Authorization and access policy enforcement apply to users as well as applications calling APIs.
Authorization policy for users may be based upon user profile attributes or dynamic factors evaluated at the time a user authenticates or makes a request.
Authorization for applications to call APIs is granted by users or authorization servers depending on the OAuth 2.0 grant type used.
Authorization and access policy enforcement can be specified on multiple levels.
Claims in security tokens can be used as a basis for access policy enforcement decisions in applications and APIs.