| 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 |