Annotation of loncom/html/adm/help/tex/Institutional_Integration_Shibboleth.tex, revision 1.1
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,
! 20: SLES 10 & 11, and openSuSE 12.1, 12.2, and 12.3.
! 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}
! 258: PerlSetVar lonSSOUserLogoutMessageFile
! 259: /home/httpd/html/adm/sso_logout_link_html_frag
! 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
! 269: Both files contain HTML mark-up, but the logout link is just a fragment which will
! 270: be inserted into the standard LON-CAPA logout page, whereas the sso\_failed\_login.html file
! 271: should be a complete HTML document.
! 272:
! 273: \item
! 274: SAML 2 Single Logout (SLO) has limited support starting with IdP's running Shibboleth 2.4.
! 275: The $<$Logout$>$ element is used to enable and configure support for Logout protocols and behavior
! 276: within the SP, e.g.,
! 277: \begin{verbatim}
! 278: <Logout>SAML2 Local</Logout>
! 279: \end{verbatim}
! 280: to support both local, i.e., for the SP itself (Local), and also in a limited way for the IdP (SAML2).
! 281: In pre-2.4 Shibboleth2 /etc/shibboleth2.xml LogoutInitiators enable SP-initiated local logout
! 282: e.g., https://yourserver/Shibboleth.sso/Logout.
! 283:
! 284: Depending on the availability of SLO support from your institution's IdP you should craft an appropriate
! 285: message to include in sso\_logout\_link\_html\_frag. If you include a link to the URL for a local logout,
! 286: you should indicate that access to other web applications using SSO may continue to be available, even
! 287: after logout from the specific SP. If no local logout is provided, then after logout from LON-CAPA,
! 288: the web browser needs to be quit, to ensure access to LON-CAPA requires re-authentication.
! 289:
! 290: \item
! 291: If you enable self-creation of SSO-authenticated users, then the sso\_failed\_login.html
! 292: document need not be created.
! 293:
! 294: Attributes provided to the SP by the IdP are available to LON-CAPA as Environment variables.
! 295: For Shibboleth SSO users, mapping of Shibboleth environment variable names to user data fields
! 296: can be set so that the appropriate user information is available at account creation time. The
! 297: mapping of variable name to LON-CAPA data name will be set by a domain cordinator using the
! 298: domain configuration screen for ``Users self-creating accounts''.
! 299:
! 300: Note: user data for a new user need not come from Environment variables populated by Shibboeth;
! 301: instead it can come from a customized get\_userinfo() routine in /home/httpd/lib/perl/localenroll.pm
! 302: (see Directory Information \ref{Institutional_Integration_Identity_Management} section).
! 303:
! 304: \end{enumerate}
! 305:
! 306: e.g., sso\_logout\_link\_html\_frag
! 307:
! 308: \begin{verbatim}
! 309:
! 310: <p>
! 311: As your original log-in to LON-CAPA was authenticated by a central Shibboleth
! 312: Single Sign On service, your Shibboleth credentials are still valid.<br />
! 313: Until you close your web browser, web applications which support Shibboleth
! 314: Single Sign-on (including LON-CAPA) will not require you to re-enter your
! 315: username and password</p>
! 316: <p>
! 317: To expire your active Shibboleth authentication token you must quit your web
! 318: browser.
! 319: </p>
! 320:
! 321: \end{verbatim}
! 322:
! 323: e.g., sso\_failed\_login.html
! 324:
! 325: \begin{verbatim}
! 326:
! 327: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
! 328: "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! 329: <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
! 330:
! 331: <head>
! 332: <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
! 333: <title>No LON-CAPA Account</title>
! 334: </head>
! 335: <body bgcolor="#ffffff">
! 336: <p>
! 337: You have authentication using Shibboleth Single Sign On service was
! 338: successful.<br />
! 339: However, you do not currently have a LON-CAPA account with the username
! 340: with which you authenticated.<br />
! 341: Policies at your institution do not allow you to create a LON-CAPA account
! 342: yourself, after successful authentication.
! 343: Please contact the <a href="/adm/helpdesk">LON-CAPA Helpdesk</a> for your
! 344: domain.
! 345: </p>
! 346: <p>
! 347: Your Shibboleth credentials are still valid.<br />
! 348: Until you close your web browser, web applications which support Shibboleth
! 349: Single Sign-on will not require you to re-enter your username and password
! 350: </p>
! 351: <p>
! 352: To expire your active Shibboleth authentication token you must quit your web
! 353: browser.
! 354: </p>
! 355: </body>
! 356: </html>
! 357:
! 358: \end{verbatim}
! 359:
! 360: \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