| Net::OpenID::Consumer(3pm) | User Contributed Perl Documentation | Net::OpenID::Consumer(3pm) |
Net::OpenID::Consumer - Library for consumers of OpenID identities
version 1.18
use Net::OpenID::Consumer;
my $csr = Net::OpenID::Consumer->new(
ua => LWPx::ParanoidAgent->new,
cache => Cache::File->new( cache_root => '/tmp/mycache' ),
args => $cgi,
consumer_secret => ...,
required_root => "http://site.example.com/",
assoc_options => [
max_encrypt => 1,
session_no_encrypt_https => 1,
],
);
# Say a user enters "bradfitz.com" as his/her identity. The first
# step is to perform discovery, i.e., fetch that page, parse it,
# find out the actual identity provider and other useful information,
# which gets encapsulated in a Net::OpenID::ClaimedIdentity object:
my $claimed_identity = $csr->claimed_identity("bradfitz.com");
unless ($claimed_identity) {
die "not actually an openid? " . $csr->err;
}
# We can then launch the actual authentication of this identity.
# The first step is to redirect the user to the appropriate URL at
# the identity provider. This URL is constructed as follows:
#
my $check_url = $claimed_identity->check_url(
return_to => "http://example.com/openid-check.app?yourarg=val",
trust_root => "http://example.com/",
# to do a "checkid_setup mode" request, in which the user can
# interact with the provider, e.g., so that the user can sign in
# there if s/he has not done so already, you will need this,
delayed_return => 1
# otherwise, this will be a "check_immediate mode" request, the
# provider will have to immediately return some kind of answer
# without interaction
);
# Once you redirect the user to $check_url, the provider should
# eventually redirect back, at which point you need some kind of
# handler at openid-check.app to deal with that response.
# You can either use the callback-based API (recommended)...
#
$csr->handle_server_response(
not_openid => sub {
die "Not an OpenID message";
},
setup_needed => sub {
if ($csr->message->protocol_version >= 2) {
# (OpenID 2) retry request in checkid_setup mode (above)
}
else {
# (OpenID 1) redirect user to $csr->user_setup_url
}
},
cancelled => sub {
# User hit cancel; restore application state prior to check_url
},
verified => sub {
my ($vident) = @_;
my $verified_url = $vident->url;
print "You are $verified_url !";
},
error => sub {
my ($errcode,$errtext) = @_;
die("Error validating identity: $errcode: $errcode");
},
);
# ... or handle the various cases yourself
#
unless ($csr->is_server_response) {
die "Not an OpenID message";
} elsif ($csr->setup_needed) {
# (OpenID 2) retry request in checkid_setup mode
# (OpenID 1) redirect/link/popup user to $csr->user_setup_url
} elsif ($csr->user_cancel) {
# User hit cancel; restore application state prior to check_url
} elsif (my $vident = $csr->verified_identity) {
my $verified_url = $vident->url;
print "You are $verified_url !";
} else {
die "Error validating identity: " . $csr->err;
}
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://openid.net/
my $csr = Net::OpenID::Consumer->new( %options );
The following option names are recognized: "ua", "cache", "args", "consumer_secret", "minimum_version", "required_root", "assoc_options", and "nonce_options" in the constructor. In each case the option value is treated exactly as the argument to the corresponding method described below under Configuration.
Calling this method without a $key argument returns a Net::OpenID::IndirectMessage object representing the protocol message, at which point the various object methods are available, including
$csr->message->protocol_version
$csr->message->has_ext
$csr->message->get_ext
Returns undef in either case if no URL parameters have been supplied (i.e., because args() has not been initialized) or if the request is not an actual OpenID message.
The $cache object can be anything that has a ->get($key) and ->set($key,$value[,$expire]) methods. See URI::Fetch for more information. This cache object is passed to URI::Fetch directly.
Setting a cache instance is not absolutely required, But without it, provider associations will not be possible and the same pages may be fetched multiple times during discovery. It will also not be possible to check for repetition of the response_nonce, which may then leave you open to replay attacks.
$code = $csr->B<consumer_secret>; ($secret) = $code->($time);
The consumer secret is used to generate self-signed nonces for the return_to URL, to prevent spoofing.
In the simplest (and least secure) form, you configure a static secret value with a scalar. If you use this method and change the scalar value, any outstanding requests from the last 30 seconds or so will fail.
You may also supply a subref that takes one argument, $time, a unix timestamp and returns a secret.
Your secret may not exceed 255 characters.
For the best protection against replays and login cross-site request forgery, consumer_secret should additionally depend on something known to be specific to the client browser instance and not visible to an attacker. If "SSH_SESSION_ID" is available, you should use that. Otherwise you'll need to set a (Secure) cookie on the (HTTPS) page where the signin form appears in order to establish a pre-login session, then make sure to change this cookie upon successful login.
In most cases you'll want to allow both 1.1 and 2.0 identifiers, which is the default. If you want, you can set this property to 1 to make this behavior explicit.
$csr->args( $reference )
where $reference is either an unblessed "HASH" ref, a "CODE" ref, or some kind of "request object" — the latter being either a CGI, Apache, Apache::Request, Apache2::Request, or Plack::Request object.
If you pass in a "CODE" ref, it must,
If you pass in an Apache (mod_perl 1.x interface) object and this is a POST request, you must not have already called "$r->content" as this routine will be making said call itself in order to extract the request parameters.
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.
Most callers should instead use the "message" method above, which abstracts away the need to understand OpenID's message serialization.
my $code = $csr->args;
this being a subref that takes a parameter name and returns the corresponding value.
Most callers should instead use the "message" method above with no arguments, which returns an object from which extension attributes can be obtained by their documented namespace URI.
In OpenID 2.0, response_nonce is sent by the identity provider as part of a positive identity assertion in order to help prevent replay attacks. In the check_authentication phase, the provider is also required to not authenticate the same response_nonce twice.
The relying party is strongly encouraged but not required to reject multiple occurrences of a nonce (which can matter if associations are in use and there is no check_authentication phase). Relying party may also choose to reject a nonce on the basis of the timestamp being out of an acceptable range.
Available options include:
"nocheck" is implied and is the only possibility if $csr->cache is unset.
Defaults to the value of "window", below.
If "lifetime" is zero or negative, expiration times will not be set at all; entries will expire as per the default behavior for your cache (or you will need to purge them via some separate process).
If your cache implementation ignores the third argument on $entry->set() calls (see Cache::Entry), then this option has no effect beyond serving as a default for "window".
Default skew is 300 (5 minutes) or "window/2", if "window" is specified and "window/2" is smaller.
("skew" is treated as 0 if set negative, but don't do that).
Misconfiguration of the provider clock means its timestamps are not reliable, which then means there is no way to know whether or not the nonce could have been sent before the start of the cache window, which nullifies any obligation to detect all multiply sent nonces. Conversely, if proper configuration can be assumed, then the timestamp value minus "skew" will be the earliest possible time that we could have received a previous instance of this response_nonce, and if the cache is reliable about holding entries from that time forward, then (and only then) can one be certain that an uncached nonce instance is indeed the first.
If you know the start time of your HTTP server (or your cache server, if that is separate — or the maximum of the start times if you have multiple cache servers), you should use this option to declare that.
If "lifetime" is specified, "window" defaults to that. If "lifetime" is not specified, "window" defaults to 1800 (30 minutes), adjusted upwards if "skew" is specified and larger than the default skew.
On general principles, "window" should be a maximal expected propagation delay plus twice the "skew".
Values between 0 and "skew" (causing all nonces to be rejected) and values greater than "lifetime" (cache may fail to keep all nonces that are still within the window) are not recommended.
Note that rejecting future nonces is not required. Nor does it protect from anything since an attacker can retry the message once it has expired from the cache but is still within the time interval where we would not yet expect that it could expire — this being the essential problem with future nonces. It may, however, be useful to have warnings about misconfigured provider clocks — and hence about this insecurity — at the cost of impairing interoperability (since this rejects messages that are otherwise allowed by the protocol), hence this option.
In most cases it will be enough to either set "nocheck" to dispense with response_nonce checking entirely because some other (better) method of preventing replay attacks (see consumer_secret) has been implemented, or use "lifetime" to declare/set the lifetime of cache entries for nonces whether because the default lifetime is unsatisfactory or because the cache implementation is incapable of setting individual expiration times. All other options should default reasonably in these cases.
In order for the nonce check to be as reliable/secure as possible (i.e., that it block all instances of duplicate nonces from properly configured providers as defined by "skew", which is the best we can do), "start" must be no earlier than the cache start time and the cache must be guaranteed to hold nonce entries for at least "window" seconds (though, to be sure, if you can tolerate being vulnerable for the first "window" seconds of a server run, then you do not need to set "start").
Note that the identity returned is not verified yet. It's only who the user claims they are, but they could be lying.
If this method returns undef, an error code will be set. See Error Codes below.
The following routines are for handling a redirected provider response and assume that, among other things, $csr->args has been properly populated with the URL parameters.
Anything you return from the selected callback function will be returned by this method verbatim. This is useful if the caller needs to return something different in each case.
The available callbacks are:
For the sake of legacy code we also allow
Clients using this callback should be updated to use setup_needed at the earliest opportunity. Here $setup_url is the same as returned by $csr->user_setup_url.
(Version 1) Redirect to or otherwise make available a link to $csr->"user_setup_url".
(Version 2) Retry the request in checkid_setup mode; the provider will then issue redirects as needed.
The base URL that this function returns can be modified by using the following options in %opts:
It's then your job to restore your app to where it was prior to redirecting them off to the user_setup_url, using the other query parameters that you'd sent along in your return_to URL.
The options in %opts may contain:
If this method returns undef, an error code will be set. See Error Codes below.
This is the complete list of error codes that can be set. Errors marked with (C) are set by claimed_identity. Other errors occur during handling of provider responses and can be set by args (A), verified_identity (V), and user_setup_url (S), all of which can show up in the "error" callback for handle_server_response.
XRI-based identities are not supported.
Meanwhile, here are answers to the security profile questions from section 15.6 of the OpenID 2.0 specification <http://openid.net/specs/openid-authentication-2_0.html#anchor47> that are relevant to the Consumer/Relying-Party:
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.
This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
The Net::OpenID family of modules has a mailing list powered by Google Groups. For more information, see <http://groups.google.com/group/openid-perl>.
OpenID website: <http://openid.net/>
Net::OpenID::ClaimedIdentity -- part of this module
Net::OpenID::VerifiedIdentity -- part of this module
Net::OpenID::Server -- another module, for implementing an OpenID identity provider/server
Brad Fitzpatrick <brad@danga.com>
Tatsuhiko Miyagawa <miyagawa@sixapart.com>
Martin Atkins <mart@degeneration.co.uk>
Robert Norris <rob@eatenbyagrue.org>
Roger Crew <crew@cs.stanford.edu>
| 2022-06-30 | perl v5.34.0 |