Once you have an application registered, you can start authorizing users. To do that, you must construct the URL to the authorization server (Liferay DXP). The authorization server asks users to authorize the requested permissions to their resources, defined as you saw in the previous tutorial as scopes.
The most common OAuth flow is the Authorization Code flow, used for web applications. The URL for this requires the following request parameters:
To construct a URL for this authorization, follow this pattern:
The client ID comes from registering the application. It’s automatically generated (you can change it if you edit the application).
IMPORTANT: Sometimes the phrase “web application” is used loosely, implying applications where the above URL is requested from the web browser directly. If this happens, you’d leak the client secret, compromising the security of the grant flow and the application. In such cases, select the “User Agent Application” client profile instead when registering your application. This makes a secure alternative available to your application: PKCE Extended Authorization Code flow (see below).
Once the user has authorized the requested permissions to their resources, the authorization server returns an authorization code to your application at its registered callback URI (A.K.A. redirect URI) as a query string parameter.
[your callback URI]?code=[authorization server generated code]
Your application must then exchange this authorization code for an access token by sending a POST request following this pattern:
With the following parameters in the body (encoded as
code=[authorization server generated code]
redirect_uri=[registered callback URI]
In the body of HTTP response to this request, you receive JSON like this:
"access_token": "[authorization server generated access token]",
"scope": "[the scopes that were authorized by the user]",
"refresh_token": "[authorization server generated refresh token]"
From this you should extract and persist the access token. If you intend to use the token for an indefinite amount of time (beyond 600 seconds from the above example) you also need the refresh token. This can be used in conjunction with the Refresh Token Flow to obtain a new access token with the same permissions, without further user authorization. The authorization server only issues Refresh Tokens if your application registration is registered for this flow.
This flow is the same as above with the addition of the Proof Key for Code
Exchange (PKCE). It requires another request parameter:
flow is for clients like smartphone applications that may not have sole access
to the URL (and thus the request parameters) redirected to by the authorization
server after the user authorization. It protects against a malicious application
on the same system authorizing itself by reading the response code. To do this,
the client application sends a code challenge with the authorization request:
a string it has generated and which it only knows. To generate this string it
must first create another secret string known as the Code Verifier, and then
apply a transformation to it. After authorization, the code verifier is sent
with the authorization code, validating the client.
For more detail on how to do this, please refer to the PKCE specification.
To support this flow, you must have defined PKCE as an Allowed Authorization
Type when you created the application. This is part of the Native Application
and User Agent Application client profiles. To request an authorization code
using PKCE, use a URL containing the
code_challenge request parameter:
https://[hostname]/o/oauth2/authorize?response_type=code&client_id=[client ID]&code_challenge=[PKCE code challenge]
The rest of the process is identical to Authorization Code flow, except that when making the final request to get the access token, you must also provide the following parameter:
code_verifier=[Code Verifier that was transformed and sent as code_challenge previously]
There are two other, less used flows. If you have a scenario where two servers exchange agreed upon, non user-centric data, you can bypass the Allow/Deny screen for users and authorize the client. This is called the Client Credentials flow, and you’d use this URL pattern:
https://[hostname]/o/oauth2/token?grant_type=client_credentials&client_id=[client ID]&client_secret=[client secret]
A final flow, where users trust the application with their passwords is rare, but possible. This is called the Resource Owner Password flow, and its URL pattern looks like this:
https://[hostname]/o/oauth2/token?grant_type=password&client_id=[client ID]&client_secret=[client secret]&username=[firstname.lastname@example.org]&password=
Users are prompted for their passwords, and upon successful log in, receive an authorization code.
All flows above result in an access token that’s sent by the authorization server (Liferay DXP) to the client application. This token is sent in the response for the client application to store and send along with any future request for data.
For example, say the authorization code
sent to the client application. When the client requests data, this code must be
sent in each request header. Using a command line HTTP client such as Curl, you
could send a request like this:
curl -H 'Authorization: Bearer 946856e2b5ddf0928f6fc55f657bab73' 'https://[hostname]/o/api/sample2'
OAuth 2.0 provides a convenient way for client applications to be granted access to particular services (scopes) by users without sharing credential information.
Once access is granted, users or administrators are free to revoke access whenever they wish. If this happens to a client, the token becomes invalid and the client must ask the user for authorization again. This puts users in control of what has access to their data, and they can exercise this control at any time.
In their account areas, users can click OAuth2 Connected Applications and see a list of applications they’ve allowed to access their accounts. From here, they can revoke access by clicking the Remove Access item in the Action menu or the Remove Access button in the detail screen for the application.
Administrators can view the authorizations in the Authorizations tab of any app in Control Panel → Configuration → OAuth2 Administration.
Clicking the Revoke button on any listed authorization revokes that application’s access to that user’s account.
OAuth 2.0 provides a complete and secure authorization flow for users, without their having to share any credential information. Once applications are created in the system, secure tokens provide access to particular scopes of information, and this access can be revoked at any time, making OAuth 2.0 a convenient method for users and developers alike to access the information they need.