From 64273920e93c563b2a9036cf5f2c4416fe4f841c Mon Sep 17 00:00:00 2001 From: Gaelian Ditchburn Date: Fri, 17 Apr 2015 08:44:08 +1000 Subject: [PATCH] Updated README with new auth/upgrade instructions. --- README.textile | 45 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/README.textile b/README.textile index 0fc08fb6b..28e09f439 100644 --- a/README.textile +++ b/README.textile @@ -26,20 +26,57 @@ h2. Quick Start rails server # Start the server # Load http://localhost:3000/admin in your browser -Or for bonus points, fork "enki at github":http://github.com/xaviershay/enki/tree/master and clone that instead. +Or for bonus points, fork "enki at github":https://github.com/xaviershay/enki/tree/master and clone that instead. h2. More info Enki is a compact, easily extendable base for your blog. It does this by being highly opinionated, for example: -* Public facing views should adhere to standards (XHTML(eXtensible Hypertext Markup Language), Atom) +* Public facing views should adhere to standards (HTML5, Atom) * /yyyy/mm/dd/post-title is a good URL for your posts * Live comment preview should be provided by default * Google does search better than you or I * You don't need a plugin system when you've got decent source control -* If you're not using OpenID you're a chump +* If you're not using something more than just a basic username/password, you're a chump * Hacking code is the easiest way to customize something +h2. Setting up authentication + +Enki uses "OmniAuth":https://github.com/intridea/omniauth for authentication. By default Enki supports "Google OpenID Connect (OAuth 2.0 for Login)":https://developers.google.com/identity/protocols/OpenIDConnect via the "omniauth-google-oauth2":https://github.com/zquestz/omniauth-google-oauth2 strategy and OpenID 2.0 via the "omniauth-openid":https://github.com/intridea/omniauth-openid strategy. Should you wish to use a different form of authentication, you can implement any of the "available OmniAuth strategies":https://github.com/intridea/omniauth/wiki/List-of-Strategies, or write your own strategy. + +h3. Using Google OpenID Connect for authentication + +You will need a Google account, then: + +* Go to "https://console.developers.google.com":https://console.developers.google.com +* Select (or create) your project +* Click 'APIs & auth' +* Make sure "Contacts API" and "Google+ API" are enabled. +* Go to the Consent Screen, and provide an 'Email address' and 'Product name' +* Wait 10 minutes for changes to take effect. +* Click on 'Credentials' under 'APIs & auth' and take note of your 'Client ID' and 'Client secret' + +Create a new file called google_oauth2.yml in your config directory, add your 'Client ID' and 'Client secret' to the file thusly: + +
GOOGLE_CLIENT_ID: 'ADD_YOUR_CLIENT_ID_HERE'
+GOOGLE_CLIENT_SECRET: 'ADD_YOUR_CLIENT_SECRET_HERE'
+
+ +If you are deploying to Heroku, you will need to set the above as ENV variables instead of using google_oauth2.yml. For example: + +
$ heroku config:set GOOGLE_CLIENT_ID=my_client_id
+$ heroku config:set GOOGLE_CLIENT_SECRET=my_client_secret
+ +Open up config/enki.yml and make sure that the google_oauth2_email value matches the email address of your Google OpenID Connect identity. + +h3. Using OpenID 2.0 for authentication + +Open up config/enki.yml and make sure that the open_id value(s) match one or more of your OpenID identity URLs. + +h2. Upgrading to Enki 2015 + +As of April 2015, Enki no longer uses the "open_id_authentication":https://github.com/Velir/open_id_authentication gem. Commit "ec85a":https://github.com/xaviershay/enki/commit/ec85aef26ee82f17e8225be5cbe03ea459d1f112 contains database migrations that remove both tables used by open_id_authentication and add a new table to store OmniAuth response information. Should you wish to keep any data that you may have currently stored in either the open_id_authentication_nonces or open_id_authentication_associations tables, retrieve this information before you run rake db:migrate to upgrade your Enki install. + h2. URL path prefix Enki can run your blog with a URL path prefix. For example, you can run it at example.com/*blog* instead of blog.example.com. You can do so with the RAILS_RELATIVE_URL_ROOT environment variable, set either before starting the server or in config/application.rb before Enki::Application. Uncommenting this line in config/application.rb will enable this behavior in all environments: @@ -56,7 +93,7 @@ Enki embodies much of the philosophy of SimpleLog, but does so in a style that i h2. Compatibility -Uses Ruby 1.9.3 or newer and Rails 4. Runs on MySQL or Postgres. Works on heroku. +Uses Ruby 1.9.3 or newer and Rails 4. Runs on MySQL or Postgres. Works on Heroku. h2. Contributors, these guys rock