1Net::OpenID::Server(3)User Contributed Perl DocumentationNet::OpenID::Server(3)
2
6 Net::OpenID::Server - Library for building your own OpenID
7 server/provider
8
10 version 1.09
11
13 use Net::OpenID::Server;
14 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 # From your OpenID server endpoint:
26 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
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 http://openid.net/
46 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
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
58 ($type, $data) = $nos->handle_page([ %opts ])
59 Returns a $type and $data, where $type can be:
60 "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 "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 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 The optional %opts may contain:
78 "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 $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 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 "identity"
96 Required. The identity URL to sign.
97 "claimed_id"
99 Optional. The claimed_id URL to sign.
100 "return_to"
102 Required. The base of the URL being generated.
103 "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 "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 "ns"
114 Optional.
115 "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 $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 "return_to"
126 Required. The base of the URL being generated.
127 $nos->args
129 Can be used in 1 of 3 ways:
130 1. Setting the way which the Server instances obtains parameters:
132 $nos->args( $reference )
134 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 2. Get a paramater:
141 my $foo = $nos->get_args("foo");
143 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 3. Get the getter:
148 my $code = $nos->get_args;
150 Without arguments, returns a subref that returns the value given a
152 parameter name.
153 $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 $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 $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 $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 $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 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 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 Your secret may not exceed 255 characters.
206 $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 $nos->endpoint_url($url)
215 $url = $nos->endpoint_url
216 For OpenID 2.0. Get/set the op_endpoint URL.
217 $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 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 $nos->err
234 Returns the last error, in form "errcode: errtext";
235 $nos->errcode
237 Returns the last error code.
238 $nos->errtext
240 Returns the last error text.
241
243 This module is Copyright (c) 2005 Brad Fitzpatrick. All rights
244 reserved.
245 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
252 This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.
253
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
260 OpenID website: http://openid.net/
261
263 Brad Fitzpatrick <brad@danga.com>
264perl v5.28.1 2011-11-10 Net::OpenID::Server(3)