(no commit message)

[devwiki.git] / ConfiguringRHEL.mdwn

First we need to install and configure moonshot, its dependencies, and a local RADIUS server for testing<br />
In a real deployment, a local RADIUS server is not needed, however it simplifies testing if one is available<br />
__gss-server__ and __gss-client__ are standard Kerberos diagnostic tools, which give us a lot of information that is helpful for debugging<br />
Again, in a real deployment these are not required, but help with testing

This guide walks through deploying the client, IdP and SP portions of moonshot - depending on your target, some steps may be inappropriate.

## Environment
### LD_LIBRARY_PATH
__LD_LIBRARY_PATH__ has to have _/opt/moonshot/lib64/_ and _/usr/lib64/freeradius_ added to it.<br />
The best way to do this is create a file at _/etc/profile.d/moonshot.sh_, with the following:

    if \[[ $LD_LIBRARY_PATH != */opt/moonshot/lib64/:/usr/lib64/freeradius/* ]]
    then
        export LD_LIBRARY_PATH=/opt/moonshot/lib64/:/usr/lib64/freeradius/:$LD_LIBRARY_PATH
    fi

After, either restart your shell session, or:

    source /etc/profile.d/moonshot.sh

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.

### SELinux set to permissive
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_:

    echo 0 > /selinux/enforce

### EPEL
Moonshot needs __EPEL__ for a few extra libraries (as pulling them from a semi-supported repository is preferable to repackaging).<br />
The simplest way to install EPEL is:

    rpm -ivh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-5.noarch.rpm
    yum install epel-release

## Moonshot Packages
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 />
Example _/etc/yum.repos.d/moonshot.repo_

    [Moonshot]
    name=Moonshot
    baseurl=http://yum.dev.ja.net/RPMS/x86_64/
    gpgcheck=0

After setting up the repository definition, we'll set up a composite ORPS/IdP.

##Moonshot IdP
To install the diagnostic tools (only needed for testing) and the RADIUSd:

    yum install freeradius krb5-moonshot-devel moonshot-gss-eap

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:


    # This is a complete entry for "steve". Note that there is no Fall-Through
    # entry so that no DEFAULT entry will be used, and the user will NOT
    # get any attributes in addition to the ones listed here.
    #
    #   steve   Cleartext-Password := "testing"
    #   Service-Type = Framed-User,
    #   Framed-Protocol = PPP,

Uncomment the line beginning __steve__.

__Chargeable-User-Identity__ is the value used to decide what user account to log in the user as on the SSH server.<br />
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 />
If anonymity is required, you could use a Perl or Python script to generate something like __user-789-camford.ac.uk__.<br />
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.
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.
It is not guaranteed that __Chargeable-User-Identity__ will be used permanently – in the future a specific RADIUS attribute may be created instead.

To activate CUI insertion, Edit _/etc/raddb/sites-enabled/default_, and find the post-auth section, and add the following:

    update reply {
        Chargeable-User-Identity = "moonshot"
    }

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.

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:

                #update outer.reply {
                #       User-Name = "%{request:User-Name}"
                #}

Finally, set the EAP type in use by moonshot (EAP-TTLS) by editing _/etc/raddb/eap.conf_ 

    default_eap_type = md5

becomes:

    default_eap_type = ttls

Other EAP types should be supported (PEAP and MD5 tested).
 
FreeRADIUS now has a very minimal IdP/ORPS configuration, and can be started with:

    service radiusd restart

If you encounter any issues, you can run radius in debug mode to see what is going on internally.

    service radiusd stop
    radiusd -X

When in debug mode, FreeRADIUS acts as an interactive program, so it should be run on a separate console, or under GNU Screen.

##Moonshot Proper
First we need a minimal _/etc/radsec.conf_

    dictionary = "/etc/raddb/dictionary"
    
    realm gss-eap {
        type = "UDP"
        timeout = 5
        retries = 3
        server {
            hostname = "127.0.0.1"
            service = "1812"
            secret = "testing123"
        }
    }

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 />
Moonshot will ultimately use RADSEC for communicating with the radius server – in which case you would use __transport="TCP"__ in _/etc/radsc.conf_<br />
Ultimately, the final values depend on the deployment – probably the address, port and secret used by your ORPS.

###gss_eap_id

Next, a file is created in the home directory at _~/.gss\_eap\_id_ – this is the file that moonshot looks in for credentials.
The format is very simple – username followed by a password on separate lines.  For now, set it to:

    steve
    testing

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.

###Shibboleth

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.
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.

Delete _/etc/shibboleth/attribute-map.xml_ and replace it with:

    <Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <GSSAPIAttribute name="urn:ietf:params:gss-eap:radius-avp urn:x-radius:89" id="local-login-user"/>
    </Attributes>

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.

To load the moonshot extensions, under the root node in _/etc/shibboleth/shibboleth2.xml_, add:

    <Extensions>
        <Library path="plugins.so" fatal="true"/>
    </Extensions>

Further down the same file, find this line:

    <AttributeExtractor type="XML" validate="true" path="attribute-map.xml"/>

Directly underneath it, add:

    <AttributeExtractor type="GSSAPI" validate="true" path="attribute-map.xml"/>

Note that this file is sensitive to the order of statements.

###/etc/gss/mech

This file tells moonshot what encryption options are valid for use with GSS.

    #
    # Sample mechanism glue configuration for EAP GSS mechanism.
    #
    # Any encryption type supported by Kerberos can be defined as the
    # last element of the OID arc.
    #
    eap-aes128          1.3.6.1.4.1.5322.22.1.17        mech_eap.so
    eap-aes256          1.3.6.1.4.1.5322.22.1.18        mech_eap.so

##Testing Functionality

As mentioned earlier, we will be using the Kerberos test tools to make sure that things are working.<br />
To start the _gss-server_, run:

    /opt/moonshot/sbin/gss-server host@localhost &

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):

    /opt/moonshot/bin/gss-client -mech "{1 3 6 1 4 1 5322 22 1 18}" 127.0.0.1 host@localhost bar

The second uses __Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)__<br />
This chooses the "best" mutually-agreeable encryption method for between client and server.  To invoke the client using __SPNEGO__, use:

    /opt/moonshot/bin/gss-client -spnego 127.0.0.1 host@localhost bar

##Sample Output

    Attribute local-login-user Authenticated Complete
    
    moonshot
    
    6d6f6f6e73686f74
    
    UID: 501
    Accepted connection: "steve"
    Sending init_sec_context token (size=150)...continue needed...
    
    context flag: GSS_C_MUTUAL_FLAG
    context flag: GSS_C_REPLAY_FLAG
    context flag: GSS_C_SEQUENCE_FLAG
    context flag: GSS_C_CONF_FLAG 
    context flag: GSS_C_INTEG_FLAG 
    "steve" to "host/moonbuildcentos.dev.ja.net", lifetime -1, flags 13e, locally initiated, open
    Name type of source name is { 1 2 840 113554 1 2 1 1 }.
    Mechanism { 1 3 6 1 5 5 2 } supports 4 names
      0: { 1 2 840 113554 1 2 1 1 }
      1: { 1 2 840 113554 1 2 1 2 }
      2: { 1 2 840 113554 1 2 1 3 }
      3: { 1 2 840 113554 1 2 1 4 }
    Received message: "testing"
    Signature verified.
    NOOP token

Running _gss-client_ produces a massive amount of output.<br />
The important part is at the end – you should see output similar to what is on the previous slide.<br />
If you do not see the line:

    Attribute local-login-user Authenticated Complete

Then attribute mapping is not functioning properly, and you need to check your shibboleth configuration.

##SSH
To install moonshot-enabled SSH:

    yum install openssh-moonshot-clients openssh-moonshot-server

Inside _/etc/ssh/sshd\_config_, and if these values are not set already:<br />
Uncomment __UsePrivilegeSeparation__ and set it to __‘no’__

        UsePriviligeSeparation no

Uncomment __GSSAPIAuthentication__ and set it to __‘yes’__

        GSSAPIAuthentication yes

Uncomment __GSSAPIKeyExchange__ and set it to __‘yes’__

        GSSAPIKeyExchange yes

Inside _/etc/ssh/ssh\_config_ and if these values are not set already:<br />
Uncomment __GSSAPIAuthentication__ and set it to __‘yes’__

        GSSAPIAuthentication yes

Uncomment __GSSAPIKeyExchange__ and set it to __‘yes’__

        GSSAPIKeyExchange yes

###Running SSH

Finally, we need to start sshd on a seperate port:

    /opt/moonshot/sbin/sshd –p 2222

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 />
Also note, that sshd must be invoked with its full path, i.e. _/opt/moonshot/sbin/sshd._

Finally, try connecting with the following:

    /opt/moonshot/bin/ssh –p 2222 –l "" 127.0.0.1

With any luck, magic happens and you are logged in as the user specified in your _Chargeable-User-Identity_!<br />
After successfully logging in, don’t forget to type __exit__ to end the SSH session and return to the root shell.<br />
Note in the SSH client command, the option __-l ""__ – this signifies that no username is to be sent to the SSH server. 

##Common Issues:

If you see:

    connecting to server: Connection refused

_gss-server_ is not running – start it again, and check its output for any reasons why it doesn't stay running

If you see:

    GSS-API error initializing context: Unspecified GSS failure.  Minor code may provide more information
    GSS-API error initializing context: SPNEGO cannot find mechanisms to negotiate
    reading token flags: 0 bytes read

Then _/etc/gss/mech_ is invalid or missing

If you see:

    Sending init_sec_context token (size=101)...continue needed...
    CTRL-EVENT-EAP-STARTED EAP authentication started
    GSS-API error accepting context: Unspecified GSS failure.  Minor code may provide more information
    GSS-API error accepting context: 
    Sending init_sec_context token (size=43)...continue needed...
    GSS-API error initializing context: Unspecified GSS failure.  Minor code may provide more information
    GSS-API error initializing context: SPNEGO failed to negotiate a mechanism

Your RADIUS server may not be running, or malfunctioning, run it in debug mode (as mentioned earlier) to find out why.

If you see:

        Segmentation fault

Then _~/.gss\_eap\_id_ is invalid or missing

If you see:

        CTRL-EVENT-EAP-METHOD EAP vendor 0 method 4 (MD5) selected

Then you have not correctly set the _default\_eap\_type_ on the RADIUS server.

If you see:

    GSS-API error gss_pname_to_uid: Unspecified GSS failure.  Minor code may provide more information
    GSS-API error gss_pname_to_uid: Unknown error

Then there is not a local user that matches your Chargeable-User-Identity

If you see…

    /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

Then LD_LIBRARY_PATH is not properly set


##Remote IdP
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