prepare.mdwn

   1 # Preparing to use Moonshot
   2
   3 This set of instructions assumes you are using system Kerberos libraries; some things will be relative to the installation prefix of Kerberos if you are using Kerberos built from source.
   4
   5
   6 First, look at the mech file in the mech_eap directory of the source tree. Copy this file to /etc/gss/mech (or on Debian/Ubuntu systems /usr/etc/gss/mech). The Debian path is a bug that will be fixed; this page will be updated after.
   7
   8 Then, create a symlink from /usr/lib/gss/mech_eap.so to the installed mech_eap.so. Are you getting the feeling you're running down some untested code paths here yet?
   9
  10 On Debian systems if you are using the system freeradius libraries make sure /usr/lib/freeradius is in your default linker search path. Perhaps edit /etc/ld.so.conf and run ldconfig. Yes, that too is a bug. If you are not using system freeradius libraries you probably have to do something similar.
  11
  12 Create a valid freeradius dictionary in $prefix/etc/radb/dictionary. This may be a bug as well.
  13
  14 # Configuring Kerberos
  15
  16 Configure Kerberos, you ask? But I'm not using Kerberos!
  17 True, but the Kerberos library is kind of self-centered at the moment and doesn't believe anyone would ever want to not use Kerberos.
  18 So, it requires that servers be able to set up Kerberos even if they never use it.
  19 Please see also a bug.
  20 So you want something like
  21
  22 Contents of /etc/krb5.conf:
  23
  24     [libdefaults]
  25         default_realm = YOUR_DOMAIN_ALL_CAPS
  26
  27 Then run ktutil
  28
  29     addprinc --password -p host/hostname.your_domain@YOUR_DOMAIN_ALL_CAPS -k 1 -e aes256-cts
  30
  31 Enter a password of your choice
  32
  33    wkt /etc/krb5.keytab
  34     quit
  35
  36 Then <code>chmod a+r /etc/krb5.keytab</code>. Note that would be a very bad thing to do if you actually were using Kerberos. It may still be a bad thing to do if you have services enabled that can potentially use Kerberos.
  37
  38 # Configuring libradsec
  39
  40         cat > $prefix/etc/radsec.conf << EOF
  41         config gss-eap {
  42             type = "UDP"
  43             server {
  44                 hostname = "127.0.0.1"
  45                 service = "1820"
  46                 secret = "$secret"
  47             }
  48         }
  49         EOF
  50
  51 $secret is the secret you share with the radius server, i.e. the "secret" entry in FreeRADIUS configuration "client" clause.
  52
  53
  54 Todo:
  55 * Set up RADIUS
  56
  57 # Using the Shibboleth SP
  58
  59 You can use the Shibboleth SP implementation as a value-added processing layer for RADIUS AVPs or SAML information obtained from the authenticating RADIUS service. The features of the SP are currently leveraged through the mech_eap GSS mechanism implementation. The information obtained from the RADIUS server is attached to the GSS security context as GSS naming extension attributes. The attributes may be simple string name/value pairs, SAML assertions, or even binary objects. The SP's attribute manipulation layers can be configured to map these GSS attributes into locally-defined alias, filter them according to policies, or use them to obtain additional information using, for example, SAML queries.
  60
  61 ## Technical Setup
  62
  63 Currently there is no build option for mech_eap that doesn't include the SP; this is likely to change in the future, but at the moment, the SP's libraries are always used in the build. The version used by the mechanism is unreleased code that will be part of the 2.5 SP release, and requires the latest development branches of the Shibboleth and OpenSAML libraries.
  64
  65 Out of the box, the SP "initializes" successfully but doesn't do anything particularly useful in most cases. Configuration of the SP is essentially the same as in the more usual Web SSO case, except that not all of the usual parts are relevant.
  66
  67 The current mech_eap instantiates the SP "in-process". This entails a certain degree of overhead and behavior from the SP that may be undesirable. As an example, access to local and remote configuration files involves the use of background threads to maintain currency; this reload capability could be disabled to improve startup time and limit resource usage.
  68
  69 A more practical direction will be to make use of the SP's support for offloading processing to the shibd daemon that is used in the typical web deployment. This is discussed below.
  70
  71 ### Metadata
  72
  73 Ordinarily metadata is a hard requirement for the SP to function, but this is less true with Moonshot. The main need for metadata will be if you wish to rely on attribute filtering policies that rely on it, chiefly the "scope" extension that allows the SP to filter out scoped attributes like eduPersonPrincipalName based on the source of the attribute. This is generally applicable only to SAML-sourced attributes, and in such cases the issuer of the assertion is the entity for which metadata is needed.
  74
  75 For the time being, the "normal" metadata used for SAML 2.0 IdPs is sufficient to drive the filtering engine. Moonshot-specific metadata may be defined in the future.
  76
  77 ### Attribute Configuration
  78
  79 The SP's three attribute subsystems are all usable with Moonshot.
  80
  81 [[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeExtractor]]
  82
  83 [[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeFilter]]
  84
  85 [[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeResolver]]
  86
  87 SAML assertions are automatically identified by mech_eap and passed in for processing, using the same XML-based extractor plugin that is familiar to Shibboleth deployers, configured via the "attribute-map.xml" file.
  88
  89 This same file format has been extended to support direct extraction of GSS naming extension attributes via a new "GSS" extractor plugin. To make this plugin available, it must be loaded:
  90
  91     <OutOfProcess logger="shibd.logger">
  92         <Extensions>
  93             <Library path="plugins.so" fatal="true"/>
  94         </Extensions>
  95     </OutOfProcess>
  96
  97 Within the "attribute-map.xml" file, you can create mappings for GSS extensions as follows:
  98
  99     <GSSAPIAttribute name="urn:ietf:params:gss-eap:radius-avp urn:x-radius:1" id="radius-1"/>
 100
 101 The "name" matches the naming extensions's identifier and the "id", as usual, is a local name for the attribute that may be more convenient for application use. You can also map multiple SAML or GSS attributes to the same local "id" to collapse multiple attribute types into one canonical form.
 102
 103 Other XML attributes defined for the <GSSAPIAttribute> element:
 104
 105 *authenticated="true|false" - allows processing to proceed only if the GSS attribute is authenticated
 106 *binary="true|false" - treats the GSS attribute as binary-valued