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