Chapter 20. OAuth - Authentication with Social Network accounts
OAuth is an authorization protocol, which allow third party applications to access user resources on behalf of another application (authorization server). The main purpose of OAuth is authorization, but in many web pages, OAuth is also used for authentication or registration of users. JBoss Portal uses OAuth for authentication and registration of users. Currently JBoss Portal acts as a third party application (OAuth client application) and it supports integration with OAuth providers like Facebook, Google+ and Twitter.
For details about specification, see the OAuth page. The current version of specification is OAuth 2.0 and the older version is OAuth 1.0a. Some vendors only support the older version.
20.1. Working of OAuth Protocol
You need to create and register new application on OAuth provider (Facebook, Google, Twitter). Registration is a vendor specific process. In this chapter, the registration process for each vendor is described in detail. The common result of registration for every vendor are:
- Client ID of your application
- Client Secret of your application
- Redirect URL, which will be used by OAuth provider to redirect back from authorization screen to JBoss Portal screen
Registration specific changes are required in the JBoss Portal configuration file
configuration.properties.You need to enable particular OAuth provider and configure the values from registration. After startup of JBoss Portal, your users can login and register into JBoss Portal with OAuth provider.
20.2. OAuth Protocol User Interface
20.2.1. User Registration
Assumptions
- JBoss Portal is running on host
server.local.network.com
We are using Facebook as an example to show the user registration process. This process is similar for other providers such as Google+ and Twitter.
Procedure 20.1. Registration of Portal with Facebook
- JBoss Portal login page has options for logging with Facebook, Google or Twitter. It shows the providers, which you configured. See figure with enabled authentication for Facebook and Google+:
- Click to redirect the user to the Facebook site.
- The user has to authenticate Facebook if not already authenticated.
- Facebook displays an authorization screen.
Note
The required privileges (scopes) are configured inconfiguration.properties. The email and user profile information is sufficient. You can add more privileges but then you have less chance of your users confirming the authorization screen. (For example: It is not a good practice to request publish message on FB wall privilege, if you are using JBoss Portal only for registration/authentication of user)
- User confirms the authorization screen and is redirected to JBoss Portal. The redirected URL is the one you configured as Redirect URL during registration process of your application. For example, the URL for Facebook is http://server.local.network.com:8080/portal/facebookAuth
- JBoss Portal displays the registration dialog box with prepopulated values from Facebook.
- The registration is complete and the user is signed into JBoss Portal.
Note
The user joseph.breburda is treated as normal user of JBoss Portal. So portal administrator can see him in list of users in JBoss Portal UI and can add him to more groups (By default the user is in
/platform/users group). User registered through Facebook has two additional properties saved as part of his UserProfile:
User properties
- Facebook username
- It is used for mapping the JBoss Portal identity to Facebook identity. It can be same as JBoss Portal username, however it is not necessary. It provides information regarding mapping of user names.For example, JBoss Portal user joseph is mapped to Facebook user joseph.breburda.
Note
JBoss Portal has a restriction that Facebook username needs to be unique, so we cannot have two JBoss Portal users with same Facebook username. - Facebook access token
- This is needed for social portlets to use accessToken to retrieve required information from Facebook. For example, you can have portlet for displaying content of Facebook wall of particular user.For more details, see Developer guide, chapter Using data from Social Networks in Portlets
Important
Access token is saved in Picketlink IDM in encoded form using symmetric encryption.
20.2.2. Login Workflow
This workflow is used when JBoss Portal username is connected with Facebook username.
For example, JBoss Portal user
joseph is connected with Facebook user joseph.breburda
Assumptions
- The user authenticated to Facebook as
joseph.breburdais mapped to portal userjoseph
Procedure 20.2. Logging process
- The first three steps are same as Section 20.2.1, “User Registration”.
- User is logged into JBoss Portal as joseph because JBoss Portal already knows that username
josephbelongs to authenticated Facebook userjoseph.breburda
20.3. Integrating OAuth with the Portal
Assumption
- The portal is running on the virtual host
server.local.network.com.
Procedure 20.3. Integrating OAuth
- Setup a virtual host by adding it to
/etc/hosts(on linux):192.168.1.88 server.local.network.com
- In the
JPP_HOME/standalone/configuration/gatein/configuration.propertiesfile, change the propertygatein.oauth.portal.urlto the value of the host. - Set the value for
gatein.oauth.portal.url.gatein.oauth.portal.url=http://server.local.network.com:8080
20.4. Integration of OAuth with Facebook
Facebook is a popular social network, that supports OAuth 2.0 protocol and can act as OAuth provider (Resource server) for JBoss Portal.
Integration of OAuth with facebook consists of two main parts:
- Registration of JBoss Portal application on Facebook
- Configuring JBoss Portal for using OAuth Protocol with Facebook
20.4.1. Registration of Portal application on Facebook
Assumptions
- JBoss Portal host is
server.local.network.comas described in Section 20.3, “Integrating OAuth with the Portal”.
Procedure 20.4. Registering Portal on Facebook
- Register as Facebook developer on https://developers.facebook.com/apps.
- Click and choose an application name such as var
gatein_app.Note
The application name is always unique. - Configure
App Domainsto contain valuelocal.network.comandSite URL for Facebook loginto contain value http://server.local.network.com:8080. You need to rememberClient IDandClient Secret. - Save changes.
Important
Before initiation production, you have to disable sandbox mode in your Facebook application. With sandbox enabled, application is available only for you, your developers and, test users created for your application
20.4.2. Configuring JBoss Portal for using OAuth Protocol with Facebook
Procedure 20.5. Configure properties in Facebook section
- Change the file
configuration.propertiesand configure properties in Facebook.## Facebook gatein.oauth.facebook.enabled=true gatein.oauth.facebook.clientId=135545169971483 gatein.oauth.facebook.clientSecret=9a7c6ece1bffb27b3c5900704e46cd38 gatein.oauth.facebook.redirectURL=${gatein.oauth.portal.url}/@@portal.container.name@@/facebookAuth gatein.oauth.facebook.scope=email
Description of properties
- gatein.oauth.facebook.enabled
- It enable integration with Facebook. Users can login and register with Facebook.
- gatein.oauth.facebook.clientId
- Client ID of your application. This is obtained from registration on Facebook as described in Section 20.4.1, “Registration of Portal application on Facebook”
- gatein.oauth.facebook.clientSecret
- Client Secret of your application. This is obtained from registration on Facebook as described in Section 20.4.1, “Registration of Portal application on Facebook” .
Note
The client secret should not be shared among your portal users or other people. - gatein.oauth.facebook.redirectURL
- The URL used by Facebook to redirect after user confirms Facebook authorization screen as shown in, step 3 of Section 20.2.1, “User Registration”. You do not need to change this value. But if you have changed property
gatein.oauth.portal.urlas described in Section 20.3, “Integrating OAuth with the Portal”, you have to set this value. - gatein.oauth.facebook.scope
- Scopes represent permissions required from users on Facebook authorization screen. This list of scope is used during user registration or authentication to JBoss Portal (portlet applications may require more scopes if they need it). It is recommended not to change this value and keep value as email. Alternatively you can:
- Delete email and use empty value instead - In this case, JBoss Portal will ask only for basic set of permissions. However, JBoss Portal will not be able to access email address, so this field will remain empty during user's registration to JBoss Portal.
- Use more values - you can use more values described in Facebook documentation . However, it is likely that users will not allow your Portal application to access their informations. And having more values is only useful for quickstart portlet applications, but quickstart applications can ask for more scopes as per their requirement.
Note
Scopes from this configuration property are used during registration/login of users
After restart of JBoss Portal, your users should be able to register or login with their Facebook accounts as described in Section 20.2.1, “User Registration” .
20.5. Integration of OAuth with Google plus
Google+ is a popular social network. It supports OAuth 2.0 protocol. The integration of Google plus with JBoss Portal consists of two main parts:
- Registration of JBoss Portal application on Google plus
- Configuring JBoss Portal for using OAuth Protocol with Google plus
20.5.1. Registration of Portal application on Google
Assumption
- JBoss Portal is hosted on
server.local.network.comas described in Section 20.3, “Integrating OAuth with the Portal” .
Procedure 20.6. Registering Portal on Google
- Register as Google developer on https://code.google.com/apis/console/.
- Click Create new application and choose an application name such as
gatein_google_app. - Under services, turn on Google+ API.
- Under >API Access, click Create new OAuth 2.0 client.
- In the Create Client ID dialog box, enter name of product in Product name. Click Next.
- Select Web application. Enter http://server.local.network.com:8080/portal/googleAuth in Authorized Redirects
Note
You can have multiple URIs, that can be used as returning URIs from Google plus application. - Click
Result
- The Client ID for web applications dialog box shows the client information such as the Client ID, Email address, Client Secret, Redirect URl and so on. These values are used during JBoss Portal configuration.
Note
For more details about registration process, see Google+ documentation
20.5.2. Configuring JBoss Portal for using OAuth Protocol with Google plus
Procedure 20.7. Configure properties in Google plus
- Change the file
configuration.propertiesfor configuring Google plus.## Google gatein.oauth.google.enabled=true gatein.oauth.google.clientId=397260572677.apps.googleusercontent.com gatein.oauth.google.clientSecret=pOWDqdu57CjplhrMmkrgcia5 gatein.oauth.google.redirectURL=${gatein.oauth.portal.url}/@@portal.container.name@@/googleAuth gatein.oauth.google.scope=https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile gatein.oauth.google.accessType=offline
Properties description
- gatein.oauth.google.enabled
- It enables integration with Google plus. Users can login and register with Google plus.
- gatein.oauth.google.clientId
- Client ID of your application. This is obtained from registration with Google as described in Section 20.5.1, “Registration of Portal application on Google”
- gatein.oauth.google.clientSecret
- Client Secret of your application. This is obtained from registration with Google as described in Section 20.5.1, “Registration of Portal application on Google”.
- gatein.oauth.google.redirectURL
- The URL used by Google to redirect after user confirms Google plus authorization screen (Step 3 of Section 20.2.2, “Login Workflow” ). Normally you do not need to change this value as long as you changed property
gatein.oauth.portal.urlas described in Section 20.3, “Integrating OAuth with the Portal”. - gatein.oauth.google.accessType
- Possible values are
offlineoronline. The default value isoffline. In offline access, the token can be used even if you are not logged into Google+ . It can be refreshed automatically by JBoss Portal.Note
For more info about access types is https://developers.google.com/accounts/docs/OAuth2WebServer#offline . - gatein.oauth.google.scope
- Scopes represent permissions required from users on Google authorization screen. This list of scope is used during user registration or authentication to JBoss Portal (portlet applications may require more scopes if they need it). It is recommended not to change this value and keep value as https://www.googleapis.com/auth/userinfo.email and https://www.googleapis.com/auth/userinfo.profile. Alternatively you can:
- Either use https://www.googleapis.com/auth/userinfo.email or https://www.googleapis.com/auth/userinfo.profile. In both cases, user will be able to login into JBoss Portal, but some information will be obtained from Google.
- Use more values by adding value at https://www.googleapis.com/auth/plus.login. However, it is likely that users will not allow your Portal application to access their informations. And having more values is only useful for quickstart portlet applications, but quickstart applications can ask for more scopes as per their requirement.
- It is user friendly for some quickstart portlets such as GoogleActivitiesPortlet and GoogleFriendsPortlet. But to use Google+ only for login (not using portlet applications), the scope https://www.googleapis.com/auth/plus.login is not needed.
After restart of JBoss Portal, your users should be able to register or login with their Google accounts as described in Section 20.2.1, “User Registration”
20.6. Integration of OAuth with Twitter
Twitter is a social network, that can be integrated with JBoss Portal. It support OAuth 1.0a and not OAuth 2.0 protocol. Integration of Twitter with JBoss Portal consists of:
- Registration of JBoss Portal application on Twitter.
- Configuring JBoss Portal for using OAuth Portocol with Twitter.
20.6.1. Registration of Portal application on Twitter
Assumption
- JBoss Portal is hosted on
server.local.network.comas described in Section 20.3, “Integrating OAuth with the Portal” .
Procedure 20.8. Registering on Twitter
- Register as Twitter developer on https://dev.twitter.com/.
- Register new application on https://dev.twitter.com/apps.
- Click Create new application.
- Enter name and description of application
- Enter the value for website as http://server.local.network.com:8080.
- Enter Callback URL value as http://server.local.network.com:8080/portal/twitterAuth
Callback URL is a mandatory field
The Callback URL is required to recognize the application type as web application, and twitter does not accept http://localhost:8080/portal as a valid URL. - Click .
- Click Settings. Select Allow this application to be used to Sign in with Twitter.
Note
Remember the value of clientId and clientSecret as they are required in JBoss Portal configuration.
20.6.2. Configuring JBoss Portal for using OAuth Protocol with Twitter
Procedure 20.9. Configure properties in Twitter
- Change the file
configuration.propertiesfor configuring Twitter.## Twitter gatein.oauth.twitter.enabled=true gatein.oauth.twitter.clientId=JBBAkYseVCzStLhhOQ gatein.oauth.twitter.clientSecret=Ihi1txdiasrjMJoisRFvBaUjVq1K87gJNKW7VCbY gatein.oauth.twitter.redirectURL=${gatein.oauth.portal.url}/@@portal.container.name@@/twitterAuth
Properties description
- gatein.oauth.twitter.enabled
- It enables integration with Twitter. Users can login and register with Twitter.
- gatein.oauth.twitter.clientId
- Client ID of your application. This is obtained from registration with Twitter as described in Section 20.6.1, “Registration of Portal application on Twitter”
- gatein.oauth.twitter.clientSecret
- Client Secret of your application. This is obtained from registration with Twitter as described in Section 20.6.1, “Registration of Portal application on Twitter”
Note
The client secret should not be shared among your portal users or other people. - gatein.oauth.twitter.redirectURL
- The URL used by Twitter to redirect after user confirms Twitter authorization screen (Step 3 of Section 20.2.1, “User Registration” ). Normally you do not need to change this value as long as you changed property
gatein.oauth.portal.urlas described in Section 20.3, “Integrating OAuth with the Portal”.
After restart of JBoss Portal, your users should be able to register or login with their Twitter accounts as described in Section 20.2.1, “User Registration” .