Annotation of loncom/html/adm/help/tex/Institutional_Integration_Shibboleth.tex, revision 1.4
1.1 raeburn 1: \label{Institutional_Integration_Shibboleth}
2:
3: If your institution operates a Shibboleth Identity Provider (IdP) for your
4: users, then you can configure a LON-CAPA server to authenticate users by
5: running your server as a Shibboleth Service Provider (SP).
6:
7: To configure a LON-CAPA server as a Shibboleth SP you will need to:
8:
9: \begin{itemize}
10: \item Install Shibboleth packages for your Linux distro, or build/install from source
11: \item Modify your Apache configuration to include shib.conf (which will load mod\_shib)
12: \item Set shibd to start on boot
13: \item Install mod\_ssl and Apache/SSL certificates
14: \item Configure your SP to work with your institution's IdP
15: \item Add a custom Apache config file to include some PerlVars (for logout etc.)
16: \end{itemize}
17:
18: Although Shibboleth can be built on any 32 or 64 bit Linux distro on which LON-CAPA is supported,
19: official packages are available from http://shibboleth.net for: Red Hat/CentOS 5, 6 and 7,
1.2 raeburn 20: SLES 10 and 11, and openSuSE 12.1, 12.2, and 12.3.
1.1 raeburn 21: In addition, http://www.switch.ch provides a repository from which shibboleth packages
22: may be obtained for Ubuntu 12.04 LTS and 14.04 LTS.
23:
24:
25: \begin{enumerate}
26:
27: \item Install Shibboleth
28:
29: See:
30: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxInstall
31:
32: Shibboleth repos for RPM-based Linux distros can be found at:
33:
34: http://download.opensuse.org/repositories/security:/shibboleth/
35:
36: Red Hat/CentOS -- add shibboleth.repo to /etc/yum.repos.d
37:
38: e.g., CentOS 5
39:
40: \begin{verbatim}
41:
42: [security_shibboleth]
43: name=Shibboleth (CentOS_5)
44: type=rpm-md
45: baseurl=http://download.opensuse.org/repositories/security:/shibboleth/CentOS_5/
46: gpgcheck=1
47: gpgkey=http://download.opensuse.org/repositories/security:/shibboleth/CentOS_5/
48: repodata/repomd.xml.key
49: enabled=1
50: \end{verbatim}
51:
52: e.g., CentOS 6
53:
54: \begin{verbatim}
55:
56: [security_shibboleth]
57: name=Shibboleth (CentOS_6)
58: type=rpm-md
59: baseurl=http://download.opensuse.org/repositories/security:/shibboleth/
60: CentOS_CentOS-6/
61: gpgcheck=1
62: gpgkey=http://download.opensuse.org/repositories/security:/shibboleth/
63: CentOS_CentOS-6/repodata/repomd.xml.key
64: enabled=1
65: \end{verbatim}
66:
67: Then do:
68: \begin{verbatim}
69: yum install shibboleth
70: \end{verbatim}
71:
72: SLES/openSuSE:
73:
74: e.g. SLES 11 SP3:
75:
76: \begin{verbatim}
77: zypper addrepo http://download.opensuse.org/repositories/security:shibboleth/
78: SLE_11_SP3/security:shibboleth.repo
79: zypper refresh
80: zypper install shibboleth
81: \end{verbatim}
82:
83: e.g. SuSE 12.3
84: \begin{verbatim}
85: zypper addrepo http://download.opensuse.org/repositories/security:shibboleth/
86: openSUSE_12.3/security:shibboleth.repo
87: zypper refresh
88: zypper install shibboleth
89: \end{verbatim}
90:
91: e.g., Ubuntu 12.04LTS
92:
93: See: https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.5/sp/deployment/?os=ubuntu
94:
95: \begin{verbatim}
96: sudo apt-get install curl
97: sudo curl -k -O http://pkg.switch.ch/switchaai/SWITCHaai-swdistrib.asc
98: sudo apt-key add SWITCHaai-swdistrib.asc
99: echo 'deb http://pkg.switch.ch/switchaai/ubuntu precise main' |
100: sudo tee /etc/apt/sources.list.d/SWITCHaai-swdistrib.list $>$ /dev/null
101: sudo apt-get update
102: sudo apt-get install shibboleth
103: \end{verbatim}
104:
105: The following directories will have now been created:
106:
107: /etc/shibboleth
108:
109: /var/log/shibboleth
110:
111: /var/run/shibboleth
112:
113: /var/cache/shibboleth
114:
115:
116:
117: \item Apache configuration
118:
119: Red Hat/CentOS -- httpd.conf should be modified to contain:
120: \begin{quotation}
121: \texttt{UseCanonicalName On}
122:
123: \texttt{Include conf/shib.conf}
124: \end{quotation}
125:
126: The Include should precede the line: Include conf/loncapa\_apache.conf
127:
128: SLES/SuSE -- modify /etc/apache2/default-server.conf and /etc/sysconfig/apache2
129:
130: Modify /etc/sysconfig/apache2 to include:
131: \begin{quotation}
132: \texttt{APACHE\_USE\_CANONICAL\_NAME=``on''}
133: \end{quotation}
134:
135: Modify /etc/apache2/default-server.conf to contain:
136: \begin{quotation}
137: \texttt{Include conf/shib.conf}
138: \end{quotation}
139:
140: The Include should precede the line: Include conf/loncapa\_apache.conf
141:
142: Note: the shib.conf file should include: ShibUseHeaders Off
143: so that environment variables can be used to access user attributes, if needed.
144:
145: \item Set shibd to start on boot
146: \begin{quotation}
147: \texttt{/sbin/chkconfig shibd on}
148: \end{quotation}
149:
150:
151: \item Install mod\_ssl and Apache/SSL certificates
152: \begin{enumerate}
153: \item Red Hat/CentOS
154: \begin{quotation}
155: \texttt{yum install mod\_ssl}
156: \end{quotation}
157:
158:
159: \item SuSE/SLES
160:
161: Use yast -$>$ Network Services -$>$ HTTP Server -$>$ Server Modules to set ssl to enabled, and rewrite to enabled
162:
163:
164: \item Ubuntu
165:
166: \begin{quotation}
167: \texttt{sudo a2enmod ssl}
168:
169: \texttt{sudo a2enmod rewrite}
170:
171: \texttt{sudo a2ensite default-ssl.conf}
172: \end{quotation}
173:
174: Edit default-ssl.conf
175: replace ``DocumentRoot /var/www/html'' with ``DocumentRoot /home/httpd/html''
176: \end{enumerate}
177:
178: You also need to create an SSL certificate signing request and have it signed by a certificate authority,
179: before installing the signed certificate and the corresponding key. Also you will need to open port 443
180: in the firewall, and enable rewrites of http to https (see ``Encrypting server traffic with SSL''
181: \ref{Domain_Configuration_SSL} section for more information).
182:
183: \item Configure your SP to work with your institution's IdP
184:
185: Before customizing your Shibboleth SP to work with your IdP it is recommended to test the default configuration.
186:
187: /usr/sbin/shibd -t should report:
188:
189: overall configuration is loadable, check console for non-fatal problems
190:
191: After restarting your Apache server, the result of accessing the URL:
192:
193: https://$<$yourserver.edu$>$/Shibboleth.sso/Session
194:
195: should be: ``A valid session was not found.''
196:
197: A Shibboleth SP can also be tested with http://testshib.org/
198:
199: Once preliminary testing is complete you will need to edit /etc/shibboleth/shibboleth2.xml
200: based on information provided by your institution, for your SP to work with the appropriate IdP.
201: At a minimum the shibboleth2.xml file will need to contain the service hostname of your LON-CAPA server,
202: and the SP entityID. You should also set an e-mail address, for users to contact in case of errors.
203:
204: e.g.,
205:
206: \begin{verbatim}
207:
208: <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
209: xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
210: xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
211: xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
212: xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
213: logger="syslog.logger" clockSkew="180">
214:
215: <InProcess logger="native.logger">
216: <ISAPI normalizeRequest="true" safeHeaderNames="true">
217: <Site id="1" name="yourserver.someplace.edu"/>
218: </ISAPI>
219: </InProcess>
220:
221: <Host name="yourserver.someplace.edu">
222: <Path name="secure" authType="shibboleth" requireSession="true"/>
223: </Host>
224:
225: <ApplicationDefaults id="default" policyId="default"
226: entityID="https://yourserver.someplace.edu/shibboleth"
227: REMOTE_USER="eppn persistent-id targeted-id"
228: signing="false" encryption="false">
229:
230: <Sessions lifetime="28800" timeout="3600" checkAddress="false"
231: handlerURL="/Shibboleth.sso" handlerSSL="true"
232:
233: </Sessions>
234:
235: <Errors supportContact="helpdesk@someplace.edu"
236: logoLocation="/shibboleth-sp/logo.jpg"
237: styleSheet="/shibboleth-sp/main.css"/>
238: </ApplicationDefaults>
239: </SPConfig>
240:
241: \end{verbatim}
242:
243: REMOTE\_USER is used to pass on the primary identifier of the authenticated user. It should be set
244: to match an attribute or alias defined in the attribute-map.xml file. LON-CAPA uses this value
245: (\$r-$>$user in the mod\_perl environment) as the username of the user. The user's domain will be
246: either the value of the PerlVar lonSSOUserDomain, or if that is undefined, the PerlVar lonDefDomain.
247: If the attribute used for REMOTE\_USER is in the form: username@somewhere.edu, and somewhere.edu is
248: the ``internet domain'' (i.e., the last item in the colon separated list of entries for your server
249: in /home/httpd/lonTabs/hosts.tab), then LON-CAPA will automatically remove the @somewhere.edu, such
250: that \$r-$>$user will be just username.
251:
252: \item Add a custom Apache config file to include some PerlVars (for logout etc.)
253:
254: Add a file to your Apache conf directory named loncapa\_apache\_local$<$dom$>$.conf, where $<$dom$>$
255: is domain, to include items such as:
256:
257: \begin{verbatim}
1.4 ! raeburn 258: PerlSetVar lonSSOUserLogoutHeadFile_<dom>/home/httpd/html/adm/sso_logout_head
! 259: PerlSetVar lonSSOUserLogoutMessageFile_<dom> /home/httpd/html/adm/sso_logout_body
1.1 raeburn 260: PerlSetVar lonSSOUserUnknownRedirect /adm/sso_failed_login.html
261: PerlSetVar lonSSOUserDomain <dom>
262: \end{verbatim}
263:
264: and add the corresponding files owned by www:www in /home/httpd/html/adm/
265:
266: Notes:
267: \begin{enumerate}
268: \item
1.4 ! raeburn 269: All files will contain HTML mark-up, but the sso\_logout\_head item is a fragment
1.3 raeburn 270: inserted into the head block of the standard LON-CAPA logout page, and similarly,
1.4 ! raeburn 271: the sso\_logout\_body is a fragment inserted into the body of the page,
1.3 raeburn 272: whereas the sso\_failed\_login.html file should be a complete HTML document.
273:
274: If the name of the PerlVar ends \_$<$dom$>$ then the HTML fragment is only displayed
275: to SSO users from that particular domain. It is possible that a LON-CAPA user from another
276: domain might have used SSO authentication on a server in his/her home domain, and then switched
277: session to your server, (e.g., for co-author access to an Authoring Space in your domain).
278: In that particular case, if you wanted to display custom HTML, you should add a PerlVar with a
279: name ending in \_$<$otherdom$>$. If you include PerlVars for lonSSOUserLogoutHeadFile
280: and/or lonSSOUserLogoutMessageFile they will be included for SSO users who use the Logout link
281: on your LON-CAPA regardless of the user's domain.
1.1 raeburn 282:
283: \item
284: SAML 2 Single Logout (SLO) has limited support starting with IdP's running Shibboleth 2.4.
285: The $<$Logout$>$ element is used to enable and configure support for Logout protocols and behavior
286: within the SP, e.g.,
287: \begin{verbatim}
288: <Logout>SAML2 Local</Logout>
289: \end{verbatim}
290: to support both local, i.e., for the SP itself (Local), and also in a limited way for the IdP (SAML2).
291: In pre-2.4 Shibboleth2 /etc/shibboleth2.xml LogoutInitiators enable SP-initiated local logout
292: e.g., https://yourserver/Shibboleth.sso/Logout.
293:
294: Depending on the availability of SLO support from your institution's IdP you should craft an appropriate
1.4 ! raeburn 295: message to include in sso\_logout\_body. If you include a link to the URL for a local logout,
1.1 raeburn 296: you should indicate that access to other web applications using SSO may continue to be available, even
297: after logout from the specific SP. If no local logout is provided, then after logout from LON-CAPA,
298: the web browser needs to be quit, to ensure access to LON-CAPA requires re-authentication.
299:
300: \item
301: If you enable self-creation of SSO-authenticated users, then the sso\_failed\_login.html
302: document need not be created.
303:
304: Attributes provided to the SP by the IdP are available to LON-CAPA as Environment variables.
305: For Shibboleth SSO users, mapping of Shibboleth environment variable names to user data fields
306: can be set so that the appropriate user information is available at account creation time. The
307: mapping of variable name to LON-CAPA data name will be set by a domain cordinator using the
308: domain configuration screen for ``Users self-creating accounts''.
309:
310: Note: user data for a new user need not come from Environment variables populated by Shibboeth;
311: instead it can come from a customized get\_userinfo() routine in /home/httpd/lib/perl/localenroll.pm
312: (see Directory Information \ref{Institutional_Integration_Identity_Management} section).
313:
314: \end{enumerate}
315:
1.4 ! raeburn 316: e.g., sso\_logout\_body
1.1 raeburn 317:
318: \begin{verbatim}
319:
320: <p>
321: As your original log-in to LON-CAPA was authenticated by a central Shibboleth
322: Single Sign On service, your Shibboleth credentials are still valid.<br />
323: Until you close your web browser, web applications which support Shibboleth
324: Single Sign-on (including LON-CAPA) will not require you to re-enter your
325: username and password</p>
326: <p>
327: To expire your active Shibboleth authentication token you must quit your web
328: browser.
329: </p>
330:
331: \end{verbatim}
332:
333: e.g., sso\_failed\_login.html
334:
335: \begin{verbatim}
336:
337: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
338: "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
339: <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
340:
341: <head>
342: <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
343: <title>No LON-CAPA Account</title>
344: </head>
345: <body bgcolor="#ffffff">
346: <p>
347: You have authentication using Shibboleth Single Sign On service was
348: successful.<br />
349: However, you do not currently have a LON-CAPA account with the username
350: with which you authenticated.<br />
351: Policies at your institution do not allow you to create a LON-CAPA account
352: yourself, after successful authentication.
353: Please contact the <a href="/adm/helpdesk">LON-CAPA Helpdesk</a> for your
354: domain.
355: </p>
356: <p>
357: Your Shibboleth credentials are still valid.<br />
358: Until you close your web browser, web applications which support Shibboleth
359: Single Sign-on will not require you to re-enter your username and password
360: </p>
361: <p>
362: To expire your active Shibboleth authentication token you must quit your web
363: browser.
364: </p>
365: </body>
366: </html>
367:
368: \end{verbatim}
369:
370: \end{enumerate}
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to Institutional_Integration_Shibboleth.tex CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [LON-CAPA] / loncom / html / adm / help / tex