.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::OpenID::Server 3pm"
.TH Net::OpenID::Server 3pm "2022-12-12" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::OpenID::Server \- Library for building your own OpenID server/provider
.SH "VERSION"
.IX Header "VERSION"
version 1.09
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::OpenID::Server;
\&
\&  my $nos = Net::OpenID::Server\->new(
\&    args         => $cgi,
\&    get_user     => \e&get_user,
\&    get_identity => \e&get_identity,
\&    is_identity  => \e&is_identity,
\&    is_trusted   => \e&is_trusted,
\&    endpoint_url => "http://example.com/server.bml",
\&    setup_url    => "http://example.com/pass\-identity.bml",
\&  );
\&
\&  # 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\*(Aqs then your job to redirect them at the end to "return_to"
\&      # (or whatever you\*(Aqve named it in setup_map)
\&  } else {
\&      WebApp::set_content_type($type);
\&      WebApp::print($data);
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the Perl \s-1API\s0 for (the server half of) OpenID, a distributed
identity system based on proving you own a \s-1URL,\s0 which is then your
identity.  More information is available at:
.PP
.Vb 1
\&  http://openid.net/
.Ve
.PP
As of version 1.01 this module has support for both OpenID 1.1 and
2.0. Prior to this, only 1.1 was supported.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .IP "Net::OpenID::Server\->\fBnew\fR([ %opts ])" 4
.el .IP "Net::OpenID::Server\->\fBnew\fR([ \f(CW%opts\fR ])" 4
.IX Item "Net::OpenID::Server->new([ %opts ])"
You can set anything in the constructor options that there are
getters/setters methods for below.  That includes: args, get_user,
is_identity, is_trusted, setup_url, and setup_map.  See below for
docs.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "($type, $data) = $nos\->\fBhandle_page\fR([ %opts ])" 4
.el .IP "($type, \f(CW$data\fR) = \f(CW$nos\fR\->\fBhandle_page\fR([ \f(CW%opts\fR ])" 4
.IX Item "($type, $data) = $nos->handle_page([ %opts ])"
Returns a \f(CW$type\fR and \f(CW$data\fR, where \f(CW$type\fR can be:
.RS 4
.ie n .IP """redirect""" 4
.el .IP "\f(CWredirect\fR" 4
.IX Item "redirect"
\&... in which case you redirect the user (via your web framework's
redirect functionality) to the \s-1URL\s0 specified in \f(CW$data\fR.
.ie n .IP """setup""" 4
.el .IP "\f(CWsetup\fR" 4
.IX Item "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
\&\*(L"trust_root\*(R" in the hashref in \f(CW$data\fR, and then redirect them to
\&\*(L"return_to\*(R" at the end.  Note that the parameters in the \f(CW$data\fR hashref
are as you named them with setup_map.
.IP "Some content type" 4
.IX Item "Some content type"
Otherwise, set the content type to \f(CW$type\fR and print the page out, the
contents of which are in \f(CW$data\fR.
.RE
.RS 4
.Sp
The optional \f(CW%opts\fR may contain:
.ie n .IP """redirect_for_setup""" 4
.el .IP "\f(CWredirect_for_setup\fR" 4
.IX Item "redirect_for_setup"
If set to a true value, signals that you don't want to handle the
\&\f(CW\*(C`setup\*(C'\fR return type from handle_page, and you'd prefer it just be
converted to a \f(CW\*(C`redirect\*(C'\fR type to your already-defined \f(CW\*(C`setup_url\*(C'\fR,
with the arguments from setup_map already appended.
.RE
.RS 4
.RE
.ie n .IP "$url = $nos\->\fBsigned_return_url\fR( %opts )" 4
.el .IP "\f(CW$url\fR = \f(CW$nos\fR\->\fBsigned_return_url\fR( \f(CW%opts\fR )" 4
.IX Item "$url = $nos->signed_return_url( %opts )"
Generates a positive identity assertion \s-1URL\s0 that you'd redirect a user
to.  Typically this would be after they've completed your setup_url.
Once trust has been setup, the \f(CW\*(C`handle_page\*(C'\fR method will redirect you
to this signed return automatically.
.Sp
The \s-1URL\s0 generated is the consumer site's return_to \s-1URL,\s0 with a signed
identity included in the \s-1GET\s0 arguments.  The \f(CW%opts\fR are:
.RS 4
.ie n .IP """identity""" 4
.el .IP "\f(CWidentity\fR" 4
.IX Item "identity"
Required.  The identity \s-1URL\s0 to sign.
.ie n .IP """claimed_id""" 4
.el .IP "\f(CWclaimed_id\fR" 4
.IX Item "claimed_id"
Optional.  The claimed_id \s-1URL\s0 to sign.
.ie n .IP """return_to""" 4
.el .IP "\f(CWreturn_to\fR" 4
.IX Item "return_to"
Required.  The base of the \s-1URL\s0 being generated.
.ie n .IP """assoc_handle""" 4
.el .IP "\f(CWassoc_handle\fR" 4
.IX Item "assoc_handle"
The association handle to use for the signature.  If blank, dumb
consumer mode is used, and the library picks the handle.
.ie n .IP """trust_root""" 4
.el .IP "\f(CWtrust_root\fR" 4
.IX Item "trust_root"
Optional.  If present, the \f(CW\*(C`return_to\*(C'\fR \s-1URL\s0 will be checked to be within
(\*(L"under\*(R") this trust_root.  If not, the \s-1URL\s0 returned will be undef.
.ie n .IP """ns""" 4
.el .IP "\f(CWns\fR" 4
.IX Item "ns"
Optional.
.ie n .IP """additional_fields""" 4
.el .IP "\f(CWadditional_fields\fR" 4
.IX Item "additional_fields"
Optional.  If present, must be a hashref with keys starting with \*(L"\ew+\e.\*(R".
All keys and values will be returned in the response, and signed.  This is
used for OpenID extensions.
.RE
.RS 4
.RE
.ie n .IP "$url = $nos\->\fBcancel_return_url\fR( %opts )" 4
.el .IP "\f(CW$url\fR = \f(CW$nos\fR\->\fBcancel_return_url\fR( \f(CW%opts\fR )" 4
.IX Item "$url = $nos->cancel_return_url( %opts )"
Generates a cancel notice to the return_to \s-1URL,\s0 if a user
declines to share their identity.  \f(CW%opts\fR are:
.RS 4
.ie n .IP """return_to""" 4
.el .IP "\f(CWreturn_to\fR" 4
.IX Item "return_to"
Required.  The base of the \s-1URL\s0 being generated.
.RE
.RS 4
.RE
.ie n .IP "$nos\->\fBargs\fR" 4
.el .IP "\f(CW$nos\fR\->\fBargs\fR" 4
.IX Item "$nos->args"
Can be used in 1 of 3 ways:
.Sp
1. Setting the way which the Server instances obtains parameters:
.Sp
\&\f(CW$nos\fR\->args( \f(CW$reference\fR )
.Sp
Where \f(CW$reference\fR is either a \s-1HASH\s0 ref, \s-1CODE\s0 ref, Apache \f(CW$r\fR (for
get_args only), Apache::Request \f(CW$apreq\fR, or \s-1CGI\s0.pm \f(CW$cgi\fR.  If a \s-1CODE\s0
ref, the subref must return the value given one argument (the
parameter to retrieve)
.Sp
2. Get a paramater:
.Sp
my \f(CW$foo\fR = \f(CW$nos\fR\->get_args(\*(L"foo\*(R");
.Sp
When given an unblessed scalar, it retrieves the value.  It croaks if
you haven't defined a way to get at the parameters.
.Sp
3. Get the getter:
.Sp
my \f(CW$code\fR = \f(CW$nos\fR\->get_args;
.Sp
Without arguments, returns a subref that returns the value given a
parameter name.
.ie n .IP "$nos\->\fBget_user\fR($code)" 4
.el .IP "\f(CW$nos\fR\->\fBget_user\fR($code)" 4
.IX Item "$nos->get_user($code)"
.PD 0
.ie n .IP "$code = $nos\->\fBget_user\fR; $u = $code\->();" 4
.el .IP "\f(CW$code\fR = \f(CW$nos\fR\->\fBget_user\fR; \f(CW$u\fR = \f(CW$code\fR\->();" 4
.IX Item "$code = $nos->get_user; $u = $code->();"
.PD
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 \f(CW$u\fR) is
not touched.  It's simply given back to your other callbacks
(is_identity and is_trusted).
.ie n .IP "$nos\->\fBget_identity\fR($code)" 4
.el .IP "\f(CW$nos\fR\->\fBget_identity\fR($code)" 4
.IX Item "$nos->get_identity($code)"
.PD 0
.ie n .IP "$code = $nos\->\fBget_identity\fR; $identity = $code\->($u, $identity);" 4
.el .IP "\f(CW$code\fR = \f(CW$nos\fR\->\fBget_identity\fR; \f(CW$identity\fR = \f(CW$code\fR\->($u, \f(CW$identity\fR);" 4
.IX Item "$code = $nos->get_identity; $identity = $code->($u, $identity);"
.PD
For OpenID 2.0. Get/set the subref returning a identity. This is called
when claimed identity is 'identifier_select'.
.ie n .IP "$nos\->\fBis_identity\fR($code)" 4
.el .IP "\f(CW$nos\fR\->\fBis_identity\fR($code)" 4
.IX Item "$nos->is_identity($code)"
.PD 0
.ie n .IP "$code = $nos\->\fBis_identity\fR; $code\->($u, $identity_url)" 4
.el .IP "\f(CW$code\fR = \f(CW$nos\fR\->\fBis_identity\fR; \f(CW$code\fR\->($u, \f(CW$identity_url\fR)" 4
.IX Item "$code = $nos->is_identity; $code->($u, $identity_url)"
.PD
Get/set the subref which is responsible for returning true if the
logged in user \f(CW$u\fR (which may be undef if user isn't logged in) owns
the \s-1URL\s0 tree given by \f(CW$identity_url\fR.  Note that if \f(CW$u\fR 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.
.ie n .IP "$nos\->\fBis_trusted\fR($code)" 4
.el .IP "\f(CW$nos\fR\->\fBis_trusted\fR($code)" 4
.IX Item "$nos->is_trusted($code)"
.PD 0
.ie n .IP "$code = $nos\->\fBis_trusted\fR; $code\->($u, $trust_root, $is_identity)" 4
.el .IP "\f(CW$code\fR = \f(CW$nos\fR\->\fBis_trusted\fR; \f(CW$code\fR\->($u, \f(CW$trust_root\fR, \f(CW$is_identity\fR)" 4
.IX Item "$code = $nos->is_trusted; $code->($u, $trust_root, $is_identity)"
.PD
Get/set the subref which is responsible for returning true if the
logged in user \f(CW$u\fR (which may be undef if user isn't logged in) trusts
the \s-1URL\s0 given by \f(CW$trust_root\fR to know his/her identity.  Note that if
either \f(CW$u\fR is undef, or \f(CW$is_identity\fR 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.
.ie n .IP "$nos\->\fBserver_secret\fR($scalar)" 4
.el .IP "\f(CW$nos\fR\->\fBserver_secret\fR($scalar)" 4
.IX Item "$nos->server_secret($scalar)"
.PD 0
.ie n .IP "$nos\->\fBserver_secret\fR($code)" 4
.el .IP "\f(CW$nos\fR\->\fBserver_secret\fR($code)" 4
.IX Item "$nos->server_secret($code)"
.ie n .IP "$code = $nos\->\fBserver_secret\fR; ($secret) = $code\->($time);" 4
.el .IP "\f(CW$code\fR = \f(CW$nos\fR\->\fBserver_secret\fR; ($secret) = \f(CW$code\fR\->($time);" 4
.IX Item "$code = $nos->server_secret; ($secret) = $code->($time);"
.PD
The server secret is used to generate and sign lots of per-consumer
secrets, and is never handed out directly.
.Sp
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, all consumers that have cached their per-consumer secrets will
start failing, since their secrets no longer work.
.Sp
The recommended usage, however, is to supply a subref that returns a
secret based on the provided \fI\f(CI$time\fI\fR, a unix timestamp.  And if one
doesn't exist for that time, create, store and return it (with
appropriate locking so you never return different secrets for the same
time.)  Your secret can just be random characters, but it's your
responsibility to do the locking and storage.  If you want help
generating random characters, call \f(CW\*(C`Net::OpenID::Server::rand_chars($len)\*(C'\fR.
.Sp
Your secret may not exceed 255 characters.
.ie n .IP "$nos\->\fBsetup_url\fR($url)" 4
.el .IP "\f(CW$nos\fR\->\fBsetup_url\fR($url)" 4
.IX Item "$nos->setup_url($url)"
.PD 0
.ie n .IP "$url = $nos\->\fBsetup_url\fR" 4
.el .IP "\f(CW$url\fR = \f(CW$nos\fR\->\fBsetup_url\fR" 4
.IX Item "$url = $nos->setup_url"
.PD
Get/set the user setup \s-1URL.\s0  This is the \s-1URL\s0 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 \s-1URL\s0 in all three cases.  Your
setup \s-1URL\s0 may contain existing query parameters.
.ie n .IP "$nos\->\fBendpoint_url\fR($url)" 4
.el .IP "\f(CW$nos\fR\->\fBendpoint_url\fR($url)" 4
.IX Item "$nos->endpoint_url($url)"
.PD 0
.ie n .IP "$url = $nos\->\fBendpoint_url\fR" 4
.el .IP "\f(CW$url\fR = \f(CW$nos\fR\->\fBendpoint_url\fR" 4
.IX Item "$url = $nos->endpoint_url"
.PD
For OpenID 2.0. Get/set the op_endpoint \s-1URL.\s0
.ie n .IP "$nos\->\fBsetup_map\fR($hashref)" 4
.el .IP "\f(CW$nos\fR\->\fBsetup_map\fR($hashref)" 4
.IX Item "$nos->setup_map($hashref)"
.PD 0
.ie n .IP "$hashref = $nos\->\fBsetup_map\fR" 4
.el .IP "\f(CW$hashref\fR = \f(CW$nos\fR\->\fBsetup_map\fR" 4
.IX Item "$hashref = $nos->setup_map"
.PD
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, \*(L"trust_root\*(R",
\&\*(L"return_to\*(R", \*(L"identity\*(R", and \*(L"assoc_handle\*(R".  If you
don't like those parameter names, this \f(CW$hashref\fR 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.
.IP "Net::OpenID::Server\->rand_chars($len)" 4
.IX Item "Net::OpenID::Server->rand_chars($len)"
Utility function to return a string of \f(CW$len\fR random characters.  May be
called as package method, object method, or regular function.
.ie n .IP "$nos\->\fBerr\fR" 4
.el .IP "\f(CW$nos\fR\->\fBerr\fR" 4
.IX Item "$nos->err"
Returns the last error, in form \*(L"errcode: errtext\*(R";
.ie n .IP "$nos\->\fBerrcode\fR" 4
.el .IP "\f(CW$nos\fR\->\fBerrcode\fR" 4
.IX Item "$nos->errcode"
Returns the last error code.
.ie n .IP "$nos\->\fBerrtext\fR" 4
.el .IP "\f(CW$nos\fR\->\fBerrtext\fR" 4
.IX Item "$nos->errtext"
Returns the last error text.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This module is Copyright (c) 2005 Brad Fitzpatrick.
All rights reserved.
.PP
You may distribute under the terms of either the \s-1GNU\s0 General Public
License or the Artistic License, as specified in the Perl \s-1README\s0 file.
If you need more liberal licensing terms, please contact the
maintainer.
.SH "WARRANTY"
.IX Header "WARRANTY"
This is free software. \s-1IT COMES WITHOUT WARRANTY OF ANY KIND.\s0
.SH "MAILING LIST"
.IX Header "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 .
.SH "SEE ALSO"
.IX Header "SEE ALSO"
OpenID website:  http://openid.net/
.SH "AUTHORS"
.IX Header "AUTHORS"
Brad Fitzpatrick <brad@danga.com>