Chapter 7. OAuth Provider API

⁠Chapter 7. OAuth Provider API

7.1. Retrieve an Instance of OAuthProvider
7.2. OAuthProvider Operations
7.3. Access to Provider-specific Operations

The interface OAuthProvider is a part of the public API. It is the entry point to perform operations on OAuth providers such as Facebook, Google, and Twitter.

Some additional portal configuration is required to use OAuth providers for authentication of users. See OAuth - Authentication with Social Network Accounts chapter in the Administration and Configuration Guide for more details on this topic.

Once a user is authenticated (or their account is linked with the OAuth provider), their access token is saved in the IDM database as a part of their User Profile. It is possible to retrieve the user's OAuth access token through the OAuthProvider interface and run its operations. It is also possible to revoke or validate existing access tokens or send a request to obtain new access tokens with more scopes (privileges).

The following sections present basic uses for the OAuthProvider API. There is an excellent Quickstart available called Portlets for Integration with Social Networks, shipped in the Quickstarts binary.

Report a bug

⁠7.1. Retrieve an Instance of OAuthProvider

You need to retrieve the appropriate instance of OAuthProvider from Portal.

Currently the portal supports three OAuth providers:

OAuthProvider.FACEBOOK for Facebook.
OAuthProvider.GOOGLE for Google+.
OAuthProvider.TWITTER for Twitter.

⁠

Example 7.1. Retrieve Facebook OAuth Instance

This example shows the syntax to use when retrieving the Facebook instance of OAuthProvider. This syntax can be adapted for other instances.


Portal portal = PortalRequest.getInstance().getPortal();
OAuthProvider facebookProvider = portal.getOAuthProvider(OAuthProvider.FACEBOOK)

Report a bug

⁠7.2. OAuthProvider Operations

⁠

Example 7.2. OAuthProvider Basic Use

This example provides a code snippet that describes some basic uses of the OAuthProvider API.


// Retrieve instance of Google OAuth provider
OAuthProvider googleProvider = PortalRequest.getInstance().getPortal().getOAuthProvider(OAuthProvider.GOOGLE);

// Check if Google was enabled in configuration.properties
if (googleProvider == null) {
    renderResp.getWriter().println("Authentication with Google not available. Ensure your administrator has enabled the service in the portal. See the Administration and Configuration Guide for instructions.");
    return;
}

// Retrieve the key and display name of the social network
String key = googleProvider.getKey();
String friendlyName = googleProvider.getFriendlyName();
renderResp.getWriter().println(friendlyName + " is enabled");

// Retrieve access token of the current user
AccessToken accessToken = googleProvider.loadAccessToken(renderReq.getRemoteUser());

// Check if access token is available. It's the case when this user was registered/authenticated into portal
// through Google+ or if he linked his account with Google+
if (accessToken == null) {
    renderResp.getWriter().println("Your account is not linked with Google+. You can link it in 'Social network' tab of " +
        "user settings or you can authenticate through Google into portal");
    return;
}

// Check if access token is valid and refresh it if necessary
try {
    accessToken = googleProvider.validateTokenAndUpdateScopes(accessToken);
} catch (OAuthApiException oauthException) {
    if (oauthException.getExceptionCode().equals(OAuthApiExceptionCode.ACCESS_TOKEN_ERROR)) {
        renderResp.getWriter().println("Your access token is invalid or has been revoked");
    } else if (oauthException.getExceptionCode().equals(OAuthApiExceptionCode.IO_ERROR)) {
        renderResp.getWriter().println("Network error during the communication with Google");
    }
}

// Check all available scopes
String availableScopes = accessToken.getAvailableScopes();

// Check if we have scope to call Google+ operations
if (!availableScopes.contains("https://www.googleapis.com/auth/plus.login")) {
    // Redirect to Google+ and ask for plus.login scope
    googleProvider.startOAuthWorkflow("https://www.googleapis.com/auth/plus.login");
    return;
}

// Obtain Google API object to call Google plus API operations
Plus service = googleProvider.getAuthorizedSocialApiObject(accessToken, Plus.class);

// Retrieve activities from Google+ wall of user
ActivityFeed activityFeed = service.activities().list("me", "public").execute();
for (Activity activity : activityFeed.getItems()) {
    renderResp.getWriter().println(activity.getTitle());
}

// Revoke the access token. It won't be possible to run any operations with it anymore.
// And your application will be cleared from Google applications of current user on page https://plus.google.com/apps
googleProvider.revokeToken(accessToken);

// Remove the token from the UserProfile of the current user
googleProvider.removeAccessToken(request.getRemoteUser());

Report a bug

⁠7.3. Access to Provider-specific Operations

The oauthProvider.getAuthorizedSocialApiObject() method is used to obtain access to provider-specific operations. This method usually returns objects from a third-party library. Those objects are always initialized with the access token of the current user and can be used to retrieve data from the related social network.

Google

There are two supported types usable as arguments of this method:

com.google.api.services.plus.Plus: - Google Plus API class, which can be used to call operations on Google Plus - see GoogleActivitiesPortlet and GoogleFriendsPortlet in the Quickstart.
com.google.api.services.oauth2.Oauth2: OAuth2 class, which provides operations related to the user, such as obtaining their Google user profile details or obtaining information about his access token - see GoogleUserInfoPortlet in the Quickstart.

Twitter

There is only one supported type for Twitter: twitter4j.Twitter . An instance of this class can be used to retrieve user details, number of tweets, number of friends, last tweets. See TwitterPortlet in the Quickstart.

Facebook

There is no supported type for Facebook. In the Quickstart, the third-party library RestFB is used to perform operations against Facebook.

Report a bug