Merge pull request #259 from differentreality/openid_documentation

Documentation about using OpenID

README.md

@@ -19,7 +19,7 @@ git clone https://github.com/openSUSE/osem.git
 bundle install
 ```
 3. Install ImageMagick from your distribution repository
-4. Generate secret key for devise and the rails app with 
+4. Generate secret key for devise and the rails app with
 ```
 rake secret
 ```
@@ -39,12 +39,33 @@ bundle exec rake db:setup
 ```
 rails server
 ```
-8. Visit the APP at 
+8. Visit the APP at
 ```
 http://localhost:3000
 ```
 9. Sign up, the first user will be automatically assigned the admin role.
 
+10. Use openID
+In order to use the OpenID feature you need to register your application with the providers
+(Google and Facebook) and enter their API keys in config/secrets.yml file, changing the existing sample values.
+
+You can register as a devoloper with Google from https://code.google.com/apis/console#:access
+You can register as a devoloper with Facebook from https://developers.facebook.com/,
+by selecting from the top menu the option 'Apps' -> 'Create a New App'
+
+Unless you add the key and secret for each provider, you will not be able to see the image that
+redirects to the login page of the provider.
+
+If you add a provider that does not require developers to register their application, you still need
+to create two (2) variables, in config/secrets.yml
+with the format of providername_key and providername_secret and add some sample text as their values.
+Example:
+myprovider_key = 'sample data'
+myprovider_secret = 'sample data'
+
+That is required so that the check in app/views/devise/shared/_openid.html.haml will pass and
+the image-link to login using the provider will be shown.
+
 ### Run OSEM in production
 We recommend to run OSEM in production with [mod_passenger](https://www.phusionpassenger.com/download/#open_source)
 and the [apache web-server](https://www.apache.org/). There are tons of guides on how to deploy rails apps on various
@@ -53,8 +74,8 @@ base operating systems. Check Google ;-)
 ## Documentation
 OSEM is extensively (some would say maniacally ;-) documented. You can generate a nice HTML documentation with ''rdoc''
 ```
-bundle exec rdoc --op doc/app --all -f fivefish app 
-xdg-open doc/app/index.html 
+bundle exec rdoc --op doc/app --all -f fivefish app
+xdg-open doc/app/index.html
 ```
 
 ## Testing

app/views/devise/shared/_openid.html.haml

@@ -1,4 +1,7 @@
 - if devise_mapping.omniauthable?
   - resource_class.omniauth_providers.each do |provider|
-    = link_to image_tag("#{provider}.png", size: '32x32') + provider , omniauth_authorize_path(resource_name, provider)
-    %br
+    - provider_key = "#{provider}_key"
+    - provider_secret = "#{provider}_secret"
+    - unless Rails.application.secrets.send(provider_key).blank? || Rails.application.secrets.send(provider_secret).blank?
+      = link_to image_tag("#{provider}.png", size: '32x32') + provider , omniauth_authorize_path(resource_name, provider)
+      %br

config/secrets.yml.example

@@ -5,11 +5,32 @@ defaults: &defaults
   secret_key_base: '12345'
 
   # For devise login tokens
-  devise_secret_key: '12345' 
+  devise_secret_key: '12345'
 
   # Your errbit API key
   # errbit_key: '12345'
 
+  # Leave the variables' names empty, unless you use the providers, in which case you need to
+  # register your applicaton and add the actual keys.
+
+  # If you add more providers, keep the format of the variables: provider_key, provider_secret
+
+  # Register your appllication with Google from https://code.google.com/apis/console#:access
+  google_key: ''
+  google_secret: ''
+
+  # Register your application with Facebook from https://developers.facebook.com/
+  facebook_key: ''
+  facebook_secret: ''
+
+  # Developers do not need to register their application for novell account to work.
+  # You must, however, leave the sample data there, for the login option to appear.
+
+  novell_key: 'sample data'
+  novell_secret: 'sample data'
+
+  # If you add more providers that do not require a key, you still have to create the 2 variables with sample data
+
 development:
   <<: *defaults
 

spec/support/omniauth_macros.rb

@@ -2,6 +2,11 @@ module OmniauthMacros
   # The mock_auth configuration allows you to set per-provider (or default)
   # authentication hashes to return during integration testing.
 
+  Rails.application.secrets.google_key = 'test key google'
+  Rails.application.secrets.google_secret = 'test secret google'
+  Rails.application.secrets.facebook_key = 'test key facebook'
+  Rails.application.secrets.facebook_secret = 'test secret facebook'
+
   def mock_auth_new_user
     OmniAuth.config.mock_auth[:google] =
       OmniAuth::AuthHash.new(