API

willnorris edited this page Jan 24, 2012 · 1 revision
Clone this wiki locally

Stored Data

The OpenID plugin stores data in various WordPress tables, as outlined here.

Options

The following global settings are stored in the options table:

  • openid_enable_commentform - (boolean) causes some jQuery to be included at the bottom of a post's comment form which adds the OpenID logo and such to the URL field.

  • openid_enable_approval - (boolean) auto-approves comments left with OpenIDs. This is really more of a placeholder option that can/will be replaced down the road with a more robust OpenID reputation or trust engine.

  • openid_no_require_name - (boolean) bypasses the check for name and email address for comments left with a verified OpenID.

  • openid_required_for_registration - (boolean) if you have your blog set to allow anyone to register, enabling this option will require that new registrations happen with an OpenID. It does not currently prevent a new user from then setting a password that can be used in the future.

  • openid_blog_owner - (string) if set, this is the username of the local user who's OpenID Provider preferences will be copied to the blog's home URL. This will prevent any other users from using the ID Select feature of OpenID 2.0.

  • openid_comment_displayname_length - (int) controls the number of characters in the URL path that are displayed when an OpenID is used as a commenter's display name. (default: 12)

  • openid_associations - (serialized) array of OpenID associations... don't mess with this.

  • openid_nonces - (serialized) array of OpenID nonces... don't mess with this.

  • openid_plugin_enabled - (boolean) internal option to track if the plugin is having problems... don't mess with this.

  • openid_plugin_revision - (string) current revision of the plugin (mostly accurate).

  • openid_db_revision - (string) last revision of the plugin that included database changes.

  • name_user_roles - (serialized) this is a built-in WordPress option, so the plugin certainly doesn't modify it directly. It does however add the capability named "use_openid_provider" that controls which user roles are allowed use their author URLs as OpenIDs (either using the local OpenID provider, or delegating elsewhere).

  • openid_xrds_returnto - (boolean) hidden option that allows sites to turn off the OpenID 2.0 return_to service in their published XRDS document. This may be necessary due to bugs in some OpenID libraries. Defaults to true.

  • openid_xrds_idib - (boolean) hidden option that allows sites to turn off the Identity In The Browser service in their published XRDS document. Defaults to true.

  • openid_xrds_eaut - (boolean) hidden option that allows sites to turn off the EAUT Mapper service in their published XRDS document. Defaults to true.

User Meta

The following options are stored per user in the usermeta table:

  • openid_delegate - (string) the OpenID the user is delegating to. Right now this is a single OpenID, but will change to an array down the road. At that time, users will be able to delegate to multiple OpenIDs to allow for failover. If the user is not delegating, but using the local OpenID provider, this will option will be empty.

  • openid_delegate_services - (serialized) when a user sets their delegate OpenID, the services supported by the delegate OpenID provider are discovered and cached here.

  • openid_trusted_sites - (serialized) array of a user's trusted relying parties.

Post Meta

Previous versions of the plugin added an 'openid' column to the comments table to track which comments were left using an OpenID. That has been removed in version 3.0 of the plugin, and this data is instead stored in the postmeta table:

  • openid_comments - (serialized) array of the comment IDs of comments to this post which were left using OpenID.

OpenID Identities

The plugin adds one table to the WordPress database named 'openid_identities'. This table keeps track of the OpenIDs associated with each user. The current schema is not ideal, but I've opted not to mess with it in order to ensure an easier upgrade path from previous versions of the plugin. If this bug is ever fixed in WordPress, I plan do away with this table entirely. The current table columns:

  • uurl_id - (int(20)) unique ID for each table row

  • user_id - (int(20)) ID of the WordPress user this OpenID is associated with (foreign key: users.ID)

  • url - (text) full OpenID URL

  • hash - (char(32)) md5 hash of URL. Used to ensure uniqueness of url field.

Hidden Options

In addition to the hidden options mentioned above in the WordPress options table, the following constants effect the behavior of the plugin. They should be defined in wp-config.php.

  • CUSTOM_OPENID_IDENTITY_TABLE - (string) by default, the OpenID Identities table is of the form $wpdb->prefix . 'openid_identites'. If you have multiple WordPress installations that share users, you can define a custom name for this table so that it can be shared.

  • OPENID_DISALLOW_OWNER - (boolean) this prevents the blog owner option from being available. This may be useful to multi-user blogs that want to ensure that no one user of the blog sets themselves as the blog owner, thereby breaking all users' ability to use ID Select.

  • OPENID_NO_AUTO_TRUST - (boolean) by default, when a user approves an authentication request from a relying party, the site is immediately set as a "Trusted Site". This is in contrast to most OpenID providers which have an additional button or checkbox that allows the user to designate whether they want to trust the site in the future or not. This new interface was designed to better represent how most users use OpenID, as well as to streamline the trust request page. Setting this option will prevent sites from being added to the Trusted Sites list, and may be useful for debugging or development purposes.

  • OPENID_COMMENTS_POST_PAGE - (string) by default, WordPress comments are posted to wp-comments-post.php. If a user has renamed this page as an anti-spam measure, the constant will ensure that the OpenID plugin continues to post to the correct page.

  • WP_DEBUG - (boolean) this is a built-in WordPress constant that the OpenID plugin makes use of. When set, this will cause additional debugging statements to be printed to the error_log (not too many right now, but we intend to add more). It also causes the plugin to request the non-minimized versions of the CSS and Javascript files, which may be useful during debugging or development.

For Plugin Authors

Starting with version 3.0, there are a number of documented methods of extending the wp-openid plugin. Other plugins should only ever use the public methods or the hooks defined below for extending wp-openid. If additional functions or hooks are needed, please send a message to the DiSo mailing list.

Public Functions

Public functions are present and fully documented in the file openid.php. They are listed here for reference, but the documentation in the code is much more in-depth.

  • is_user_openid - checks if a specified user has an active OpenID connected with their account.

  • is_comment_openid - checks if a specified comment was left with an OpenID or by a user who has an active OpenID.

  • get_user_openids - get a list of all the OpenIDs connected with a specified user.

  • get_user_by_openid - get the ID of the user connected with the specified OpenID.

  • openid_input - get an HTML input field for inputting OpenIDs. This is useful if the openid_enable_commentform option doesn't work for your theme, or you wish to have a separate OpenID field.

  • get_userdata_by_various - convenience function which allows getting user data by username, user_id, or for the current user.

Extending the OpenID Consumer

The OpenID Consumer provides a small handful of hooks for use by other plugins.

  • openid_finish_auth - (action) After processing the OpenID authentication response, this action is called to allow the response to be acted on. Presently, the plugin implements this action in three cases: commenting, logging in through wp-login.php, and adding a new OpenID to an account in the profile management pages. Functions are passed one parameter:

    • string - the authenticated OpenID URL. If OpenID authentication failed for whatever reason, this will be null.
  • openid_page_head - (action) Various parts of the plugin need to display a page of data to the user, such as prompting the user to repost their comment anonymously after OpenID authentication has failed. This also occurs within the OpenID Provider when prompting the user to approve an authentication request. This action allows plugins to inject data into the page's element such as additional CSS or Javascript. Functions are not passed any parameters.

  • openid_auth_request_extensions - (filter) When making an authentication request, this filter is called to allow plugins attach additional extensions on the request. For example, the plugin itself will attach an simple registration attribute request on authentication requests to new OpenIDs. Functions are passed one parameter:

    • array - array of Auth_OpenID_Extension objects.
  • openid_user_data - (filter) when profile data is desired for a particular OpenID, this filter is called to collect that data. By default, the plugin implements simple registration attribute retrieval and data provided in the comment form. Other plugins can use this filter to implement attribute retrieval using AX, hCard, FOAF, etc. Functions are passed two parameters:

    • array - user data. see wp_insert_user for data used by WordPress.
    • string - OpenID the data is being collected for
  • openid_consumer_return_urls - (filter) OpenID advertises the authorized return URLs in its XRDS document, as suggested by the OpenID 2.0 spec. Plugins may add additional authorized return URLs with this filter. Functions are passed one parameter:

    • array - array of authorized return URLs

Extending the OpenID Provider

The built-in OpenID Provider includes a number of hooks which can be implemented to provide additional functionality. All of the simple registration (sreg) features of the OpenID Provider are provided using these hooks, as can be seen in the file server_ext.php.

  • openid_server_pre_auth - (action) This action is called when processing an OpenID authentication request, before checking if the current user is logged in. If a plugin wishes to hijack the authentication request, or needs to do its own internal setup that is not dependent on the user being logged in, this is the place to do it. If the authentication flow takes multiple steps (ie. having to authenticate the user and prompt them to approve the authentication request), then this action will be called during each HTTP request involved. Functions are passed one parameter:

    • object - the Auth_OpenID_Request object
  • openid_server_post_auth - (action) This action is called when processing an OpenID authentication request, after ensuring that the current user is logged in. If your plugin needs to do some internal setup but needs to know the user that is logged in, this is the place to do it. Like openid_server_pre_auth, this action is called on each HTTP request. Functions are passed one parameter:

    • object - the Auth_OpenID_Request object
  • openid_server_trust_form - (action) If necessary, the user will be prompted to approve the OpenID authentication request. This action allows a plugin to include additional information in the trust form. If your plugin needs to interact with the user, or simply needs to notify the user of something, this is the place to do it. Note that this form will only be displayed to the user if the relying party site is not already present in the user's list of "Trusted Sites". Functions are not passed any parameters.

  • openid_server_trust_submit - (action) This action allows plugins to process any input from the user gather from the trust form. Functions are passed two parameters:

    • boolean - whether the user approved the authentication request
    • object - the Auth_OpenID_Request object
  • openid_server_store_trusted_site - (filter) Whenever a user approves an authentication request, the relying party is added to the user's list of "Trusted Sites". Plugins are able to use this filter to add additional information about the site before it is stored in the database. Functions are passed one parameter:

    • array - information about the trusted site. By default, two keys are present - 'url' which is the trust root for the relying party, and 'last_login' which is the UNIX timestamp of the last time the user authenticated to this site.
  • openid_server_auth_response - (filter) This filter is called just before processing the authentication response and returning it to the relying party. Plugins can use this filter to add extensions to the response object. Functions are passed one parameter:

    • object - the Auth_OpenID_Response object
  • openid_server_xrds_types - (filter) This filter allows plugins to includes additional XRDS Types in the advertised OpenID Authentication services. Functions are passed one parameter:

    • array - current types to be included in the XRDS service. This should include at least either the OpenID 1.0 or the OpenID 2.0 type, so that plugins can limit their contributions to a specific OpenID protocol version.

Extending the OpenID Provider - Simple Registration

The Simple Registration OpenID extension defines 9 attributes which can be requested from an OpenID provider to aid a user in registering at a new relying party. The standard WordPress user profile is sufficient to populate three of these attributes: fullname, email, and nickname. For each sreg attribute a filter is called which allows other plugins to provide and/or override a value.

  • openid_server_sreg_* - (filter) where * is the attribute name. For example, the filter openid_server_sreg_gender allows plugins to provide a value for gender. Functions are passed two parameters:

    • string - the current value for the attribute
    • int - the user_id to retrieve attributes for