First we need to install and configure moonshot, its dependencies, and a local RADIUS server for testing
In a real deployment, a local RADIUS server is not needed, however it simplifies testing if one is available
gss-server and gss-client are standard Kerberos diagnostic tools, which give us a lot of information that is helpful for debugging
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.
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).
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.
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.
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.
If anonymity is required, you could use a Perl or Python script to generate something like user-789-camford.ac.uk.
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

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.
Moonshot will ultimately use RADSEC for communicating with the radius server – in which case you would use transport="TCP" in /etc/radsc.conf
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.
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.5.5.15.1.1.18 }" 127.0.0.1 host@localhost bar

The second uses Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)
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.
The important part is at the end – you should see output similar to what is on the previous slide.
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:
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:
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.
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!
After successfully logging in, don’t forget to type exit to end the SSH session and return to the root shell.
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