readme.txt 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142
  1. === Keyring ===
  2. Contributors: beaulebens, mdawaffe, jshreve, automattic
  3. Tags: authentication, security, oauth, http basic, key, token, authorization, delicious, facebook, flickr, foursquare, google contacts, instagram, instapaper, linkedin, runkeeper, tripit, tumblr, twitter, yahoo, web services
  4. Requires at least: 3.3
  5. Tested up to: 3.6
  6. Stable Tag: 1.5.1
  7. An authentication framework that handles authorization with external web services.
  8. == Description ==
  9. See the [Keyring Developer's Guide](http://dentedreality.com.au/projects/wp-keyring/) for more details.
  10. Keyring provides a very hookable, completely customizable framework for connecting your WordPress to an external service. It takes care of all the heavy lifting when making authenticated requests, so all you need to do is implement cool features and not worry about these tricky bits.
  11. Out of the box, Keyring currently comes with base Service definitions for webservices which use:
  12. * HTTP Basic
  13. * OAuth1
  14. * OAuth2
  15. And includes an example service implementation (services/extended/example.php) plus ready-to-use definitions for:
  16. * [Delicious](http://delicious.com/)
  17. * [Facebook](http://facebook.com/)
  18. * [Flickr](http://flickr.com/)
  19. * [Foursquare](http://foursquare.com/)
  20. * [Google Contacts](http://google.com/)
  21. * [Instagram](http://instagram.com/)
  22. * [Instapaper](http://instapaper.com/)
  23. * [LinkedIn](http://linkedin.com/)
  24. * [Moves](http://moves-app.com/)
  25. * [RunKeeper](http://runkeeper.com/)
  26. * [TripIt](http://tripit.com/)
  27. * [Tumblr](http://tumblr.com/)
  28. * [Twitter](http://twitter.com/)
  29. * [Yahoo! Updates](http://yahoo.com/)
  30. You can very easily write your own Service definitions and then use all the power of Keyring to hook into that authentication flow. See the [Keyring Developer's Guide](http://dentedreality.com.au/projects/wp-keyring/) for more details.
  31. == Installation ==
  32. 1. Install Keyring either via the WordPress.org plugin directory, or by uploading the files to your server
  33. 2. Activate Keyring in Plugins > Installed Plugins
  34. 3. Go to Tools > Keyring > Add New and you will be prompted to configure services before making user-specific connections to them
  35. == Frequently Asked Questions ==
  36. = How Do I Use Keyring in my Plugin? =
  37. Check out the [Keyring Developer's Guide](http://dentedreality.com.au/projects/wp-keyring/).
  38. See [Keyring Social Importers](http://wordpress.org/plugins/keyring-social-importers/) for an example. You can also extend Keyring Service classes directly, rather than attaching the service as a property to an object (like the Importers do).
  39. = Will Keyring work on my WordPress? =
  40. Keyring requires PHP 5.3+ to work, because it makes use of some modern features in PHP like late static binding and abstract classes. Other than that, as long as you meet the minimum required WP version, you should be OK to get started. If you get a cryptic "T_PAAMAYIM_NEKUDOTAYIM" error, you need to upgrade to PHP 5.3+.
  41. Your webserver will also need to be able to make outbound HTTPS requests for some operations with some services to work correctly.
  42. = How do I configure Services? =
  43. Most services within Keyring require some sort of API key/secret before you can connect to them.
  44. 1. Go to Tools > Keyring > Add New
  45. 2. Click the name of a service in the bottom section, or 'Manage' next to one of the services in the top section
  46. 3. Enter your API details (you will need to get those from the specific service)
  47. 4. Click 'Save Changes'
  48. 5. Now you should be able to create a new connection to that service
  49. = How do I connect to 'x' service? =
  50. 1. Go to Tools > Keyring > Add New
  51. 2. Click the name of the service in the top section (if it's in the bottom section, then that service has not been configured for API access yet, see above)
  52. 3. Follow through any authentication prompts to connect
  53. 4. You should now be connected, and your connection details should be listed on the Keyring admin page (which you will be redirected to once authentication is complete)
  54. = Now what? =
  55. Keyring just provides a framework for handling connections to external services. You need to download another plugin which makes use of Keyring to do anything useful (e.g. an importer or content-syncing plugin).
  56. = How does Keyring store tokens? =
  57. * By default, on a single-site install, Keyring stores tokens in your wp_posts table with a custom post type of 'keyring_token'
  58. * Coming soon, Keyring will store tokens for a multi-site install in a specified blog/site's wp_posts (so you can set a single site aside for just token storage if you like)
  59. * Keyring provides a framework for you to write your own token storage engine (see store.php and includes/stores/).
  60. = How do I add to the list of services Keyring can connect to? =
  61. Add files to includes/services/extended/ that either implement one of the includes/services/core/ service foundations, or start from scratch. Follow one of the existing service definitions for a template, and see service.php in the root of Keyring for some detail on methods you need to define, and optional ones that might make your life easier.
  62. == Changelog ==
  63. = 1.5.1 =
  64. * Remove example OAuth application included within that library. Unnecessary and contains an XSS vulnerability.
  65. = 1.5 =
  66. * Enhancement: Added Moves as a service
  67. * Bugfix: OAuth2 services were having querystring parameters stripped during POST requests. No longer doing that.
  68. * Bugfix: typo in profile request for RunKeeper service
  69. = 1.4 =
  70. * WARNING: BREAKING CHANGES
  71. * BREAKING: Depending on where you were loading Keyring, the new filtering on 'keyring_admin_url' might require some changes on your end
  72. * BREAKING: Credentials for Services are handled slightly differently now (especially if you were using constants), so confirm they are loading before rolling out this update
  73. * Introduce concept of "is_configured()" to Services so that you can test if a service has been set up correctly before attempting to use it
  74. * Change get_credentials() so that it checks for a service-specific _get_credentials(), then generic constants, then in the DB
  75. * get_credentials() is now always called when initiating a service, to load its details from the most appropriate place available
  76. * In the default Admin UI, split services out to show which ones are configured/ready to connect and which ones need attention
  77. * Add extensive helper instructions to the configuration pages for apps with links to where you need to go to register etc
  78. * Update Twitter requests to 1.1 endpoint, ready for them retiring v1
  79. * Keep track of request response codes (Props justinshreve)
  80. * Start adding some additional information to Keyring::error() for better handling
  81. = 1.3 =
  82. * Added Service definitions for Instapaper (paid account required) and TripIt
  83. * Improved access and request token filters
  84. * Specify request token in token query for custom storage engines that don't use globally-unique ids
  85. * Pass request token to verification of access tokens
  86. * Make Keyring::init() be callable after init (it will trigger everything it needs automatically)
  87. * Changed admin UI to use ListTable
  88. = 1.2 =
  89. * WARNING: BREAKING CHANGES
  90. * Huge overhaul of codebase to support Request tokens, passing reference via 'state' param (BREAKING)
  91. * Shuffled around how tokens are managed so that more places explicitly expect a Keyring_Token (BREAKING)
  92. * Force serialization of stored tokens when using SingleStore (BREAKING)
  93. * Big cleanup/changes to how token storage works, and how Keyring_Store looks (BREAKING)
  94. * Standardized handling of meta with tokens (BREAKING)
  95. * Added RunKeeper Service definition
  96. * Added a bunch of filters and tried to standardize them everywhere
  97. * Improve some nonce checking
  98. * Improved debugging information for different service types
  99. * Introduced app_ids for services that support/require them
  100. * Removed all wp_die()s in favor of Keyring::error(); exit;
  101. * Introduced test_connection() methods, props pento
  102. * Whitespace/alignment cleanup
  103. * Switched to using stable-tagging system in the WP.org repo
  104. = 1.1 =
  105. * First tagged version