Net::OpenID::Consumer(3pm) | User Contributed Perl Documentation | Net::OpenID::Consumer(3pm) |
NAME¶
Net::OpenID::Consumer - Library for consumers of OpenID identitiesVERSION¶
version 1.13SYNOPSIS¶
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 { # (OpenID 2) retry request in checkid_setup mode # (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; }
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://openid.net/
CONSTRUCTOR¶
- new
-
my $csr = Net::OpenID::Consumer->new( %options );
METHODS¶
State¶
- $csr->message($key)
- Returns the value for the given key/field from the OpenID
protocol message contained in the request URL parameters (i.e., the value
for the URL parameter "openid.$key"). This can only be used to
obtain core OpenID fields not extension fields.
- $csr->err
- Returns the last error, in form "errcode: errtext", as set by the various handlers below.
- $csr->errcode
- Returns the last error code. See Error Codes below.
- $csr->errtext
- Returns the last error text.
- $csr->json_err
- Returns the last error code/text in JSON format.
Configuration¶
- $csr->ua($user_agent)
- $csr->ua
- Getter/setter for the LWP::UserAgent (or subclass) instance which will be used when direct HTTP requests to a provider 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->cache($cache)
- $csr->cache
- Getter/setter for the cache instance which is used for
storing fetched HTML or XRDS pages, keys for associations with identity
providers, and received response_nonce values from positive provider
assertions.
- $csr->consumer_secret($scalar)
- $csr->consumer_secret($code)
-
$code = $csr->B<consumer_secret>; ($secret) = $code->($time);
- $csr->minimum_version(2)
- $csr->minimum_version
- Get or set the minimum OpenID protocol version supported.
Currently the only useful value you can set here is 2, which will cause
1.1 identifiers to fail discovery with the error
"protocol_version_incorrect" and responses from version 1
providers to not be recognized.
- $csr->args($ref)
- $csr->args($param)
- $csr->args
- Can be used in 1 of 3 ways:
- 1.
- Set the object from which URL parameter names and values
are to be retrieved:
$csr->args( $reference )
- •
- given a single parameter name argument, return the corresponding parameter value, and,
- •
- given no arguments at all, return the full list of parameter names from the request.
- 2.
- Get a parameter value:
my $foo = $csr->args("foo");
- 3.
- Get the parameter getter:
my $code = $csr->args;
- $csr->required_root($url_prefix)
- $csr->required_root
- Gets or sets the string prefix that, if nonempty, all return_to URLs must start with. Messages with return_to URLS that don't match will be considered invalid (spoofed from another site).
- $csr->assoc_options(...)
- $csr->assoc_options
- Get or sets the hash of parameters that determine how associations with identity providers will be made. Available options include:
- "assoc_type"
- Association type, (default 'HMAC-SHA1')
- "session_type"
- Association session type, (default 'DH-SHA1')
- "max_encrypt"
- (boolean) Use best encryption available for protocol version for both session type and association type. This overrides "session_type" and "assoc_type"
- "session_no_encrypt_https"
- (boolean) Use an unencrypted session type if the ID provider URL scheme is "https:". This overrides "max_encrypt" if both are set.
- "allow_eavesdropping"
- (boolean) Because it is generally a bad idea, we abort assocations where an unencrypted session over a non-SSL connection is called for. However the OpenID 1.1 specification technically allows this, so if that is what you really want, set this flag true. Ignored under protocol version 2.
- $csr->nonce_options(...)
- $csr->nonce_options
- Gets or sets the hash of options for how response_nonce
should be checked.
- "nocheck"
- (boolean) Skip response_nonce checking entirely. This
overrides all other nonce_options.
- "lifetime"
- (integer) Cache entries for nonces will expire after this
many seconds.
- "ignoretime"
- (boolean) Do not do any checking of timestamps, i.e., only test whether nonce is in the cache. This overrides all other nonce options except for "lifetime" and "nocheck"
- "skew"
- (integer) Number of seconds that a provider clock can be
ahead of ours before we deem it to be misconfigured.
- "start"
- (integer) Reject nonces where timestamp minus
"skew" is earlier than "start" (absolute seconds;
default is zero a.k.a. midnight 1/1/1970 UTC)
- "window"
- (integer) Reject nonces where timestamp minus
"skew" is more than "window" seconds ago. Zero or
negative values of "window" are treated as infinite (i.e., allow
everything).
- "timecop"
- (boolean) Reject nonces from The Future (i.e., timestamped
more than "skew" seconds from now).
Performing Discovery¶
- $csr->claimed_identity($url)
- Given a user-entered $url (which could be missing http://,
or have extra whitespace, etc), converts it to canonical form, performs
partial discovery to confirm that at least one provider endpoint exists,
and returns a Net::OpenID::ClaimedIdentity object, or, on failure of any
of the above, returns undef and sets last error ($csr-> err).
Handling Provider Responses¶
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.- $csr->handle_server_response( %callbacks );
- When a request comes in that contains a response from an
OpenID provider, figure out what it means and dispatch to an appropriate
callback to handle the request. This is the callback-based alternative to
explicitly calling the methods below in the correct sequence, and is
recommended unless you need to do something strange.
- "not_openid"
- the request isn't an OpenID response after all.
- "setup_needed"
- a checkid_immediate mode request was rejected, indicating that the provider requires user interaction.
- "cancelled"
- the user cancelled the authentication request from the provider's UI.
- "verified ($verified_identity)"
- the user's identity has been successfully verified. A Net::OpenID::VerifiedIdentity object is passed in.
- "error ($errcode, $errmsg)"
- an error has occured. An error code and message are provided. See Error Codes below for the meanings of the codes.
- "setup_required ($setup_url)"
- [DEPRECATED] a checkid_immediate mode request was
rejected and $setup_url was provided.
- $csr->is_server_response
- Returns true if a set of URL parameters has been supplied (via $csr-> args) and constitutes an actual OpenID protocol message.
- $csr->setup_needed
- Returns true if a checkid_immediate request failed because
the provider requires user interaction. The correct action to take at this
point depends on the OpenID protocol version
N.B.: While some providers have been
known to supply the "user_setup_url" parameter in Version 2
"setup_needed" responses, you cannot rely on this, and,
moreover, since the OpenID 2.0 specification has nothing to say about the
meaning of such a parameter, you cannot rely on it meaning anything in
particular even if it is supplied.
- $csr->user_setup_url( [ %opts ] )
- (Version 1 only) Returns the URL the user must return to in order to login, setup trust, or do whatever the identity provider needs them to do in order to make the identity assertion which they previously initiated by entering their claimed identity URL.
N.B.: Checking whether
"user_setup_url" is set in order to determine whether a
checkid_immediate request failed is DEPRECATED and will fail under OpenID 2.0.
Use "setup_needed()" instead.
- "post_grant"
- What you're asking the identity provider 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 provider can do whatever it wants, so don't depend on this.
- $csr->user_cancel
- Returns true if the user declined to share their identity,
false otherwise. (This function is literally one line: returns true if
"openid.mode" eq "cancel")
- $csr->verified_identity( [ %opts ] )
- Returns a Net::OpenID::VerifiedIdentity object, or returns
undef and sets last error ($csr-> err). Verification includes
double-checking the reported identity URL declares the identity provider,
verifying the signature, etc.
- "required_root"
- Sets the required_root just for this request. Values returns to its previous value afterwards.
ERROR CODES¶
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.- "provider_error"
- (A) The protocol message is a (2.0) error mode (i.e., "openid.mode = 'error'") message, typically used for provider-specific error reponses. Use $csr-> message to get at the "contact" and "reference" fields.
- "empty_url"
- (C) Tried to do discovery on an empty or all-whitespace string.
- "bogus_url"
- (C) Tried to do discovery on a non-http:/https: URL.
- "protocol_version_incorrect"
- (C) None of the ID providers found support even the minimum protocol version ($csr-> minimum_version)
- "no_identity_server"
- (CV) Tried to do discovery on a URL that does not seem to have any providers at all.
- "bad_mode"
- (SV) The "openid.mode" was expected to be "id_res" (positive assertion or, in version 1, checkid_immediate failed).
- "no_identity"
- (V) The "openid.identity" parameter is missing.
- "no_sig"
- (V) The "openid.sig" parameter is missing.
- "no_return_to"
- (V) The "openid.return_to" parameter is missing
- "bogus_return_to"
- (V) The "return_to" URL does not match $csr->required_root
- "nonce_missing"
- (V) The "openid.response_nonce" parameter is missing.
- "nonce_reused"
- (V) A previous assertion from this provider used this response_nonce already. Someone may be attempting a replay attack.
- "nonce_format"
- (V) Either the response_nonce timestamp was not in the correct format (e.g., tried to have fractional seconds or not UTC) or one of the components was out of range (e.g., month = 13).
- "nonce_future"
- (V) "timecop" was set and we got a response_nonce that was more than "skew" seconds into the future.
- "nonce_stale"
- (V) We got a response_nonce that was either prior to the start time or more than window seconds ago.
- "time_expired"
- (V) The return_to signature time ("oic.time") is from too long ago.
- "time_in_future"
- (V) The return_to signature time ("oic.time") is too far into the future.
- "time_bad_sig"
- (V) The HMAC of the return_to signature ("oic.time") is not what it should be.
- "server_not_allowed"
- (V) None of the provider endpoints found for the given ID match the server specified by the "openid.op_endpoint" parameter (OpenID 2 only).
- "unexpected_url_redirect"
- (V) Discovery for the given ID ended up at the wrong place
- "bogus_delegation"
- (V) Asserted identity ("openid.identity") does not match claimed_id or local_id/delegate.
- "unsigned_field"
- (V) In OpenID 2.0, "openid.op_endpoint", "openid.return_to", "openid.response_nonce", and "openid.assoc_handle" must always be signed, while "openid.claimed_id" and "openid.identity" must be signed if present.
- "expired_association"
- (V) "openid.assoc_handle" is for an association that has expired.
- "signature_mismatch"
- (V) An attempt to confirm the positive assertion using the association given by "openid.assoc_handle" failed; the signature is not what it should be.
- "naive_verify_failed_network"
- (V) An attempt to confirm the positive assertion via direct contact (check_authentication) with the provider failed with no response or a bad status code (!= 200).
- "naive_verify_failed_return"
- (V) An attempt to confirm a positive assertion via direct contact (check_authentication) received an explicitly negative response ("openid.is_valid = FALSE").
PROTOCOL VARIANCES¶
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:- 1.
- Are wildcards allowed in realms? Yes.
- 2.
- N/A.
- 3.
- Types of claimed identifiers accepted. HTTP or HTTPS
- 4.
- Are self-issued certificates allowed for authentication? Depends entirely on the user agent ("ua" ) supplied. LWP::UserAgent, as of version 6.0, can be configured to only accept connections to sites with certificates deriving from a set of trusted roots.
- 5.
- Must the XRDS file be signed? No.
- 6.
- Must the XRDS file be retrieved over secure channel? No.
- 7.
- What types of session types can be used when creating associations? Any of "no-encryption","DH-SHA1","DH-SHA256"
- 8.
- N/A.
- 9.
- N/A.
- 10.
- Must the association request take place over a secure channel? If the session type is "no-encryption" , then Yes for version 2.0 providers and likewise for version 1.1 providers if "allow_eavesdropping" is not set, otherwise No.
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.MAILING LIST¶
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 <http://groups.google.com/group/openid-perl>.SEE ALSO¶
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/serverAUTHORS¶
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>2012-03-18 | perl v5.14.2 |