Mojolicious/Plugin/SAML.pm untested

filter: Statementstmt 0.0% 0 / 109 Branchbran 0.0% 0 / 12 Conditioncond 0.0% 0 / 16 MC/DCmcdc 0.0% 0 / 9 Subroutinesub 0.0% 0 / 12 Podpod 0.0% 0 / 2 totaltotal 0.0% 0 / 160 CC 7 SCAR 31.4
CC
7
Cov
0%
register
56.0
sp_metadata
2.0
BEGIN
2.0
CRAP 23.0
1 package Mojolicious::Plugin::SAML;
2  
3 use Mojo::Base 'Mojolicious::Plugin';
4  
5 use Carp ();
6 use Crypt::OpenSSL::RSA;
7 use Crypt::OpenSSL::X509;
8 use Mojo::File 'path';
9 use Mojo::SAML ':docs';
10 use Mojo::SAML::IdP;
11 use Mojo::URL;
12 use Mojo::Util;
13 use Scalar::Util ();
14  
15 has [qw/metadata route/];
16  
17 sub sp_metadata {
18 my $plugin = shift;
19 #TODO this should search for an SPSSODescriptor
20 return $plugin->metadata->descriptors->[0];
21 }
22  
23 sub register {
24 my ($plugin, $app, $conf) = @_;
25 $conf ||= {};
26 $conf = { %$conf, %{$app->config->{SAML}} };
27 Carp::croak 'No SAML configuration given'
28 unless keys %$conf;
29  
30 my $login = $conf->{handle_login} // Carp::croak 'handle_login is required';
31 my $key = Crypt::OpenSSL::RSA->new_private_key(path($conf->{key})->slurp);
32 my $cert = Crypt::OpenSSL::X509->new_from_string(path($conf->{cert})->slurp);
33 my $idp = Mojo::SAML::IdP->new->from($conf->{idp});
34  
35 my $location = $conf->{location};
36 my $entity_id = $conf->{entity_id} // $location;
37  
38 my $key_info = KeyInfo->new(cert => $cert);
39 my $key_desc = KeyDescriptor->new(
40 key_info => $key_info,
41 use => 'signing',
42 );
43 my $post = AssertionConsumerService->new(
44 index => 0,
45 binding => 'HTTP-POST',
46 location => $location,
47 );
48 my $redir = AssertionConsumerService->new(
49 index => 1,
50 binding => 'HTTP-Redirect',
51 location => $location,
52 );
53 my $sp = SPSSODescriptor->new(
54 key_descriptors => [$key_desc],
55 assertion_consumer_services => [$post, $redir],
56 nameid_format => [qw/unspecified/],
57 );
58 my $metadata = EntityDescriptor->new(
59 id => 'MOJOSAML_METADATA',
60 entity_id => $entity_id,
61 descriptors => [$sp],
62 insert_signature => Signature->new(key_info => $key_info),
63 insert_xml_declaration => 1,
64 sign_with_key => $key,
65 );
66 $plugin->metadata($metadata);
67  
68 $app->helper('saml.authn_request' => sub {
69 my ($c, %opt) = @_;
70  
71 my $binding = $opt{binding} // 'HTTP-Redirect';
72 my $passive = $opt{passive} // 0;
73 # TODO get "sign" default from idp
74 my $sign = $opt{sign} // 1;
75  
76 my $url = $idp->location_for(SingleSignOnService => $binding);
77 my $req = AuthnRequest->new(
78 issuer => $entity_id,
79 assertion_consumer_service_index => 0,
80 is_passive => $passive,
81 nameid_policy => NameIDPolicy->new(format => 'unspecified'),
82 destination => "$url",
83 );
84  
85 if ($binding eq 'HTTP-Redirect') {
86 $url->query(SAMLRequest => $req->to_string_deflate);
87  
88 if ($sign) {
89 $url->query({SigAlg => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'});
90 $key->use_sha256_hash;
91 my $val = $url->query->to_string;
92 my $sig = $key->sign($val);
93 $url->query({Signature => Mojo::Util::b64_encode($sig, '')});
94 }
95  
96 $c->redirect_to($url);
97 } else {
98 Carp::croak "Binding '$binding' is not implemented by saml.authn_request helper";
99 }
100 });
101  
102 $app->helper('saml.response' => sub {
103 my $c = shift;
104 Carp::croak 'saml response methods must be called during a saml response'
105 unless my $dom = $c->stash->{'saml.response'};
106 return $dom;
107 });
108  
109 my @ns = (samlp => 'urn:oasis:names:tc:SAML:2.0:protocol');
110 $app->helper('saml.response_success' => sub {
111 my $c = shift;
112 my $dom = $c->saml->response;
113 return !!$dom->at('samlp|Response > samlp|Status > samlp|StatusCode[Value="urn:oasis:names:tc:SAML:2.0:status:Success"]', @ns);
114 });
115  
116 $app->helper('saml.response_status' => sub {
117 my $c = shift;
118 my $dom = $c->saml->response;
119 return +($dom->at('samlp|Response > samlp|Status > samlp|StatusCode[Value]', @ns) || {})->{Value};
120 });
121  
122 my $path = Mojo::URL->new($location)->path->to_string;
123 my $r = $app->routes->any($path);
124 $plugin->route($r);
125 Scalar::Util::weaken $plugin->{route};
126  
127 $r->get('/descriptor' => sub {
128 state $my_meta = $plugin->metadata->to_string; # only render once
129 my $c = shift;
130 return $c->reply->not_found unless $my_meta;
131 $c->render(text => $my_meta, format => 'xml');
132 }, 'saml_descriptor');
133  
134 $r->get('/authn_request' => sub { shift->saml->authn_request }, 'saml_authn_request');
135  
136 $r->any('/' => sub {
137 my $c = shift;
138 my $pub = $idp->public_key_for('signing');
139 my $text = Mojo::Util::b64_decode($c->param('SAMLResponse'));
140 my $dom = Mojo::DOM->new->xml(1)->parse($text);
141 return $c->reply->exception('Login failed from SAML provider: Response failed to verify')
142 unless Mojo::XMLSig::verify($dom, $pub);
143  
144 $c->stash->{'saml.response'} = $dom;
145  
146 $c->$login;
147 }, 'saml_endpoint');
148  
149 return $plugin;
150 }
151  
152 1;
153  
154 =head1 NAME
155  
156 Mojolicious::Plugin::SAML - A simple SAML Service Provider plugin
157  
158 =head1 SYNOPSIS
159  
160 =head1 DESCRIPTION
161  
162 This plugin is an early attempt at making a somewhat turn-key SAML Service Provider (SP) plugin.
163 It is explicitly for a single SP communicating with a single Identity Provider (IdP).
164  
165 In the future it is imagined that other more robust plugins might encompass more complex interactions.
166  
167 =head1 CAVEATS
168  
169 Nothing about this plugin should be considered stable.
170 Things can and will change incompatibly until this warning is removed.
171  
172 =head1 CONFIGURATION
173  
174 my $saml = $app->plugin('SAML', \%conf);
175  
176 The plugin can be configured in two ways.
177 A hash reference of configuration options can be passed to the plugin loader.
178 Additionally configuration will be taken from the application's configuration under the C<SAML> toplevel key.
179  
180 The two sources of configuration will be shallow merged with the application configuration taking precedence.
181  
182 The following configuration keys are accepted.
183  
184 =head2 idp
185  
186 The location of the IdP metadata.
187 Passed to L<Mojo::SAML::Entity/from>, it can be a url, string containing xml, or file path.
188  
189 =head2 key
190  
191 The file path location of an RSA private key.
192  
193 =head2 cert
194  
195 The file path location of an X509 certificate generated by the L</key>.
196  
197 =head2 location
198  
199 The fully qualified url of the SAML endpoint, including protocol and host.
200  
201 =head2 entity_id
202  
203 The name of the SP entity to be created.
204 Defaults to the value of L</location> if not specified (the common case).
205  
206 =head2 handle_login
207  
208 A callback called when a login attempt is made.
209 This is called after the request is verified.
210 Note that it does not check L</"saml.response_success">; the callback should and handle accordingly.
211  
212 =head1 HELPERS
213  
214 =head2 saml.authn_request
215  
216 $c->saml->authn_request(%options);
217  
218 Generate and render an AuthnRequest based on the following key-value options
219  
220 =over
221  
222 =item binding
223  
224 The binding that should be used for the request.
225 Defaults to C<HTTP-Redirect>.
226  
227 Currently no other bindings are supported, however that is planned.
228  
229 =item passive
230  
231 Boolean indicating if the request should be passive.
232 Defaults to false.
233  
234 A passive request checks to see if the subject is already logged in.
235 The user is not prompted to login and they aren't shown interactive pages though they may be redirected.
236 The response is as usual for a login attempt, though on failure, the response is not successful (see L</"saml.response_success"> and L</"saml.response_status">).
237  
238 =item sign
239  
240 Boolean indicating if the request should be signed.
241 Defaults to true (though it should and probably will default to the IdP's preference).
242  
243 =back
244  
245 =head2 saml.response
246  
247 my $dom = $c->saml->response;
248  
249 Returns the parsed (and validated) SAML response (as a L<Mojo:DOM> object).
250 This must only be called during the response to a SAML interaction, notably during L</handle_login>.
251  
252 =head2 saml.response_success
253  
254 my $bool = $c->saml->response_success;
255  
256 Returns a boolean indicating if the SAML response was succesful.
257 This must only be called during the response to a SAML interaction, notably during L</handle_login>.
258  
259 =head2 saml.response_status
260  
261 my $status = $c->saml->response_status;
262  
263 Returns the string status from the SAML response.
264 This may be useful if L</"saml.response_success"> was false in order to differentiate the cause of the failure.
265 This must only be called during the response to a SAML interaction, notably during L</handle_login>.
266  
267 =head1 ROUTES
268  
269 This plugin creates several routes all existing under the base url derived from L</location>.
270 They are described below by name and path, where the base path is assumed to be C</saml>.
271  
272 =head2 saml_endpoint
273  
274 /saml
275  
276 This is the primary interaction point for the IdP service.
277  
278 =head2 saml_descriptor
279  
280 /saml/descriptor
281  
282 This url renders the Entity Metadata for the service, containing the SP descriptor that the IdP will need for configuration.
283  
284 =head2 saml_authn_request
285  
286 /saml/authn_request
287  
288 This url generates an AuthnRequest to the IdP via L</"saml.authn_request"> helper called without options (ie, using the default options).
289  
290 =head1 ATTRIBUTES
291  
292 The plugin implements the following attributes.
293  
294 =head2 metadata
295  
296 my $doc = $saml->metadata;
297  
298 Stores the generated metadata, an instance of L<Mojo::SAML::Document::EntityDescriptor>.
299 This can be modified before the first time is is served by L</saml_descriptor>.
300 This is especially useful for injecting requested attributes.
301  
302 Currently the plugin is designed to generate the SP metadata.
303 Setting the metadata from an XML file is planned but not yet implemented.
304 Setting this attribute is not recommended.
305  
306 =head2 route
307  
308 my $r = $saml->route;
309  
310 This holds the L<Mojolicious::Routes::Route> object that is the top-level of the tree of L</ROUTES>.
311 The reference is weakened when initially stored.
312  
313 This attribute is intended for interrogating and possibly modifying the route object itself.
314 Setting this attribute will not be very useful.
315  
316 =head1 METHODS
317  
318 =head2 register
319  
320 my $saml = $app->plugin('SAML');
321  
322 The method called when the plugin is loaded by the application.
323 Returns the plugin instance itself.
324  
325 Note that this is useful to change definitions before the application has begun serving requests.
326 Once the application has begun to serve requests, changes to this object or its data are not recommended and the behavior in that case will be undefined.
327  
328 =head2 sp_metadata
329  
330 my $doc = $saml->sp_metadata;
331  
332 Returns the generated metadata for the SP, an instance of L<Mojo::SAML::Document::SPSSODescriptor>.
333 This reference is also available from L</metadata> but this is more convenient.
334  
335 Note that the implementation of this method is still undetermined.
336 Specifically don't rely on what would happen if you replace this element from the L</metadata>.
337