WordPress: Keyring Developer’s Guide

Download Keyring from the WordPress.org Plugin Repository.

Keyring is a generalized framework for WordPress which handles authentication with, and authenticated requests to remote services. It provides a set of predefined “Services” which describe how to communicate with a collection of popular platforms, and also makes it easy for you to plug into that framework and define your own Services for other systems.

Written as a plugin for WordPress, Keyring may be run in “headless” mode to provide completely white-labeled authentication/communication functionality, or with a simple UI to allow users to manage their connections. On its own, Keyring does not “do” anything useful for an end user. It is built purely with the developer in mind, to make your life easier when integrating with other services. Using Keyring means you no longer need to care about OAuth or HTTP Basic, or how to sign requests or anything else — you request a secure connection from Keyring and if one is available, you will be provided with a simple, standard way of talking to that service. If there is no connection available, then the user will be taken through any authorization process and then the finalized connection will be returned to your plugin upon completion.

In this documentation, we’ll look at the architecture of Keyring, how the pieces work together and how you can extend Keyring by writing your own Services and Token Stores, plus implementing it as the authentication/communication layer in your own plugins/themes.

Tell Me What You Think

  1. Ryan said:

    awesome! i’ve been working on a similar project for a while. it imports your posts and other content from facebook, twitter, etc. into blogging platforms like wordpress, tumblr, and blogger. it doesn’t dive as deeply into wordpress in particular, but trades that for breadth across the other destination platforms.

    https://github.com/snarfed/freedom

    it uses another project, https://github.com/snarfed/activitystreams-unofficial , to translate the data from each source platform to a common format (ActivityStreams), before converting it again to each destination format.

    i’m glad to see more people working on these kinds of IndieWeb projects!

    • Beau said:

      Nice work Ryan! I was involved with the ActivityStreams spec team way back when, so have been interested in this stuff for a while :)

      I see you’ve done some work on pulling in comments/conversation happening around your content on other networks as well — I’ll be looking at doing that with Keyring/my importers at some point.

      Stay in touch!

  2. Peter said:

    Hi Beau, great job! this plugin is awesome! just what i needed.
    A little question, i looked but i have not found, what is the license of the plugin !?

    • Beau said:

      Thanks, and I really should add the license into the docs :)

      It’s GPLv2 or later, per the requirements to be in the WP.org plugin directory.

  3. Beau, just a question for a work-around
    (I am not that smart myself within PHP)

    – I seen in the code that it is checking on images being imported already.

    That’s a problem for me when I want to import in 1 blog my wifes instagram pics and my own instagram pics (we have a project with a hashtag and we want to import all instagram pics with that hashtag.

    Your plugin does import all my images properly, with a very very nice date save, tags etc.. perfect !

    But after the import of my +900 pics (thats working after fixing a fcgi issue)
    images of my wife are seen as duplicate (25x) and all other images are not retrieved.

    It would be awesome if I could import those images as well

    any hints, tips / work around how to achieve this?

    Thanks for this wonderful plugin so far ;-)

    • Beau said:

      It sounds like you’re using the Keyring Social Importers, in addition to Keyring. I guess it’s hitting a full page of duplicates, and then bailing from checking the rest, because it doesn’t import anything in a full batch?

      As a hack, you could try removing the check in keyring-importer-instagram.php around line 226:

      // If we’re doing a normal import and the last request was all skipped, then we’re at “now”
      if ( !$this->auto_import && self::NUM_PER_REQUEST == $skipped )
      $this->finished = true;

      Remove that whole block, and see what that does for you. It might leave you in an infinite loop though, so you’d need to manually bail out of the import.

      • Correct, I am using that plugin.
        The loop is working, but not any import.
        the problem seems that there are already 921 instagram posts (from user1)
        that import *the initial one* was working flawlessly.

        Now I am finished with one user, and I need to switch to the 2nd user cause in that account I have also around 500 instagram posts which I have to import before I can make a selection what I do not need.

        I delete the information from the keyring from that user, than I add the info from user2, I have also made credentials/secrets under that account on the developer site of instagram. I am authenticated .. now I press import
        but still 0 images to be imported.

        (unfortunately) .. ;_)

        • Beau said:

          Ah, I think I see what’s happening then; it’s because basically the importers are currently written assuming only a single user. I need to make some pretty significant changes to support simultaneous users on the same blog unfortunately.

          Off the top of my head, the only way I can think that you might be able to make this work is to import everything on a different blog entirely, then export all of your posts/media, and import that WXR/WordPress file into the main one.

          I’d have to have a think about exactly how to support multi-users.

          • np,
            just after writing above I installed a new plugin DsgnWrks Instagram, seems to do the similar. BIggest issue was if the plugin is importing the image with correct date.

            So if you have spare time, otherwise … ;);-) .. thanks for feedback !