1Net::OpenID::Server(3)User Contributed Perl DocumentationNet::OpenID::Server(3)
2
3
4

NAME

6       Net::OpenID::Server - Library for building your own OpenID
7       server/provider
8

VERSION

10       version 1.09
11

SYNOPSIS

13         use Net::OpenID::Server;
14
15         my $nos = Net::OpenID::Server->new(
16           args         => $cgi,
17           get_user     => \&get_user,
18           get_identity => \&get_identity,
19           is_identity  => \&is_identity,
20           is_trusted   => \&is_trusted,
21           endpoint_url => "http://example.com/server.bml",
22           setup_url    => "http://example.com/pass-identity.bml",
23         );
24
25         # From your OpenID server endpoint:
26
27         my ($type, $data) = $nos->handle_page;
28         if ($type eq "redirect") {
29             WebApp::redirect_to($data);
30         } elsif ($type eq "setup") {
31             my %setup_opts = %$data;
32             # ... show them setup page(s), with options from setup_map
33             # it's then your job to redirect them at the end to "return_to"
34             # (or whatever you've named it in setup_map)
35         } else {
36             WebApp::set_content_type($type);
37             WebApp::print($data);
38         }
39

DESCRIPTION

41       This is the Perl API for (the server half of) OpenID, a distributed
42       identity system based on proving you own a URL, which is then your
43       identity.  More information is available at:
44
45         http://openid.net/
46
47       As of version 1.01 this module has support for both OpenID 1.1 and 2.0.
48       Prior to this, only 1.1 was supported.
49

CONSTRUCTOR

51       Net::OpenID::Server->new([ %opts ])
52           You can set anything in the constructor options that there are
53           getters/setters methods for below.  That includes: args, get_user,
54           is_identity, is_trusted, setup_url, and setup_map.  See below for
55           docs.
56

METHODS

58       ($type, $data) = $nos->handle_page([ %opts ])
59           Returns a $type and $data, where $type can be:
60
61           "redirect"
62               ... in which case you redirect the user (via your web
63               framework's redirect functionality) to the URL specified in
64               $data.
65
66           "setup"
67               ... in which case you should show the user a page (or redirect
68               them to one of your pages) where they can setup trust for the
69               given "trust_root" in the hashref in $data, and then redirect
70               them to "return_to" at the end.  Note that the parameters in
71               the $data hashref are as you named them with setup_map.
72
73           Some content type
74               Otherwise, set the content type to $type and print the page
75               out, the contents of which are in $data.
76
77           The optional %opts may contain:
78
79           "redirect_for_setup"
80               If set to a true value, signals that you don't want to handle
81               the "setup" return type from handle_page, and you'd prefer it
82               just be converted to a "redirect" type to your already-defined
83               "setup_url", with the arguments from setup_map already
84               appended.
85
86       $url = $nos->signed_return_url( %opts )
87           Generates a positive identity assertion URL that you'd redirect a
88           user to.  Typically this would be after they've completed your
89           setup_url.  Once trust has been setup, the "handle_page" method
90           will redirect you to this signed return automatically.
91
92           The URL generated is the consumer site's return_to URL, with a
93           signed identity included in the GET arguments.  The %opts are:
94
95           "identity"
96               Required.  The identity URL to sign.
97
98           "claimed_id"
99               Optional.  The claimed_id URL to sign.
100
101           "return_to"
102               Required.  The base of the URL being generated.
103
104           "assoc_handle"
105               The association handle to use for the signature.  If blank,
106               dumb consumer mode is used, and the library picks the handle.
107
108           "trust_root"
109               Optional.  If present, the "return_to" URL will be checked to
110               be within ("under") this trust_root.  If not, the URL returned
111               will be undef.
112
113           "ns"
114               Optional.
115
116           "additional_fields"
117               Optional.  If present, must be a hashref with keys starting
118               with "\w+\.".  All keys and values will be returned in the
119               response, and signed.  This is used for OpenID extensions.
120
121       $url = $nos->cancel_return_url( %opts )
122           Generates a cancel notice to the return_to URL, if a user declines
123           to share their identity.  %opts are:
124
125           "return_to"
126               Required.  The base of the URL being generated.
127
128       $nos->args
129           Can be used in 1 of 3 ways:
130
131           1. Setting the way which the Server instances obtains parameters:
132
133           $nos->args( $reference )
134
135           Where $reference is either a HASH ref, CODE ref, Apache $r (for
136           get_args only), Apache::Request $apreq, or CGI.pm $cgi.  If a CODE
137           ref, the subref must return the value given one argument (the
138           parameter to retrieve)
139
140           2. Get a paramater:
141
142           my $foo = $nos->get_args("foo");
143
144           When given an unblessed scalar, it retrieves the value.  It croaks
145           if you haven't defined a way to get at the parameters.
146
147           3. Get the getter:
148
149           my $code = $nos->get_args;
150
151           Without arguments, returns a subref that returns the value given a
152           parameter name.
153
154       $nos->get_user($code)
155       $code = $nos->get_user; $u = $code->();
156           Get/set the subref returning a defined value representing the
157           logged in user, or undef if no user.  The return value (let's call
158           it $u) is not touched.  It's simply given back to your other
159           callbacks (is_identity and is_trusted).
160
161       $nos->get_identity($code)
162       $code = $nos->get_identity; $identity = $code->($u, $identity);
163           For OpenID 2.0. Get/set the subref returning a identity. This is
164           called when claimed identity is 'identifier_select'.
165
166       $nos->is_identity($code)
167       $code = $nos->is_identity; $code->($u, $identity_url)
168           Get/set the subref which is responsible for returning true if the
169           logged in user $u (which may be undef if user isn't logged in) owns
170           the URL tree given by $identity_url.  Note that if $u is undef,
171           your function should always return 0.  The framework doesn't do
172           that for you so you can do unnecessary work on purpose if you care
173           about exposing information via timing attacks.
174
175       $nos->is_trusted($code)
176       $code = $nos->is_trusted; $code->($u, $trust_root, $is_identity)
177           Get/set the subref which is responsible for returning true if the
178           logged in user $u (which may be undef if user isn't logged in)
179           trusts the URL given by $trust_root to know his/her identity.  Note
180           that if either $u is undef, or $is_identity is false (this is the
181           result of your previous is_identity callback), you should return 0.
182           But your callback is always run so you can avoid timing attacks, if
183           you care.
184
185       $nos->server_secret($scalar)
186       $nos->server_secret($code)
187       $code = $nos->server_secret; ($secret) = $code->($time);
188           The server secret is used to generate and sign lots of per-consumer
189           secrets, and is never handed out directly.
190
191           In the simplest (and least secure) form, you configure a static
192           secret value with a scalar.  If you use this method and change the
193           scalar value, all consumers that have cached their per-consumer
194           secrets will start failing, since their secrets no longer work.
195
196           The recommended usage, however, is to supply a subref that returns
197           a secret based on the provided $time, a unix timestamp.  And if one
198           doesn't exist for that time, create, store and return it (with
199           appropriate locking so you never return different secrets for the
200           same time.)  Your secret can just be random characters, but it's
201           your responsibility to do the locking and storage.  If you want
202           help generating random characters, call
203           Net::OpenID::Server::rand_chars($len).
204
205           Your secret may not exceed 255 characters.
206
207       $nos->setup_url($url)
208       $url = $nos->setup_url
209           Get/set the user setup URL.  This is the URL the user is told to go
210           to if they're either not logged in, not who they said they were, or
211           trust hasn't been setup.  You use the same URL in all three cases.
212           Your setup URL may contain existing query parameters.
213
214       $nos->endpoint_url($url)
215       $url = $nos->endpoint_url
216           For OpenID 2.0. Get/set the op_endpoint URL.
217
218       $nos->setup_map($hashref)
219       $hashref = $nos->setup_map
220           When this module gives a consumer site a user_setup_url from your
221           provided setup_url, it also has to append a number of get
222           parameters onto your setup_url, so your app based at that setup_url
223           knows what it has to setup.  Those keys are named, by default,
224           "trust_root", "return_to", "identity", and "assoc_handle".  If you
225           don't like those parameter names, this $hashref setup_map lets you
226           change one or more of them.  The hashref's keys should be the
227           default values, with values being the parameter names you want.
228
229       Net::OpenID::Server->rand_chars($len)
230           Utility function to return a string of $len random characters.  May
231           be called as package method, object method, or regular function.
232
233       $nos->err
234           Returns the last error, in form "errcode: errtext";
235
236       $nos->errcode
237           Returns the last error code.
238
239       $nos->errtext
240           Returns the last error text.
241
243       This module is Copyright (c) 2005 Brad Fitzpatrick.  All rights
244       reserved.
245
246       You may distribute under the terms of either the GNU General Public
247       License or the Artistic License, as specified in the Perl README file.
248       If you need more liberal licensing terms, please contact the
249       maintainer.
250

WARRANTY

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

MAILING LIST

255       The Net::OpenID family of modules has a mailing list powered by Google
256       Groups. For more information, see
257       http://groups.google.com/group/openid-perl .
258

SEE ALSO

260       OpenID website:  http://openid.net/
261

AUTHORS

263       Brad Fitzpatrick <brad@danga.com>
264
265
266
267perl v5.36.0                      2023-01-20            Net::OpenID::Server(3)
Impressum