NAME

Net::OpenID::Consumer - library for consumers of OpenID identities

SYNOPSIS

use Net::OpenID::Consumer;

my $csr = Net::OpenID::Consumer->new;

# set the user-agent (defaults to LWP::UserAgent, which isn't safe)
$csr->ua(LWPx::ParanoidAgent->new);

# set how the consumer gets to your web environment's GET arguments
$csr->args(\%hash);   # hashref of get args/values
$csr->args($r);       # Apache
$csr->args($aprreq);  # Apache::Request
$csr->args($cgi);     # CGI.pm
$csr->args(sub {});   # subref that returns value, given arg

# a user entered, say, "bradfitz.com" as their identity.  The first
# step is to fetch that page, parse it, and get a
# Net::OpenID::ClaimedIdentity object:

my $claimed_identity = $csr->claimed_identity("bradfitz.com");

# now your app has to send them at their identity server's endpoint
# to get redirected to either a positive assertion that they own
# that identity, or where they need to go to login/setup trust/etc.

my $check_url = $claimed_identity->check_url(
  return_to  => "http://example.com/openid-check.app?yourarg=val",
  post_grant => "close",
  trust_root => "http://example.com/",
);

# so you send the user off there, and then they come back to
# openid-check.app, then you see what the identity server said;

if (my $setup_url = $csr->user_setup_url) {
     # redirect/link/popup user to $setup_url
} elsif (my $vident = $csr->verified_identity) {
     my $verified_url = $vident->url;
     print "You are $verified_url !";
} else {
     die "Error validating identity: " . $csr->err;
}

DESCRIPTION

This is the Perl API for (the consumer half of) OpenID, a distributed identity system based on proving you own a URL, which is then your identity. More information is available at:

http://www.danga.com/openid/

CONSTRUCTOR

new

my $csr = Net::OpenID::Consumer->new([ %opts ]);

You can set the ua and args in the constructor.

METHODS

$csr->ua($user_agent)

$csr->ua

Getter/setter for the LWP::UserAgent (or subclass) instance which will be used when web donwloads are needed. It's highly recommended that you use LWPx::ParanoidAgent, or at least read its documentation so you're aware of why you should care.

$csr->args($ref)

$csr->args($param)

$csr->args

Can be used in 1 of 3 ways:

1. Setting the way which the Consumer instances obtains GET parameters:

$csr->args( $reference )

Where $reference is either a HASH ref, CODE ref, Apache $r, Apache::Request $apreq, or CGI.pm $cgi. If a CODE ref, the subref must return the value given one argument (the parameter to retrieve)

2. Get a paramater:

my $foo = $csr->args("foo");

When given an unblessed scalar, it retrieves the value. It croaks if you haven't defined a way to get at the parameters.

3. Get the getter:

my $code = $csr->args;

Without arguments, returns a subref that returns the value given a parameter name.

$csr->claimed_identity($url)

Given a user-entered $url (which could be missing http://, or have extra whitespace, etc), returns either a Net::OpenID::ClaimedIdentity object, or undef on failure.

Note that this identity is NOT verified yet. It's only who the user claims they are, but they could be lying.

$csr->user_setup_url( [ %opts ] )

Returns the URL the user must return to in order to login, setup trust, or do whatever the identity server needs them to do in order to make the identity assertion which they previously initiated by entering their claimed identity URL. Returns undef if this setup URL isn't required, in which case you should ask for the verified_identity.

The base URL this this function returns can be modified by using the following options in %opts:

post_grant

What you're asking the identity server to do with the user after they setup trust. Can be either return or close to return the user back to the return_to URL, or close the browser window with JavaScript. If you don't specify, the behavior is undefined (probably the user gets a dead-end page with a link back to the return_to URL). In any case, the identity server can do whatever it wants, so don't depend on this.

$csr->verified_identity

Returns a Net::OpenID::VerifiedIdentity object, or undef. Verification includes double-checking the reported identity URL declares the identity server, getting the DSA public key, verifying the signature, etc.

$csr->server_selector

Get/set the optional subref that selects which openid server to check against, if the user has declared multiple. By default, if no server_selector is declared, the first is always chosen.

$csr->err

Returns the last error, in form "errcode: errtext"

$csr->errcode

Returns the last error code.

$csr->errtext

Returns the last error text.

$csr->json_err

Returns the last error code/text in JSON format.

COPYRIGHT

This module is Copyright (c) 2005 Brad Fitzpatrick. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file. If you need more liberal licensing terms, please contact the maintainer.

WARRANTY

This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.

SEE ALSO

OpenID website: http://www.danga.com/openid/

Net::OpenID::ClaimedIdentity -- part of this module

Net::OpenID::VerifiedIdentity -- part of this module

Net::OpenID::Server -- another module, for acting like an OpenID server

AUTHORS

Brad Fitzpatrick <brad@danga.com>