ConfiguringRHEL.mdwn

   1 First we need to install and configure moonshot, its dependencies, and a local RADIUS server for testing<br />
   2 In a real deployment, a local RADIUS server is not needed, however it simplifies testing if one is available<br />
   3 __gss-server__ and __gss-client__ are standard Kerberos diagnostic tools, which give us a lot of information that is helpful for debugging<br />
   4 Again, in a real deployment these are not required, but help with testing
   5
   6 This guide walks through deploying the client, IdP and SP portions of moonshot - depending on your target, some steps may be inappropriate.
   7
   8 ## Environment
   9 ### LD_LIBRARY_PATH
  10 __LD_LIBRARY_PATH__ has to have _/opt/moonshot/lib64/_ and _/usr/lib64/freeradius_ added to it.<br />
  11 The best way to do this is create a file at _/etc/profile.d/moonshot.sh_, with the following:
  12
  13     if \[[ $LD_LIBRARY_PATH != */opt/moonshot/lib64/:/usr/lib64/freeradius/* ]]
  14     then
  15         export LD_LIBRARY_PATH=/opt/moonshot/lib64/:/usr/lib64/freeradius/:$LD_LIBRARY_PATH
  16     fi
  17
  18 After, either restart your shell session, or:
  19
  20     source /etc/profile.d/moonshot.sh
  21
  22 This is required as moonshot currently stores its modified libraries separately to the main system ones to avoid conflicts.  This should not be necessary in the future.
  23
  24 ### SELinux set to permissive
  25 Moonshot has a couple of outstanding issues regarding proper labeling of _SELinux_ contexts, causing it to fail when _SELinux_ is enforcing.  This should be resolved soon - change the setting in _/etc/sysconfig/selinux_, or in _/etc/rc.local_:
  26
  27     echo 0 > /selinux/enforce
  28
  29 ### EPEL
  30 Moonshot needs __EPEL__ for a few extra libraries (as pulling them from a semi-supported repository is preferable to repackaging).<br />
  31 The simplest way to install EPEL is:
  32
  33     rpm -ivh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-5.noarch.rpm
  34     yum install epel-release
  35
  36 ## Moonshot Packages
  37 The RPM's and SRPM's for moonshot are currently hosted at [[http://yum.dev.ja.net]] - this may change (and in fact, is quite likely to change) in the future.  The packages are currently unsigned.<br />
  38 Example _/etc/yum.repos.d/moonshot.repo_
  39
  40     [Moonshot]
  41     name=Moonshot
  42     baseurl=http://yum.dev.ja.net/RPMS/x86_64/
  43     gpgcheck=0
  44
  45 After setting up the repository definition, we'll set up a composite ORPS/IdP.
  46
  47 ##Moonshot IdP
  48 To install the diagnostic tools (only needed for testing) and the RADIUSd:
  49
  50     yum install freeradius krb5-moonshot-devel moonshot-gss-eap
  51
  52 Once FreeRADIUS is installed, a source of identity needs to be enabled - either the roaming network in the case of an ORPS, or AD/LDAP/etc for an IdP.  For now, we'll just use a flat file.  Open _/etc/raddb/users_ and locate the following fragment:
  53
  54
  55     # This is a complete entry for "steve". Note that there is no Fall-Through
  56     # entry so that no DEFAULT entry will be used, and the user will NOT
  57     # get any attributes in addition to the ones listed here.
  58     #
  59     #   steve   Cleartext-Password := "testing"
  60     #   Service-Type = Framed-User,
  61     #   Framed-Protocol = PPP,
  62
  63 Uncomment the line beginning __steve__.
  64
  65 __Chargeable-User-Identity__ is the value used to decide what user account to log in the user as on the SSH server.<br />
  66 This value would normally be set by your local RADIUS proxy (ORPS) – so in a real deployment, rather than statically logging the user in as __moonshot__ you may decide to use something like __steve-camford.ac.uk__.<br />
  67 If anonymity is required, you could use a Perl or Python script to generate something like __user-789-camford.ac.uk__.<br />
  68 The exact value does not matter – only that the mappings are consistent, so that the user gets access to the same local account each time.
  69 To allow creation of accounts on demand you could use __LDAP__ – when the ORPS sees a successful authentication, it could trigger a script that creates the desired account in an __LDAP__ domain.
  70 It is not guaranteed that __Chargeable-User-Identity__ will be used permanently – in the future a specific RADIUS attribute may be created instead.
  71
  72 To activate CUI insertion, Edit _/etc/raddb/sites-enabled/default_, and find the post-auth section, and add the following:
  73
  74     update reply {
  75         Chargeable-User-Identity = "moonshot"
  76     }
  77
  78 Note in the case of an ORPS you need to unfilter this attribute in _/etc/raddb/attrs_ to prevent this attribute from being stripped on roaming requests.
  79
  80 A legacy attribute required for SSH at this time is the user name returned by the IdP.  To make this happen, Edit _/etc/raddb/sites-enabled/inner-tunnel_, find the following and uncomment it:
  81
  82                 #update outer.reply {
  83                 #       User-Name = "%{request:User-Name}"
  84                 #}
  85
  86 Finally, set the EAP type in use by moonshot (EAP-TTLS) by editing _/etc/raddb/eap.conf_
  87
  88     default_eap_type = md5
  89
  90 becomes:
  91
  92     default_eap_type = ttls
  93
  94 Other EAP types should be supported (PEAP and MD5 tested).
  95
  96 FreeRADIUS now has a very minimal IdP/ORPS configuration, and can be started with:
  97
  98     service radiusd restart
  99
 100 If you encounter any issues, you can run radius in debug mode to see what is going on internally.
 101
 102     service radiusd stop
 103     radiusd -X
 104
 105 When in debug mode, FreeRADIUS acts as an interactive program, so it should be run on a separate console, or under GNU Screen.
 106
 107 ##Moonshot Proper
 108 First we need a minimal _/etc/radsec.conf_
 109
 110
 111     realm gss-eap {
 112         type = "UDP"
 113         timeout = 5
 114         retries = 3
 115         server {
 116             hostname = "127.0.0.1"
 117             service = "1812"
 118             secret = "testing123"
 119         }
 120     }
 121
 122 This tells the moonshot SP where to find a RADIUS server for authentication - in this case, we will use the local server just configured.<br />
 123 Moonshot will ultimately use RADSEC for communicating with the radius server – in which case you would use __transport="TCP"__ in _/etc/radsc.conf_<br />
 124 Ultimately, the final values depend on the deployment – probably the address, port and secret used by your ORPS.
 125
 126 ###gss_eap_id
 127
 128 Next, a file is created in the home directory at _~/.gss\_eap\_id_ – this is the file that moonshot looks in for credentials.
 129 The format is very simple – username followed by a password on separate lines.  For now, set it to:
 130
 131     steve
 132     testing
 133
 134 In a deployment with a GUI, this file is replaced by the Moonshot Identity Selector.  It is conceivable in the future that the Identity Selector GUI will be supplemented with a curses-like UI, or other mechanism allowing console usage.
 135
 136 ###Shibboleth
 137
 138 Moonshot uses _libshib_ to parse RADIUS and SAML attributes – SAML assertions can be embedded inside RADIUS responses by the IdP, allowing an ORPS to exercise a very fine-grained authorization policy.
 139 In the demo we just use a very simple example – mapping the _Chargeable-User-Identity_ to a local user account, but in a real deployment you could map a SAML attribute to the user account just as easily.
 140
 141 Delete _/etc/shibboleth/attribute-map.xml_ and replace it with:
 142
 143     <Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 144         <GSSAPIAttribute name="urn:ietf:params:gss-eap:radius-avp urn:x-radius:89" id="local-login-user"/>
 145     </Attributes>
 146
 147 In this case, 89 corresponds to _Chargeable-User-Identity_, which is mapped to _local-login-user_, which sets the local account that the user will be given access to.
 148
 149 To load the moonshot extensions, under the root node in _/etc/shibboleth/shibboleth2.xml_, add:
 150
 151     <Extensions>
 152         <Library path="plugins.so" fatal="true"/>
 153     </Extensions>
 154
 155 Further down the same file, find this line:
 156
 157     <AttributeExtractor type="XML" validate="true" path="attribute-map.xml"/>
 158
 159 Directly underneath it, add:
 160
 161     <AttributeExtractor type="GSSAPI" validate="true" path="attribute-map.xml"/>
 162
 163 Note that this file is sensitive to the order of statements.
 164
 165 ###/etc/gss/mech
 166
 167 This file tells moonshot what encryption options are valid for use with GSS.
 168
 169     #
 170     # Sample mechanism glue configuration for EAP GSS mechanism.
 171     #
 172     # Any encryption type supported by Kerberos can be defined as the
 173     # last element of the OID arc.
 174     #
 175     eap-aes128          1.3.6.1.4.1.5322.22.1.17        mech_eap.so
 176     eap-aes256          1.3.6.1.4.1.5322.22.1.18        mech_eap.so
 177
 178 ##Testing Functionality
 179
 180 As mentioned earlier, we will be using the Kerberos test tools to make sure that things are working.<br />
 181 To start the _gss-server_, run:
 182
 183     /opt/moonshot/sbin/gss-server host@localhost &
 184
 185 There are two ways to start _gss-client_ – the first specifies an encryption method to use by its OID 1.3.6.1.4.1.5322.22.1.18 (as seen in /etc/gss/mech):
 186
 187     /opt/moonshot/bin/gss-client -mech "{1.3.6.1.5.5.15.1.1.18 }" 127.0.0.1 host@localhost bar
 188
 189 The second uses __Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)__<br />
 190 This chooses the "best" mutually-agreeable encryption method for between client and server.  To invoke the client using __SPNEGO__, use:
 191
 192     /opt/moonshot/bin/gss-client -spnego 127.0.0.1 host@localhost bar
 193
 194 ##Sample Output
 195
 196     Attribute local-login-user Authenticated Complete
 197
 198     moonshot
 199
 200     6d6f6f6e73686f74
 201
 202     UID: 501
 203     Accepted connection: "steve"
 204     Sending init_sec_context token (size=150)...continue needed...
 205
 206     context flag: GSS_C_MUTUAL_FLAG
 207     context flag: GSS_C_REPLAY_FLAG
 208     context flag: GSS_C_SEQUENCE_FLAG
 209     context flag: GSS_C_CONF_FLAG
 210     context flag: GSS_C_INTEG_FLAG
 211     "steve" to "host/moonbuildcentos.dev.ja.net", lifetime -1, flags 13e, locally initiated, open
 212     Name type of source name is { 1 2 840 113554 1 2 1 1 }.
 213     Mechanism { 1 3 6 1 5 5 2 } supports 4 names
 214       0: { 1 2 840 113554 1 2 1 1 }
 215       1: { 1 2 840 113554 1 2 1 2 }
 216       2: { 1 2 840 113554 1 2 1 3 }
 217       3: { 1 2 840 113554 1 2 1 4 }
 218     Received message: "testing"
 219     Signature verified.
 220     NOOP token
 221
 222 Running _gss-client_ produces a massive amount of output.<br />
 223 The important part is at the end – you should see output similar to what is on the previous slide.<br />
 224 If you do not see the line:
 225
 226     Attribute local-login-user Authenticated Complete
 227
 228 Then attribute mapping is not functioning properly, and you need to check your shibboleth configuration.
 229
 230 ##SSH
 231 To install moonshot-enabled SSH:
 232
 233     yum install openssh-moonshot-clients openssh-moonshot-server
 234
 235 Inside _/etc/ssh/sshd\_config_, and if these values are not set already:<br />
 236 Uncomment __UsePrivilegeSeparation__ and set it to __‘no’__
 237
 238         UsePriviligeSeparation no
 239
 240 Uncomment __GSSAPIAuthentication__ and set it to __‘yes’__
 241
 242         GSSAPIAuthentication yes
 243
 244 Uncomment __GSSAPIKeyExchange__ and set it to __‘yes’__
 245
 246         GSSAPIKeyExchange yes
 247
 248 Inside _/etc/ssh/ssh\_config_ and if these values are not set already:<br />
 249 Uncomment __GSSAPIAuthentication__ and set it to __‘yes’__
 250
 251         GSSAPIAuthentication yes
 252
 253 Uncomment __GSSAPIKeyExchange__ and set it to __‘yes’__
 254
 255         GSSAPIKeyExchange yes
 256
 257 ###Running SSH
 258
 259 Finally, we need to start sshd on a seperate port:
 260
 261     /opt/moonshot/sbin/sshd –p 2222
 262
 263 At this time we do not recommend running __openssh-moonshot__ as the systemwide SSH client or server – it should be installed alongside the the standard SSH client and server.<br />
 264 Also note, that sshd must be invoked with its full path, i.e. _/opt/moonshot/sbin/sshd._
 265
 266 Finally, try connecting with the following:
 267
 268     /opt/moonshot/bin/ssh –p 2222 –l "" 127.0.0.1
 269
 270 With any luck, magic happens and you are logged in as the user specified in your _Chargeable-User-Identity_!<br />
 271 After successfully logging in, don’t forget to type __exit__ to end the SSH session and return to the root shell.<br />
 272 Note in the SSH client command, the option __-l ""__ – this signifies that no username is to be sent to the SSH server.
 273
 274 ##Common Issues:
 275
 276 ###If you see:
 277
 278     connecting to server: Connection refused
 279
 280 _gss-server_ is not running – start it again, and check its output for any reasons why it doesn't stay running
 281
 282 ###If you see:
 283
 284     GSS-API error initializing context: Unspecified GSS failure.  Minor code may provide more information
 285     GSS-API error initializing context: SPNEGO cannot find mechanisms to negotiate
 286     reading token flags: 0 bytes read
 287
 288 Then _/etc/gss/mech_ is invalid or missing
 289
 290 ###If you see:
 291
 292     Sending init_sec_context token (size=101)...continue needed...
 293     CTRL-EVENT-EAP-STARTED EAP authentication started
 294     GSS-API error accepting context: Unspecified GSS failure.  Minor code may provide more information
 295     GSS-API error accepting context:
 296     Sending init_sec_context token (size=43)...continue needed...
 297     GSS-API error initializing context: Unspecified GSS failure.  Minor code may provide more information
 298     GSS-API error initializing context: SPNEGO failed to negotiate a mechanism
 299
 300 Your RADIUS server may not be running, or malfunctioning, run it in debug mode (as mentioned earlier) to find out why.
 301
 302 ###If you see:
 303
 304         Segmentation fault
 305
 306 Then _~/.gss\_eap\_id_ is invalid or missing
 307
 308 ###If you see:
 309
 310         CTRL-EVENT-EAP-METHOD EAP vendor 0 method 4 (MD5) selected
 311
 312 Then you have not correctly set the _default\_eap\_type_ on the RADIUS server.
 313
 314 ###If you see:
 315
 316     GSS-API error gss_pname_to_uid: Unspecified GSS failure.  Minor code may provide more information
 317     GSS-API error gss_pname_to_uid: Unknown error
 318
 319 Then there is not a local user that matches your Chargeable-User-Identity
 320
 321 ###If you see…
 322
 323     /opt/moonshot/bin/gss-client: relocation error: /opt/moonshot/bin/gss-client: symbol gss_acquire_cred_with_password, version gssapi_krb5_2_MIT not defined in file libgssapi_krb5.so.2 with link time reference
 324
 325 Then LD_LIBRARY_PATH is not properly set
 326
 327
 328 ##Remote IdP
 329 This is left for an exercise for the user - at this stage it should just be a case of changing _/etc/radsec.conf_ to point at the right RADIUSd