Understanding Authorization Methods

Authorization, which follows authentication, provides granular access control to API requests based on verified identity. This ensures only authorized entities with appropriate permissions interact with your API resources. Understanding authorization methods and their strengths is essential for effectively securing your environment's headless APIs.

There are three primary methods available to authorize Liferay headless API requests:

As Clarity's environments leverage Liferay SaaS (which requires all authorization requests to communicate via security authorization tokens), they'll use OAuth 2.0 as their authorization approach.

Understanding Authorization with OAuth 2.0

OAuth 2.0 is a powerful framework enabling access limitations without requiring direct credential sharing. It secures your API endpoints by authorizing applications through defined permission scopes. This makes it ideal for scenarios where third-party applications grant resource access on behalf of a user. OAuth 2.0 authorization follows this flow:

• Request Authorization: The application requests access with its client ID and desired permissions.
• Users Grant Permission: Users grant permission implicitly or explicitly, authorizing the application to access specific resources on their behalf.
• Authorization Grant Issued: The authorization server issues a temporary grant code to be exchanged for an access token.
• Access Token Requested: The application sends the temporary grant to the authorization server, along with its client ID and a confidential client secret known only to the application and the authorization server.
• Resource Access Granted: The authorization server validates credentials and issues an access token to the application.

This access token enables the client application to make future API calls, with limited resource access granted to the scoped permissions.

OAuth 2.0's standardized, delegated access control makes it the preferred method for authorizing third-party applications to access your APIs. It provides a secure and flexible way to define different scopes for your endpoints and control access to your API resources.

Understanding Basic and Cookie/Session Authorization

Though less secure than OAuth 2.0, basic authorization and cookie/session authorization can all secure APIs.

• Basic Authorization: The simplest authorization protocol, user credentials are sent to the server as an encoded user name and password. This is the least secure authentication protocol, as it typically provides all-or-nothing access, credentials are stored in Base64 (which risks decoding if intercepted), and it is not appropriate for scenarios where third-party applications need to access your API.
• Cookie/Session Authentication: Primarily designed for browser-based clients, this available protocol makes direct requests to APIs by passing the session identifier (the cookie reference) and the Liferay Auth Token. It's not suitable for mobile apps and other clients that don't have built-in cookie management, and requires careful adherence to security best practices regarding CSRF protection and secure cookie attributes.

When to Leverage Basic Authentication

Due to its security limitations, basic authentication for securing APIs is generally discouraged within production scenarios. There are limited situations where it could be considered:

• Testing and Development: Simple to implement, basic authentication enables quick headless API testing and development with headless APIs without the overhead of more complex authentication methods.
• Controlled Environments: For APIs only accessible within highly controlled internal networks, where communication is also strictly over HTTPS, basic authentication could be considered. Even under these circumstances, better alternatives usually exist.
• Non-Critical APIs: Basic authentication is potentially acceptable for very simple APIs that don't handle sensitive data and are always accessed over HTTPS. This is rare, as most APIs handle at least some level of sensitive information.

When to Leverage Cookie/Session Authentication

Cookie/session authentication for consuming APIs is primarily relevant when the client consuming the API is a traditional web browser. Situations where cookie/session authentication can be considered include:

• Browser-Based Frontends: For client applications running in a user's browser, cookie/session authentication can simplify user session maintenance. Since the browser automatically handles cookie storage and transmission, your JavaScript code wouldn't need to explicitly manage tokens in API requests.
• Server-Side Rendering (SSR) Applications: In SSR applications, the server renders HTML for the client. If rendered HTML requires API interaction and sessions are managed via cookies, cookie/session authentication can authenticate server-side requests on behalf of users.
• Existing Web Applications: For existing web applications that already leverage cookie/session authentication, it may be easier to maintain consistency by using the same authentication mechanism for added APIs.

For example, this method may be useful if you are building a React-based portlet that makes requests to Liferay's headless APIs.

Selecting Authorization Methods

While simpler to initially implement, both basic and cookie/session authorization protocols have notable drawbacks. Basic authentication should generally only be used for testing and development. Cookie/session authentication is mainly appropriate when consuming REST APIs within traditional web browsers. However, it's more challenging to adhere to the stateless principles of REST APIs when maintaining sessions through cookies, which can impact scalability and introduce complexities in distributed environments.

Authorizing with OAuth 2.0 provides far more flexibility and security, and should be your default authorization method for securing headless APIs. OAuth 2.0 enhances API security by utilizing time-limited, permission-scoped access tokens instead of hard-coded user credentials, enabling fine-grained control and easy token revocation. This minimizes the risk of credential compromise and ensures secure access across diverse applications.

Clarity's API Authorization

Clarity restricts all but a few custom web service methods for public access. This ensures some of their external systems are free to extract non-sensitive data, such as ticket sub-categories, without requiring complex security requirements. As they are building their platform on Liferay SaaS, all non-public access authorization requests will be transported through HTTPS and use OAuth 2.0 authorization tokens.

Conclusion

Authorization is critical for securing APIs to protect sensitive data, uphold data privacy, prevent resource misuse, and meet compliance requirements through controlled access. Selecting authorization methods requires considerations about the complexity of your application and the level of security required. OAuth 2.0 is the preferred choice for securing APIs in modern web applications such as Liferay, offering enhanced security, fine-grained access control, and greater flexibility.

Once Clarity has registered an OAuth 2.0 application, they can continue layering security by authorizing specific users. Next, you'll learn about common OAuth flows supported by Liferay.