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