| 1 | package Mojo::SAML; | ||
| 2 | |||
| 3 | 1 | ▶ | use Mojo::Base -strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | |||
| 5 | our $VERSION = '0.07'; | ||
| 6 | $VERSION = eval $VERSION; | ||
| 7 | |||
| 8 | 1 | ▶ | use constant (); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | 1 | ▶ | use Exporter 'import'; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | 1 | ▶ | use Mojo::Util; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 11 | |||
| 12 | our @doc_types = (qw/ | ||
| 13 | AssertionConsumerService | ||
| 14 | AttributeConsumingService | ||
| 15 | AuthnRequest | ||
| 16 | ContactPerson | ||
| 17 | EntityDescriptor | ||
| 18 | KeyDescriptor | ||
| 19 | KeyInfo | ||
| 20 | NameIDPolicy | ||
| 21 | Organization | ||
| 22 | RequestedAttribute | ||
| 23 | Signature | ||
| 24 | SPSSODescriptor | ||
| 25 | /); | ||
| 26 | |||
| 27 | for my $type (@doc_types) { | ||
| 28 | my $package = "Mojo::SAML::Document::$type"; | ||
| 29 | require(Mojo::Util::class_to_path($package)); | ||
| 30 | constant->import($type => $package); | ||
| 31 | } | ||
| 32 | |||
| 33 | our %EXPORT_TAGS = ( | ||
| 34 | 'docs' => [ @doc_types ], | ||
| 35 | ); | ||
| 36 | our @EXPORT_OK = @doc_types; | ||
| 37 | |||
| 38 | 1; | ||
| 39 | |||
| 40 | =head1 NAME | ||
| 41 | |||
| 42 | Mojo::SAML - A SAML2 toolkit using the Mojo toolkit | ||
| 43 | |||
| 44 | =head1 DESCRIPTION | ||
| 45 | |||
| 46 | L<Mojo::SAML> is a project to build a SAML toolkit using the Mojo stack. | ||
| 47 | It is (for better or worse) completely reimplemented from the ground up. | ||
| 48 | It is considered extremely experimental and unstable (see L</CAVEATS>). | ||
| 49 | |||
| 50 | That said, it can do basic SAML interactions given the proper configuration. | ||
| 51 | For more on SAML, you might want to consult L<https://en.wikipedia.org/wiki/SAML_2.0> or L<https://wiki.oasis-open.org/security>. | ||
| 52 | |||
| 53 | =head1 CAVEATS | ||
| 54 | |||
| 55 | It currently has plenty of limitations and should be considered extremely experimental. | ||
| 56 | The API can and will change without warning until this warning is removed. | ||
| 57 | |||
| 58 | It also relies heavily on using the simpler SAML bindings and is only really workable for RSA keys. | ||
| 59 | Because of this, there are dependencies on L<Crypt::OpenSSL::RSA> and L<Crypt::OpenSSL::X509> which really should be optional, though they are required until other signing mechanisms are included. | ||
| 60 | Users are encouraged to add those modules to their own dependencies in case they become optional in the future. | ||
| 61 | |||
| 62 | Currently data extraction and documentation are very much separate sets of code. | ||
| 63 | It is not yet decided if this will continue or if some effort will be made to unify them. | ||
| 64 | This is a large part of the concern for api stability. | ||
| 65 | |||
| 66 | While most classes have API documentation, currently overall usage documentation is lacking. | ||
| 67 | For the time being, examples can be seen in the C<ex/> directory within the source repository and/or distribution, especially C<ex/webapp.pl>. | ||
| 68 | These examples will be modified as the API changes and eventually usage documentation should be written. | ||
| 69 | |||
| 70 | L<Mojo::XMLSig> has some tests, the rest has precious few tests. | ||
| 71 | There could always be more tests. | ||
| 72 | |||
| 73 | All of this should be improvable. | ||
| 74 | PRs and comments are most welcome. | ||
| 75 | |||
| 76 | =head1 EXPORTS | ||
| 77 | |||
| 78 | L<Mojo::SAML> exports nothing by default. | ||
| 79 | On request it can export any of the following symbols or tags. | ||
| 80 | |||
| 81 | =head2 XML Document Constructors | ||
| 82 | |||
| 83 | The following symbols are constant functions which return the full name of L<Mojo::SAML::Document> subclasses. | ||
| 84 | Their name is both the name of the subclass and the tag that they create. | ||
| 85 | |||
| 86 | =head3 AssertionConsumerService | ||
| 87 | |||
| 88 | Constant shortcut to L<Mojo::SAML::Document::AssertionConsumerService>. | ||
| 89 | |||
| 90 | =head3 AttributeConsumingService | ||
| 91 | |||
| 92 | Constant shortcut to L<Mojo::SAML::Document::AttributeConsumingService>. | ||
| 93 | |||
| 94 | =head3 AuthnRequest | ||
| 95 | |||
| 96 | Constant shortcut to L<Mojo::SAML::Document::AuthnRequest>. | ||
| 97 | |||
| 98 | =head3 ContactPerson | ||
| 99 | |||
| 100 | Constant shortcut to L<Mojo::SAML::Document::ContactPerson>. | ||
| 101 | |||
| 102 | =head3 EntityDescriptor | ||
| 103 | |||
| 104 | Constant shortcut to L<Mojo::SAML::Document::EntityDescriptor>. | ||
| 105 | |||
| 106 | =head3 KeyDescriptor | ||
| 107 | |||
| 108 | Constant shortcut to L<Mojo::SAML::Document::KeyDescriptor>. | ||
| 109 | |||
| 110 | =head3 KeyInfo | ||
| 111 | |||
| 112 | Constant shortcut to L<Mojo::SAML::Document::KeyInfo>. | ||
| 113 | |||
| 114 | =head3 NameIDPolicy | ||
| 115 | |||
| 116 | Constant shortcut to L<Mojo::SAML::Document::NameIDPolicy>. | ||
| 117 | |||
| 118 | =head3 Organization | ||
| 119 | |||
| 120 | Constant shortcut to L<Mojo::SAML::Document::Organization>. | ||
| 121 | |||
| 122 | =head3 RequestedAttribute | ||
| 123 | |||
| 124 | Constant shortcut to L<Mojo::SAML::Document::RequestedAttribute>. | ||
| 125 | |||
| 126 | =head3 Signature | ||
| 127 | |||
| 128 | Constant shortcut to L<Mojo::SAML::Document::Signature>. | ||
| 129 | |||
| 130 | =head3 SPSSODescriptor | ||
| 131 | |||
| 132 | Constant shortcut to L<Mojo::SAML::Document::SPSSODescriptor>. | ||
| 133 | |||
| 134 | =head2 Tags | ||
| 135 | |||
| 136 | =head3 :docs | ||
| 137 | |||
| 138 | Exports all of the above document type constants. | ||
| 139 | |||
| 140 | =head1 OTHER MODULES | ||
| 141 | |||
| 142 | While they aren't linked to from this module, some other modules that will likely be useful are: | ||
| 143 | |||
| 144 | =head2 Mojo::SAML::Names | ||
| 145 | |||
| 146 | L<Mojo::SAML::Names> is a (fairly incomplete) list of naming conventions and standard used in SAML. | ||
| 147 | |||
| 148 | =head2 Mojo::SAML::IdP | ||
| 149 | |||
| 150 | L<Mojo::SAML::IdP> is a tool for examining the entity metadata returned from an identity provider and extracting useful inforamation. | ||
| 151 | |||
| 152 | =head2 Mojo::XMLSig | ||
| 153 | |||
| 154 | L<Mojo::XMLSig> is a tool for signing and verifying XML documents. | ||
| 155 | Note that it is possible that this module could be spun out into its own distribution at some point. | ||
| 156 | If it does, this module will depend on it. | ||
| 157 | |||
| 158 | =head2 Mojolicious::Plugin::SAML | ||
| 159 | |||
| 160 | L<Mojolicious::Plugin::SAML> attempts to be a turn-key SAML Service Provider (SP) implementation. | ||
| 161 | This is useful for interacting with a single Identity Provider (IdP) under simple circumstances. | ||
| 162 | This is (as with all the rest) still highly experimental. | ||
| 163 | |||
| 164 | =head1 SOURCE REPOSITORY | ||
| 165 | |||
| 166 | L<http://github.com/jberger/Mojo-SAML> | ||
| 167 | |||
| 168 | =head1 CONTRIBUTORS | ||
| 169 | |||
| 170 | Giuseppe Di Terlizzi (giterlizzi) | ||
| 171 | |||
| 172 | Mohammad S Anwar (manwar) | ||
| 173 | |||
| 174 | =head1 AUTHOR | ||
| 175 | |||
| 176 | Joel Berger, E<lt>joel.a.berger@gmail.comE<gt> | ||
| 177 | |||
| 178 | =head1 COPYRIGHT AND LICENSE | ||
| 179 | |||
| 180 | Copyright (C) 2018 by L</AUTHOR> and L</CONTRIBUTORS> | ||
| 181 | This library is free software; you can redistribute it and/or modify | ||
| 182 | it under the same terms as Perl itself. | ||