1<<if: ZXIDBOOK>> 2<<else: >>Apache with mod\_auth\_saml Receipe 3################################### 4<<author: Sampo Kellom�ki (sampo@iki.fi)>> 5<<class: article!a4paper!!mod\_auth\_saml 01>> 6<<cvsid: $Id: mod_auth_saml.pd,v 1.11 2009-09-16 10:14:57 sampo Exp $>> 7 8While I am not a guru in Apache set-ups and others will do this much 9better, not to speak of the official documentation, I still find that 10to ensure initial success of the new installer, some help may be in order. 11 12Consider this receipe only one of many possible set-ups and not 13necessarily even the best. The receipe worked for me in September 2008. If 14you come much later, things may have changed. 15 16This Apache set-up illustrates ~mod_auth_saml~. If you are interested 17in CGI, ~mod_php~, or ~mod_perl~ use with Apache, or compilation 18of Apache httpd with above bits and pieces, please refer to 19<<link:../html/apache.html: Apache Setup Receipe>> 20 21For more general information about ZXID.org compilation or APIs start 22reading in <<link:../html/README.zxid.html: README.zxid>>. 23 241 Architectural Overview 25======================== 26 271.1 Other documents 28------------------- 29 30<<doc-inc.pd>> 31<<htmlpreamble: <title>Apache with mod_auth_saml Receipe</title><link type="text/css" rel=stylesheet href="zx.css"><body><h1>Apache with mod_auth_saml Receipe</h1> >> 32<<fi: >> 33 34<<dia: arch-zxid-apache:bg,fg: ZXID, via mod_auth_saml, adds to Apache httpd Single Sign-On (SSO), Attribute Broker, and XACML PEP Capabilities that can be used by existing static and dynamic content without alteration.>> 35<<newpage: >> 36 37<<if: ZXIDBOOK>> 38<<else: >> 392 Introduction to mod_auth_saml 40=============================== 41<<fi: >> 42 43For avoidance of doubt, ~mod_auth_saml~ - based on zxid.org - is 44a separate project from ~mod_authn_casa~, ~mod_scalp~ and ~mod_mellon~, 45which provide somewhat similar functionality, but have 46different code bases. It may be possible to use all of these 47simultaneously, but this is not recommended unless you are an expert 48that can sort out the differences. 49 50~mod_auth_saml~ provides Apache2 native integration at authentication 51layer. The objective of ~mod_auth_saml~ is to cause Apache to trigger 52SAML 2.0 Single Sign-On instead of HTTP Basic or Digest authentication. 53 54~mod_auth_saml~ does not backend in any module in the <<italic: 55mod_authn_*>> sense. All authentication information is obtained from 56the frontend IdP without consulting any backend. (However, the zxid.org 57session mechanism needs backend storage - once zxid.org is generalized 58to support other backends than the default file system, we may factor 59out the local session storage to a backend of its own.) 60 61If you want to perform local authentication after the SSO, 62~mod_auth_saml~ will provide for downstream <<italic: mod_authz_*>> modules a 63(pseudonymous) user identifier that can be used to make the 64authorization decisions. It will also provide the attributes that were 65received in the SSO or that were retrieved by later web services calls 66(like ID-DAP or Personal Profile calls). 67 68Eventually ~mod_auth_saml~ may call on a <<italic: mod_authn_*>> 69backend to obtain additional local attributes (beyond the ones 70received in the SSO). Such call will use the pseudonym as key. 71 722.1 Compiling from Source 73------------------------- 74 75You may be able to get mod_auth_saml.so in binary form, in which 76case all you need to do is 77 78 make dir # Create /var/zxid hierarchy 79 cp mod_auth_saml.so /usr/local/httpd/modules 80 81For more in-depth compilation instructions, please refer to 82general ZXID documentation (README.zxid). 83 84Before you try compilation and installation of mod_auth_saml, you 85should investigate what type of Apache install you have. Unfortunately 86different OS distributions do this differently, making it difficult to 87provide one set of instructions that would always work. 88 89Out of box, zxid/Makefile assumes your Apache is installed where 90the Apache project source code distribution would put it, namely 91in APACHE_ROOT=/usr/local/httpd. You can change this by adding 92a new definition in localconf.mk. 93 94On some distributions the Apache related files are scattered 95in many places that are not under any specific "root" directory. 96In these cases you may need to define separate variable 97for each use, e.g: 98 99 localconf.mk: 100 APACHE_INCLUDE=-I/usr/include/apache2 101 APR_INCLUDE=-I/usr/include/apr-1.0 102 APACHE_MODULES=/usr/lib/apache2/modules 103 104To locate the correct directories, you can try 105 106 find / -name ap_config.h 107 find / -name apr.h 108 find / -name mod_auth_basic.so 109 110Once everything is correctly set up, you can compile 111and install by saying 112 113 make apachezxid # Compiles 114 make apachezxid_install # Copies 115 make dir # Create directory structure 116 117The installation step really just copies mod_auth_saml.so to 118modules/ subdirectory of the Apache installation. 119 1202.1 Configuration and Testing 121----------------------------- 122 1232.1.1 httpd.conf 124~~~~~~~~~~~~~~~~ 125 126First you have to make sure mod_auth_saml.so is located in the 127modules/ directory of your Apache httpd installation 128(e.g. /usr/local/httpd/modules/mod_auth_saml.so in Apache httpd 129compiled from source or /usr/lib/apache2/modules/mod_auth_saml.so in 130some distributions). Then you should pull the module into the 131configuration with directive: 132 133 LoadModule auth_saml_module modules/mod_auth_saml.so 134 135Next you should configure the Location protected by SSO: 136 137 <Location /protected> 138 Require valid-user 139 AuthType "saml" 140 ZXIDConf "URL=https://sp1.zxidsp.org:5443/protected/saml" 141 </Location> 142 143The /protected is the directory you choose to protect. AuthType must 144be "saml". The ZXIDConf directive allows you to pass any and 145all ZXID configuration directives, using query string format. Please 146see main ZXID documentation (README.zxid) for full discussion 147of the configuration options. 148 149While most options can be left at their default value, the ~URL~ 150always needs to be specified. It must match the domain name 151and the directory that you choose to protect. The final suffix 152/saml is used as communications end point during protocol 153exchanges. You can choose any word you want (i.e. need not be "saml"), 154but it must not conflict with any actual content in the directory 155and must be immediate child of the directory. 156 157As of version 0.28 (Sept 2008) you still need to create actual 158file to correspond to the URL: 159 160 touch /usr/local/httpd/htdocs/protected/saml 161 162We expect to remove this requirement for dummy file in a future 163version. 164 165(*** the saml part should be automatically appeneded, sanity check Location and url match, dig virtual host domain name automatically, example http://idrecconv.orange.fr/auth_user/bin/auth_user.cgi?origine=...) 166 1672.1.2 Trying it out 168~~~~~~~~~~~~~~~~~~~ 169 170Try accessing 171 172 https://sp1.zxidsp.org:5443/protected/somefile 173 174You should first land on IdP selection and then after 175authentication to the IdP, see the file, or error 176message if the file does not exist. 177 178<<ignore: 179gdb /apps/apache/std/bin/httpd /apps/apache/std/core 180dir /s/httpd-2.2.3 181bt 182>> 183 1842.1.3 Setting up Circle of Trust 185~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 186 187* Auto-CoT method 188* Manual methods 189 1902.2 Real World Example 191---------------------- 192 193Assume you want to set up a complex web site with some areas 194protected strongly, others moderately, and some not at all. 195 196 / -- No protection 197 /pers -- Optional SAML SSO. If SSO has been performed, the 198 content will be personalized. If no SSO has been 199 performed -- or fails -- nonpersonalized content 200 is served. Default IdP is used. 201 /intra -- Requires SAML SSO with default IdP 202 /protected -- Requires any SAML SSO with choice of IdP 203 /strong -- Requires SAML SSO with strong credentials and choice of IdP 204 /other -- Independent SP colocated with same web server. Login 205 to any of the first 4 directories does not count 206 as login to /other. It is its own entity and needs 207 separate SAML SSO. 208 2091. Here's how you would configure it in httpd.conf (SSL and other 210 configuration items are as usual and are not reproduced here): 211 212 LoadModule auth_saml_module modules/mod_auth_saml.so 213 214 <Location /pers> 215 Require valid-user 216 AuthType "saml" 217 ZXIDConf "URL=https://sp1.zxidsp.org:5443/protected/saml" 218 ZXIDConf "DEFAULTQS=l0https://s-idp.liberty-iop.org:8881/idp.xml=1%26fp=1" 219 </Location> 220 221 <Location /intra> 222 Require valid-user 223 AuthType "saml" 224 ZXIDConf "URL=https://sp1.zxidsp.org:5443/protected/saml" 225 ZXIDConf "DEFAULTQS=l0https://s-idp.liberty-iop.org:8881/idp.xml=1%26fc=1" 226 ZXIDConf "REQUIRED_AUTHNCTX=urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport$urn:oasis:names:tc:SAML:2.0:ac:classes:Strong" 227 </Location> 228 229 <Location /protected> 230 Require valid-user 231 AuthType "saml" 232 ZXIDConf "URL=https://sp1.zxidsp.org:5443/protected/saml" 233 ZXIDConf "ANON_OK=/pers/" 234 ZXIDConf "REDIR_TO_CONTENT=1" 235 </Location> 236 237 <Location /strong> 238 Require valid-user 239 AuthType "saml" 240 ZXIDConf "URL=https://sp1.zxidsp.org:5443/protected/saml" 241 ZXIDConf "REQUIRED_AUTHNCTX=urn:oasis:names:tc:SAML:2.0:ac:classes:Strong" 242 ZXIDConf "IDP_SEL_PAGE=/idpsel.cgi" 243 </Location> 244 245 <Location /other> 246 Require valid-user 247 AuthType "saml" 248 ZXIDConf "PATH=/var/other/" 249 ZXIDConf "URL=https://sp1.zxidsp.org:5443/other/saml" 250 ZXIDConf "SES_COOKIE_NAME=OtherSes" 251 </Location> 252 253 Notes 254 255 a. /pers, /intra, and /strong are "slaves" of /protected. This 256 means they can have some settings of their own, but other 257 settings, especially those that apply after SSO, are shared 258 with /protected 259 b. The slaves share Entity ID, session cookie, and session 260 with the master. 261 c. /other is genuinely different SP with its own Entity ID, 262 cookie and session directory. 263 d. The ANON_OK describes prefix under which SSO failure is 264 not considered fatal. Currently there can only be one 265 such prefix per master SP. This is known limitation. (***) 266 e. The REDIR_TO_CONTENT is set in master and shared with 267 slaves. This causes the SSO to end with 302 redirection to 268 the original content so that the URL in browser's address 269 bar will appear clean. Without this option, the last 270 step of the SSO protocol might be visible and since 271 SSO terminates in master SP, the slaves would have 272 their relative URLs wrong. 273 f. The DEFAULTQS specification is used to simulate user 274 submitting the IdP selection form. It is used for the 275 SPs for which the IdP is always the same. The Query String 276 can also have some other form fields that control things 277 like the +ispassive+ flag (fp=1) or the +allowcreate+ 278 flag (fc=1). To understand what fields are possible, 279 you can "View Source" the regular IdP selection page. 280 The value of the DEFAULTQS option needs to be URL encoded 281 to prevent premature interpretation as multiple configuration 282 options. In particular the ampersand must be encoded as %26. 283 g. The IDP_SEL_PAGE allows you to build a fully custom 284 IdP selection page. Here we use it for requesting strong 285 authentication context. Other simpler ways to customize 286 the IdP Selection Page exist, see e.g. IDP_SEL_TEMPL_FILE 287 whose default value is "idpsel.html" (you can edit that 288 file or "idpsel.css" for customization). IDP_SEL_TEMPL_FILE 289 must be specified as absolute filesystem path (this may be relaxed in future *** --Sampo). 290 2912. Create directories in the web root according to above plan. 292 You also need to create the /var/other hierarchy since 293 you want to keep /other as separate entity from rest of 294 the directories 295 296 make dir ZXID_PATH=/var/other/ 297 298 N.B. The last slash is important. 299 300 Make sure the web server process has file system permissions 301 to write to /var/zxid and /var/other. 302 3032.3 Testing 304----------- 305 306To enable debugging output, you should add 307 308 ZXIDDebug "0x61" 309 310to the above configuration. 311 3121. Make sure you are logged out from your IdP and 313 SP (e.g. delete cookies in browser) 314 3152. https://sp1.zxidsp.org:5443/pers/env.cgi 316 317 * IdP selection should not show up. 318 * IdP should not ask credentials. 319 * You should see dump of environment variables 320 * SAML_authnctxlevel=- 321 * SAML_idpnid=- 322 3233. https://sp1.zxidsp.org:5443/intra/env.cgi 324 325 * IdP selection should not show up. (bug: currently it does ***) 326 * IdP should ask credentials 327 * You should see dump of environment variables 328 * SAML_authnctxlevel=urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport 329 * SAML_idpnid=Peq7sdf-o0brJQcyrFvVh 330 3314. https://sp1.zxidsp.org:5443/pers/env.cgi 332 333 * This time the session is well authenticated so you 334 should see the same dump as in step (3). 335 3365. Logout by https://sp1.zxidsp.org:5443/protected/saml?o=m 337 and clicking "Single Logout (R)" 338 3392.4 mod_auth_saml FAQ 340--------------------- 341 3421. How it actually works, does the module intercept every http 343 request/response? 344 345 It intercepts every HTTP request destined to URL prefixed by what 346 appears in httpd.conf <Location> configuration, i.e. Apache itself 347 prefilters by URL prefix. 348 349 Then it checks if cookie session is present - if so, the request is 350 passed through to rest of Apache processing. If not, it will start 351 the SSO processing by presenting the IdP selection screen. Eventually 352 this will be improved to attempt automatic detection of IdP, e.g. if 353 there is only one IdP in the CoT. 354 355 If the URL is the special one configured in 356 357 ZXIDConf "URL=https://sp1.zxidsp.org:5443/protected/saml" 358 359 it will pass control to the ZXID code. 360 361 If SSO was triggered, the original URL is held in RelayState and 362 once the SSO completes (which will happen at the special URL), a 363 redirect is performed to the original URL found from RelayState. 364 This could be used beneficially in unsolicited SSO as well. 365 3662. Does it have the reverse proxy functionality or is it located elsewhere? 367 368 mod_auth_saml works at the same layer and much the same way as 369 HTTP Basic authentication is implemented in Apache. It runs 370 in the Apache process itself and does not invoke any external 371 helper. 372 373 It is not a reverse proxy. However, it is possible to configure 374 a frontend Apache server, with mod_auth_saml, to act as a reverse 375 proxy.<<footnote: Integrating zxid to a dedicated reverse proxy 376 like Pound (http://www.apsis.ch/pound/) should not be difficult.>> 377 3783. Is it OS independant? I mean, works both for Apache-Linux and 379 Apache-Windows and Apache-Solaris? I wonder not directly, but 380 could be compiled, right? 381 382 It should be OS independant. For Unixes I am pretty sure this is a 383 fact. For Windows we need more testing (as of May 2008). It does not 384 yet (May 2008) work in IIS. 385 3864. How the session creation at application is handled? 387 388 The name of the cookie that ZXID sets is configurable (by default it 389 is called ZXIDSES). This may be enough for some applications. 390 3912.5 Important TODO items for mod_auth_saml 392------------------------------------------ 393 394Memory management needs an audit. The problem centers around memory 395management of dependency libraries openssl and libcurl. Both libraries 396as well as ZXID itself have vectorable memory allocators, i.e. you 397can supply your own implementation of malloc(3) and free(3). This allows 398Apache pool allocation functions to be used instead of the traditional 399malloc(3) and free(3). 400 401Unfortunately life is not that simple. Which pool should we use? The 402per request pool is suitable for most purposes, but how can we know for what 403purpose openssl and libcurl allocate memory? There is no easy way of 404knowing and the ephemeral nature of per request allocation may land us 405in trouble. Other option would be to allocate everything from global 406pool to make sure the memory will never be freed under us. Unfortunately 407memory from the global pool can not be freed. Thus we may be better 408sticking to malloc(3) and free(3). 409 410To make matters worse, openssl is used by all of zxid, libcurl, and Apache 411mod_ssl. Which one gets to set the function pointers that point to the 412allocator? There is no easy answer - or at least we have not seen one yet. 413 414The allocator problems may be just about manageable for Apache running 415in traditional pre-fork server mode, but become a real nightmare for 416threaded execution modes. 417 4182.6 mod_authz_xacml 419------------------- 420 421We plan to develop a <<italic: mod_authz_*>> layer module that will perform the 422authorization using XACML. ~mod_authz_xacml~ will act as a PEP and 423pass all available session attributes to a PDP and then act on the 424decision of the PDP to deny or permit access to a web resource. This is 425still WIP. 426 427<<if: ZXIDBOOK>> 428<<else: >> 429 4307 Conclusion 431============ 432 433If you have any trouble, please do not hesitate to contact the author. 434 435<<EOF: >> 436 437grep ap_internal_redirect * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/* 438 439Apparent order of processing in Apache httpd-2.2.3 440 441tail -f tmp/log.httpd & 442tail -f tmp/err-httpd & 443/apps/apache/std/bin/apachectl restart 444https://sp1.zxidsp.org:5443/protected/content.txt 445https://s-idp.liberty-iop.org:8881/N 446 447ulimit -c unlimited 448/apps/apache/std/bin/httpd -X # Run Apache in single threaded debug mode 449# In single threaded mode beware of metadata requests blocking 450gdb /apps/apache/std/bin/httpd /d/sampo/zxid/core 451 452Apache and cores: 453* http://www.cyberciti.biz/tips/configure-apache-web-server-for-core-dump.html 454* CoreDumpDirectory /tmp/cores 455* cat /proc/sys/kernel/core_pattern 456 457<<fi: >>