README.md
1# NAME
2
3Google::SAML::Request - Create or parse Google's SAML requests
4
5# VERSION
6
7You are currently reading the documentation for version 0.05
8
9# DESCRIPTION
10
11Google::SAML::Request will parse (and, for the sake of completeness, create)
12SAML requests as used by Google. __Please note__ that Google::SAML::Request is by
13no means a full implementation of the SAML 2.0 standard. But if you want to
14talk to Google to authenticate users, you should be fine.
15
16In fact, if you want to talk to Google about SSO, just use
17[Google::SAML::Response](https://metacpan.org/pod/Google::SAML::Response)
18and you should be fine.
19
20# SYNOPSIS
21
22Create a new request object by taking the request ouf of the CGI environment:
23
24 use Google::SAML::Request;
25 my $req = Google::SAML::Request->new_from_cgi();
26 if ( $req->ProviderName() eq 'google.com'
27 && $req->AssertionConsumerServiceURL() eq 'https://www.google.com/hosted/psosamldemo.net/acs' ) {
28
29 processRequest();
30 }
31 else {
32 print "go talk to someone else\n";
33 }
34
35Or use a request string that you get from somewhere else (but make sure that it is no longer
36URI-escaped):
37
38 use Google::SAML::Request;
39 my $req = Google::SAML::Request->new_from_string( $request_string );
40 if ( $req->ProviderName() eq 'google.com'
41 && $req->AssertionConsumerServiceURL() eq 'https://www.google.com/hosted/psosamldemo.net/acs' ) {
42
43 processRequest();
44 }
45 else {
46 print "go talk to someone else\n";
47 }
48
49Or, finally, create a request from scratch and send that to somebody else:
50
51 use Google::SAML::Request;
52 my $req = Google::SAML::Request->new(
53 {
54 ProviderName => 'me.but.invalid',
55 AssertionConsumerServiceURL => 'http://send.your.users.here.invalid/script',
56 }
57 );
58
59# PREREQUISITES
60
61You will need the following modules installed:
62
63- [MIME::Base64](https://metacpan.org/pod/MIME::Base64)
64- [Compress::Zlib](https://metacpan.org/pod/Compress::Zlib)
65- [Date::Format](https://metacpan.org/pod/Date::Format)
66- [XML::Simple](https://metacpan.org/pod/XML::Simple)
67- [URI::Escape](https://metacpan.org/pod/URI::Escape)
68- [CGI](https://metacpan.org/pod/CGI) (if you are going to use the 'new\_from\_cgi' constructor)
69
70# METHODS
71
72## new
73
74Create a new Google::SAML::Request object from scratch.
75
76You have to provide the needed parameters here. Some parameters
77are optional and defaults are used if they are not supplied.
78
79The parameters need to be passed in in a hash reference as
80key value pairs.
81
82### Required parameters
83
84- ProviderName
85
86 Your name, e.g. 'google.com'
87
88- AssertionConsumerServiceURL
89
90 The URL the user used to contact you. E.g. 'https://www.google.com/hosted/psosamldemo.net/acs'
91
92### Optional parameters
93
94- IssueInstant
95
96 The time stamp for the Request. Default is _now_.
97
98- ID
99
100 If you need to create the ID yourself, use this option. Otherwise the ID is
101 generated from the current time and a pseudo-random number.
102
103## new\_from\_cgi
104
105Create a new Google::SAML::Request object by fishing it out of the CGI
106environment.
107
108If you provide a hash-ref with the key 'param\_name' you can determine
109which cgi parameter to use. The default is 'SAMLRequest'.
110
111## new\_from\_string
112
113Pass in a (uri\_unescaped!) string that contains the request string. The string
114will be base64-unencoded, inflated and parsed. You'll get back a fresh
115Google::SAML::Response object if the string can be parsed.
116
117## get\_xml
118
119Returns the XML representation of the request.
120
121## get\_get\_param
122
123No, that's not a typo. This method will return the request in a form
124suitable to be used as a GET parameter. In other words, this method
125will take the XML representation, compress it, base64-encode the result
126and, finally, URI-escape that.
127
128### Accessor methods (read-only)
129
130All of the following accessor methods return the value of the
131attribute with the same name
132
133## AssertionConsumerServiceURL
134
135## ID
136
137## IssueInstant
138
139## ProtocolBinding
140
141## ProviderName
142
143## Version
144
145# SOURCE CODE
146
147This module has a repository on github. Pull requests are welcome.
148
149 https://github.com/mannih/Google-SAML-Request/
150
151# AUTHOR
152
153Manni Heumann (saml at lxxi dot org)
154
155# LICENSE
156
157Copyright (c) 2008 Manni Heumann. All rights reserved.
158
159This program is free software; you can redistribute it and/or
160modify it under the same terms as Perl itself.
161