/ 
Net-OpenID-Server-0.03
River stage one • 3 direct dependents • 3 total dependents
/ Net::OpenID::Server

NAME

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

SYNOPSIS

use Net::OpenID::Server;

my $nos = Net::OpenID::Server->new(
  args         => $cgi,
  private_key  => \&get_priv_key_from_database,
  public_key   => "public_key.txt",
  get_user     => \&get_user,
  is_identity  => \&is_identity,
  is_trusted   => \&is_trusted
  setup_url    => "http://example.com/pass-identity.bml",
  setup_map    => { "post_grant" => "do_after_grant" },
);

# From your OpenID server endpoint:

my ($type, $data) = $nos->handle_page;
if ($type eq "redirect") {
    WebApp::redirect_to($data);
} elsif ($type eq "setup") {
    my %setup_opts = %$data;
    # ... show them setup page(s), with options from setup_map
    # it's then your job to redirect them at the end to "return_to"
    # (or whatever you've named it in setup_map)
} else {
    WebApp::set_content_type($type);
    WebApp::print($data);
}

DESCRIPTION

This is the Perl API for (the server 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

Net::OpenID::Server->new([ %opts ])

You can set anything in the constructor options that there are getters/setters methods for below. That includes: args, private_key, public_key, get_user, is_identity, is_trusted, setup_url, and setup_map. See below for docs.

METHODS

($type, $data) = $nos->handle_page

Returns a $type and $data, where $type can be:

redirect

... in which case you redirect the user (via your web framework's redirect functionality) to the URL specified in $data.

setup

... in which case you should show the user a page (or redirect them to one of your pages) where they can setup trust for the given "trust_root" in the hashref in $data, and then redirect them to "return_to" at the end. Note that the parameters in the $data hashref are as you named them with setup_map.

Some content type

Otherwise, set the content type to $type and print the page out, the contents of which are in $data.

$nos->args($ref)
$nos->args($param)
$nos->args

Can be used in 1 of 3 ways:

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

$nos->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 = $nos->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 = $nos->args;

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

$nos->public_key

Returns scalar with PEM-encoded public key.

$nos->public_key($key_arg)

Set the public_key. $key_arg can be a scalar with the PEM-encoded key, a scalar of the filename holding the public key, or a subref that returns the public key when requested.

$nos->private_key
$nos->private_key($key_arg)

Get/set private_key. Same interface as public_key.

$nos->get_user($code)
$code = $nos->get_user; $u = $code->();

Get/set the subref returning a defined value representing the logged in user, or undef if no user. The return value (let's call it $u) is not touched. It's simply given back to your other callbacks (is_identity and is_trusted).

$nos->is_identity($code)
$code = $nos->is_identity; $code->($u, $identity_url)

Get/set the subref which is responsible for returning true if the logged in user $u (which may be undef if user isn't logged in) owns the URL tree given by $identity_url. Note that if $u is undef, your function should always return 0. The framework doesn't do that for you so you can do unnecessary work on purpose if you care about exposing information via timing attacks.

$nos->is_trusted($code)
$code = $nos->is_trusted; $code->($u, $trust_root, $is_identity)

Get/set the subref which is responsible for returning true if the logged in user $u (which may be undef if user isn't logged in) trusts the URL given by $trust_root to know his/her identity. Note that if either $u is undef, or $is_identity is false (this is the result of your previous is_identity callback), you should return 0. But your callback is always run so you can avoid timing attacks, if you care.

$nos->setup_url($url)
$url = $nos->setup_url

Get/set the user setup URL. This is the URL the user is told to go to if they're either not logged in, not who they said they were, or trust hasn't been setup. You use the same URL in all three cases. Your setup URL may contain existing query parameters.

$nos->setup_map($hashref)
$hashref = $nos->setup_map

When this module gives a consumer site a user_setup_url from your provided setup_url, it also has to append a number of get parameters onto your setup_url, so your app based at that setup_url knows what it has to setup. Those keys are named, by default, "trust_root", "return_to", "post_grant", and "is_identity". If you don't like those parameter names, this $hashref setup_map lets you change one or more of them. The hashref's keys should be the default values, with values being the parameter names you want.

$nos->err

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

$nos->errcode

Returns the last error code.

$nos->errtext

Returns the last error text.

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/

AUTHORS

Brad Fitzpatrick <brad@danga.com>