In OAuth 2.0, applications are granted access to limited subsets of user data. These are called scopes (not to be confused with Liferay scopes). They are created in two ways:
By administrators, by creating a Service Access Policy for the scope
By developers, by creating a JAX-RS endpoint. By default, scopes are generated based on the HTTP verbs supported by the JAX-RS endpoint. A special annotation override this behavior and register specific scopes.
Creating a Scope for a JSONWS Service
The most common way to create a scope is to create a
Service Access Policy
prefixed with the name
OAUTH2_. This naming convention causes the policy to appear
in the OAuth application configuration screen as a scope.
For example, say the application needs access to a user’s profile information to retrieve the email address. To grant the application access to this, go to Control Panel → Configuration → Service Access Policy, and create the policy pictured below.
Note that the policy is not a default policy, and that it grants access only to
one method in the
UserService. This is a JSONWS web service generated by
Service Builder. You can view a list of all available services in your
installation at this URL:
Once you create a policy and name it with the
OAUTH2_ prefix, it appears in
the Scopes tab in OAuth2 Administration.
Now you can select it and save your application.
Creating a Scope for a JAX-RS Service
Without any special Liferay OAuth2 annotations or properties, a standard OSGi JAX-RS application is inspected by the Liferay OAuth2 runtime and scopes are derived based on the HTTP verbs supported by the application.
When developers want more control, they can register their JAX-RS application
with the property
oauth2.scopechecker.type=annotations and use
com.liferay.oauth2.provider.scope.RequiresScope exported from the
Liferay OAuth2 Provider Scope API bundle to annotate endpoint resource methods or
whole classes like this:
Once deployed, this becomes a scope in the OAuth 2.0 configuration.
Creating the Authorization Page
This step is optional. Users need an interface to authorize access to their accounts, and one is provided automatically. If, however, you want to customize the page, you can create an authorization page in your Site.
Go to Control Panel → System Settings → Security → OAuth2. Click the bottom item on the left, labeled Authorize Screen.
Two defaults appear. The first is the URL to the authorize page. By default, it’s
/group/guest/authorize-oauth2-application. This corresponds to the default site’s URL and a page on that site called
If you have customized the name and URL of your default site, make the appropriate change here so the URL matches the page you’ll create in that site next. Click Save.
Go to your Site’s Build → Pages screen. Click the button and choose Private Page. This forces users to log in.
Choose the Full Page Application type.
Give the page the same name you configured in step 2.
Uncheck the box labeled Add this Page to the following Menus:. You don’t want this page showing up in your Site navigation.
On the page that appears next, verify the Friendly URL matches the URL you configured in step 2.
Under Full Page Application, choose OAuth2 Authorize Portlet.
Excellent! Users can use the default or the UI of your design to go through the authorization process. Now that you have the UI and you understand scopes, it’s time to make the authorization process happen in your application.