There are 3 ways to implement single sign on with Google account.

1) OpenId

2) SAML

3) OAuth2

As per the latest Google apps market place guidelines, Google is discouraging the usage of openid and SAML.

OAuth2 is the recommended way of providing SSO with google apps and this is a must to be integrated with google apps.

1) A site which needs to support google SSO should create a project in google developer console.

a. Go to - https://console.developers.google.com/project

b. Create Project and give a name you like.

c. Click on 'Library' Under “API API Manager” on the left panel and make sure “Google+ API” and “Contacts API” are turned on. (This is the API we use to get the profile info of the user from Google.)

d. Click on 'credentials' on the left side panel under “API API Manager”.

e. Create a new OAuth client ID -

Authorized JavaScript origins - your super site base URL (ex - http://dev01.learnexa.com)

Authorized redirect URI - <learning_site_url>/auth/google_oauth2/callback (ex - http://dev01.learnexa.com/auth/google_oauth2/callback)

f. Note down the details of client ID and client secret.

g. Make sure that you enter “Email address” and “Product name” under 'consent screen' link of “API API Manager”. Upload logos if you want.

2) Update the client and secret in config/google_sso.yml file and save.

User creation flow is very much similar to sales-force user creation except that we do not need to show a screen to enter first name, last name and signup. We can directly sign the user up as we have that information.

1) For now, we can show a link on the login screen of the learning site to login using Google. Clicking on this will take user to google login page if he is not logged. After loggin in it will redirect him to my learning page. In the background google would have redirected the user to the leanrning site's callback URL and we would have created the account for him if there was no account already with this email.

2) The user session is maintained through cookies in the same way as we do for salesforce SSO.

3) If the user wants to login using google again, he can follow the same procedure as (1).

4) If the user wants to login from the learning site, he needs to generate a password which is the case with salesforce SSO.

5) Note - For now, all the users are created with the default privileges of the learning site. (Learners if default user creation privilege is set as learners).

Future Change - If we decide to provide laearnexa site in google app market, then users will click on app link to launch the learning site which does not need a link on login page to login using google.

1) Not sure why we show a screen to provide first name, last name and ask the user to signup in case of Salesforce SSO. We do not need this in case of Google SSO as we can get all the details from API during the authentication itself ? Do we need the user to read terms and conditions and check them explictly for the learning site? (If not we can just create an account in the background and improve the user experience here).

2) Password needs to be reset for the user if he wants to login to the learning site directly as per current implementation. Should we keep it the same for Google SSO as well ? If we decide to present the user in the question above, then we can also ask him to set a password there itself (exactly like how Quora does.)

Gems useful - https://github.com/zquestz/omniauth-google-oauth2

One open item is to implement dynamic provider for the configuration which configures different providers for different learning sites.

Add a new table to save oauth SSO settings for each company. This supports all oauth based SSO providers (for now google. In future this can be extended to FB, github and etc.)

oauth_sso_settings

users

Learnexa site should be available in Google apps market. Once installed, it should be launch-able from the universal navigator of google apps.

As Learnexa is a multitenant application with support for subdomains and own domains. So, To make it launchable in Google apps, the Google SSO per site is not suitable.

1) Learnexa application is made available in market place with it's logo. There will be a universal launch URL like http://learnexa.com/marketplace

2) Google apps admin of any site can go to Learnexa in market place and install it. While installing, after google account authentication, admin is redirected to the universal launch URL of learnexa app. Either of the following will happen -

a) Learnexa site admin can specify the google app email domain on learnexa admin page. If this email domain is specified, admin is simply logged in to the learnexa site which has the email domain of this user configured.

b) If no email domain was set already on learnexa site, then a screen will be presented to the admin to enter the site URL which needs to be linked to his email domain account. After this, admin is logged into the site.

3) From here after , all the users of the above email domain would see Learnexa app in their google apps navigator. When they click on the navigator link they are redirected to google login page and then to the site my learning via the universal launch URL mentioned above. None of the users would see the screen asking to enter the site name as it would have been set in step (2).

4) Any user can login from learnexa site's home page by clicking on “Sign in with google”. We will login the user through oauth and redirect them to their site. All the oauth flow is handled by learnexa app but the redirection to learning site happens based on the URL they have used while logging in. This url is preserved through oauth flow as state parameter.

1) Validation - Only restriction here is if a google apps domain can;t be linked to more than one learning sites in Learnexa. This is needed to differentiate to which site user gets logged when launched from google apps navigation menu. So, this validation is checked when the admin tried to link his learning site with a google apps domain.

2) Can a learning site allow more than one google apps domains ?

Yes. This is allowed.

Reference - https://developers.google.com/apps-marketplace

1) Setting up the application - https://developers.google.com/apps-marketplace/preparing

2) Publishing the application - https://developers.google.com/apps-marketplace/listing

To get the app approved in market place -

• Care should be taken that , proper oauth flow is implemented.

• Correct APIs need to be used to get the information.

• Google recommends the apps to do something significant with the APIs but not using it just like a login server. This is just a recommendation.

Gems used - https://github.com/zquestz/omniauth-google-oauth2

Add a new table to save market_palce_settings for each company. This can have multiple entries for the same company but with different domains.

market_place_settings

users

companies

1. Create a new Google Client and market place app as mentioned below and keep the API key and secret ready. Google SSO and marketplace setup . (Please execute step 1 and step 2). [TO BE DONE by Murali on Production]

2. Create a file - /deploy/crossbow/shared/config/google_sso.yml and update the client_id and client_secret values for given environment. [TO BE DONE by Uday on Production]

3. Update deploy script to symlink this file. [TO BE DONE by Uday on Production]

vi ~/crossbow/config/deploy.rb
// Add following line under symlink tasks.
run "ln -nfs #{shared_path}/config/google_sso.yml #{release_path}/config/google_sso.yml"

1. Complete the Listing Review Request form - Will be done
2. Monitor the associated email address - Will be done
3. Use OAuth2.0 - Done
4. Define your scopes properly - Done (defined email and profile scopes for now.)
5. Use one-click single sign-on - Done
6. Use Core Google Services API - Done (Contats API - Omniauth google oauth2 gem uses this by default)
7. Use the Universal Navigation Link appropriately - Done.
8. Use the Setup link in the SDK - No additional setup needed.
9. Upload your images at the correct size - Will be done.

References -

a) Setting up the application - https://developers.google.com/apps-marketplace/preparing

b) Publishing the application - https://developers.google.com/apps-marketplace/listing

• Only Step (1) is needed for SSO Support.
• Step (2) is needed for marketplace integration and our internal testing. After this step, only the users with google apps domain of the app creator will be able to use the app. (In our case learnexa.com)
• Step (3) is needed for publishing the app to marketplace. This is when the customers will be able to install the app and use. Till then they can use Google SSO but not be able to launch the app from their Google apps.

a) Go to - https://console.developers.google.com/project

b) Create Project and give a name you like (say - Learnexa).

c) Click on 'APIs' Under “APIs & auth” (left navigation links) and make sure “Google+ API” and “Contacts API” are turned on. If they are not on, please turn them on.

d) Click on 'credentials' on the left side panel under “APIs & auth”.

e) Create a new client ID -

Authorized JavaScript origins - The super site base URL (ex - http://learnexa.com)

Authorized redirect URI - <super_site_base_url>/auth/google_oauth2/callback (ex - http://learnexa.com/auth/google_oauth2/callback)

f) Note down the details of client ID and client secret. These are needed to be configured in learnexa app's config/google_sso.yml

g) Click on 'consent screen' link of “APIs & auth”. > Make sure that you enter “Support Email” and “Product name” under this.

a) Go to https://code.google.com/apis/console/?api=plus#:services?noredirect

b) Make sure the project created in the previous step is selected on the left top corner. Now, enable “Google Apps Marketplace SDK ”. As of now, we do not use any of these API services here. In future, enable these services as needed.

c) Provide application name (ex - Learnexa) and description.

The icons are available at - https://tracker.exphosted.com/view.php?id=6100 (inside learnexa-google-logos-v2.zip)

Enable Individual Install - We can enable this as we might want individuals to be able install (not only groups)

Terms of service URL - http://learnexa.com/terms-of-service

Privacy Policy URL - http://learnexa.com/privacy (Check the check box to see the textbox where you enter this.)

Oauth scopes - None

d) Enable “Universal Navigation Extension” under extensions and URL value - http://learnexa.com/market_place

save changes.

Generally it takes 15 mins for the changes to reflect. Test the install flow and the developer can test the SSO flow with the credentials of the client created under step (1) .

Reference - https://developers.google.com/apps-marketplace/listing

Resources - Uploaded to issue - https://tracker.exphosted.com/view.php?id=6100 (Note: Change the manifest.json as needed.)

To be done -

• Prepare & Provide test account credentials for learnexa. ( 1 or 2 learnexa.com email accounts and a production site which is configured with 'learnexa.com' and has self registration enabled.)

Steps To Publish

Keep the resources above ready and follow the steps under “Setting it Up” Section of https://developers.google.com/apps-marketplace/listing

a) Creating app in Google Chrome web store -

All the resources are attached to the issue - https://tracker.exphosted.com/view.php?id=6100

Go to https://chrome.google.com/webstore/developer/dashboard. Click on “Add new item” and upload learnexa.zip. (Note: Review manifest.json. Please make changes if any are needed).

Now, enter the following details once the app is created from the uploaded zip file.

• Detailed description ( Present in - learnexa-chrome-webstore-description-v1.docx)
• Screenshots (Present in - learnexa-google-screenshot-v2.zip)
• Promotional tile images (Preview the tiles to see if they look fine.)
• Category
• Language
• Visibility options - (for now, we can set unlisted, till the Google review.)

Keep saving the changes as draft. When we are ready to publish, please publish.

b) Filling in the review form -

Review form - (https://docs.google.com/forms/d/14QOb8PbSLKDgwIp8Zv-luoAAVurPXUqtzL0Hgikp3rk/viewform)

Have you made sure your application conforms to the best practices document? - YES (Check List)

Does your application use OAuth2.0 for login and authentication (should not use OpenID or OAuth1)? - YES

What Google Apps Marketplace SDK Extensions does your application define? - Google Universal Navagation

Which of the following Google Services APIs does your application utilize? - Contacts API (Note - only this for now, in future, more APIs will be enabled.)

What additional Google APIs does your application utilize? - Google + API

Does your application require additional signup/usage instructions?

Application logs in only the google domains which are pre configured in the learnexa learning site. If a user installed it with a google domain which is not configured with any learnexa site, a message is shown to the user when he launches it.

For the review, we have configured the domains already. Please login with the following username and password to test the flow.

username: ssotest@learnexa.com (→ replace this with any test Google account for review.)

password: <password> (→ replace this with a valid password.)

If the application reviewer likes to review with any other google app domain, please communicate the google app domain account to us sothat we will configure a learnexa site with it.

Note: To do : Please configure learnexa.com domain under Manage Site > Single Sign on > Google Tab of any test site on learnexa.com. For now, test.learnexa.com is configured with learnexa.com. If we need to create a new site for this purpose, we can do it.

Please change this site's registration type to self registration so that Google reviwer can see the whole flow.

Provide a screen capture video of your application demonstrating meaningful integration using the APIs
that you specified above and usage of OAuth 2.0 login

- Video uploaded to issue - https://tracker.exphosted.com/view.php?id=6100

This video shows the oauth flow of us and also shows the data we read using Google + API (which internally uses contacts API).

Note: Review Please review this video. If we like to retake this, it can be retaken from a production learnexa site with a new google app account. Upload this on youtube as an unlisted video and paste the URL in the form.

Note - (To be done by Murali on Prod.)

Log out if all google accounts on the browser. Login again with the google account you need to use for marketplace app submission.

1. Go to https://console.developers.google.com and choose the project.

2. On the left navigation links , under “APIs & Auth” make sure that “Contacts API” is on. (This would be on by default, generally.)

3. Go to - https://code.google.com/apis/console/?api=plus#:services?noredirect and choose your application. (From drop down box on the Left corner).

4. Scroll down to the “Scopes > Oauth scopes”. Remove “https://www.googleapis.com/auth/contacts” and paste “https://www.googleapis.com/auth/contacts.readonly” in the text box and click on “Add”. Save Changes.

Example - Sample screenshot showing where to add the scope. (contacts in this case).

5. Changes may take about 10 mins to reflect.

Note - (To be done by Uday on Prod after Murali's review.)

1. Update 'scope' filed of current stanza of google_sso.yml config file. Needed on both app servers on production. For example when adding 'contacts.readonly' scope, it looks like below.

production:
  client_id: GOOGLE_CLIENT_ID
  client_secret: GOOGLE_CLIENT_SECRET
  enabled: true
  scope: "userinfo.email, userinfo.profile, contacts.readonly"

2. Restart the app server.

cd /deploy/crossbow/current
touch tmp/restart.txt

Note - (To be done by Uday on Prod for learnexa.com before submitting app for Google again.)

When ever the oauth scopes change we need to inform the admins of the Google apps domains who use our application to grant the access with new privileges. Otherwises users are presented with the consent screen which is not proper SSO.

Google apps admin has to follow the steps below for this, which are straight forward.

1. Go to - https://admin.google.com and login.

2. Under admin console > More controls > Click “Marketplace Apps”

3. Choose the “Learnexa” App in the list.

4. Click on “Data access” which has note “Approve needed”. ('Dev01 Learnexa' is the app in the screenshot for example).

5. Grant the access.