# Preparing to use Moonshot
+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.
+
+
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.
-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?
+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? Your system may use /usr/lib64/gss, or /usr/lib/architecture-and-os/gss instead.
-On Debian systems 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.
+# Configuring libradsec
-Create a radsec.conf in $prefix/etc/radsec.conf.
+ cat > $prefix/etc/radsec.conf << EOF
+ realm gss-eap {
+ type = "UDP"
+ server {
+ hostname = "127.0.0.1"
+ service = "1812"
+ secret = "$secret"
+ }
+ }
+ EOF
-Create a valid freeradius dictionary in $prefix/share/freeradius/dictionary. This may be a bug as well.
+$secret is the secret you share with the radius server, i.e. the "secret" entry in FreeRADIUS configuration "client" clause.
-# Configuring Kerberos
-Configure Kerberos, you ask? But I'm not using Kerberos!
-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.
-So, it requires that servers be able to set up Kerberos even if they never use it.
-Please see also a bug.
-So you want something like
+Todo:
+* Set up RADIUS
-Contents of /etc/krb5.conf:
+# Using the Shibboleth SP
- [libdefaults]
- default_realm = YOUR_DOMAIN_ALL_CAPS
+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.
-Then run ktutil
+## Technical Setup
- addprinc --password -p host/hostname.your_domain@YOUR_DOMAIN_ALL_CAPS -k 1 -e aes256-cts
+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.
-Enter a password of your choice
+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.
- wkt /etc/krb5.keytab
- quit
+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.
-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.
+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.
+### Metadata
+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.
-Todo:
-* configure libradsec
-* Set up RADIUS
+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.
+
+### Attribute Configuration
+
+The SP's three attribute subsystems are all usable with Moonshot.
+
+[[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeExtractor]]
+
+[[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeFilter]]
+
+[[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeResolver]]
+
+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.
+
+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:
+
+ <OutOfProcess logger="shibd.logger">
+ <Extensions>
+ <Library path="plugins.so" fatal="true"/>
+ </Extensions>
+ </OutOfProcess>
+
+Within the "attribute-map.xml" file, you can create mappings for GSS extensions as follows:
+
+ <GSSAPIAttribute name="urn:ietf:params:gss-eap:radius-avp urn:x-radius:1" id="radius-1"/>
+
+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.
+
+Other XML attributes defined for the <GSSAPIAttribute> element:
+
+* authenticated="true|false" - allows processing to proceed only if the GSS attribute is authenticated
+* binary="true|false" - treats the GSS attribute as binary-valued
+
+### Daemon Use
+
+To move processing (and significant startup cost) outside of the GSS server process, you can patch mech_eap as follows:
+
+ --- a/moonshot/mech_eap/util_shib.cpp
+ +++ b/moonshot/mech_eap/util_shib.cpp
+ @@ -417,8 +417,7 @@ gss_eap_shib_attr_provider::initWithJsonObject(const gss_eap
+ bool
+ gss_eap_shib_attr_provider::init(void)
+ {
+ - if (SPConfig::getConfig().getFeatures() == 0 &&
+ - ShibbolethResolver::init() == false)
+ + if (ShibbolethResolver::init(SPConfig::InProcess) == false)
+ return false;
+
+ gss_eap_attr_ctx::registerProvider(ATTR_TYPE_LOCAL, createAttrContext);
+
+The shibresolver library also has to be loaded as an extension (exact path and filename vary by platform):
+
+ <OutOfProcess logger="shibd.logger">
+ <Extensions>
+ <Library path="plugins.so" fatal="true"/>
+ <Library path="/usr/lib/libshibresolver.so" fatal="true"/>
+ </Extensions>
+ </OutOfProcess>
+If you then run shibd, mech_eap's use of the SP will be remoted to it in the usual fashion.
projects / devwiki.git / blobdiff