4.1.2. Using the Moonshot-Host-TargetedId attribute in a database lookup

A typical Moonshot deployment uses three pseudonymous targeted identifiers as issued by a Moonshot IdP - the Moonshot-Host-TargetedId, Moonshot-Realm-TargetedId, and Moonshot-TR-COI-TargetedId. These are carried as ordinary RADIUS attributes - see Issue Pseudonymous Identifiers for further information on these identifiers and how an IdP is configured to issue them.

To use these identifiers as the incoming attribute to be used as the remote identifier for the user, do the following:

4.1.2.1.  Create a mapping policy configuration

1. In FreeRADIUS' /etc/raddb/policy.d directory, create a file named "moonshot".

2. In this file place the following content:

   moonshot_saml.post-auth {
     # if the request contains the GSS-Acceptor-* attributes and is not a trust router request
     if ( (&request:GSS-Acceptor-Service-Name) && (&request:GSS-Acceptor-Host-Name) && ("%{tolower:%{request:GSS-Acceptor-Service-Name}}" != 'trustidentity') ) {
       if (&reply:Moonshot-Host-TargetedId) {
         update reply {
           # do a query against the database to see if an account mapping exists for this Moonshot-Host-TargetedId, otherwise return the Targeted-Id
           Tmp-String-1 := "%{%{sql:SELECT account_id_map.local_uid FROM `account_id_map` WHERE account_id_map.gss_acceptor = '%{GSS-Acceptor-Service-Name}/%{GSS-Acceptor-Host-Name}' AND account_id_map.targeted_id = '%{reply:Moonshot-Host-TargetedId}'}:-%{reply:Moonshot-Host-TargetedId}}"
         }
       } # if TargetedId
    
       # erase incoming SAML Assertion
       update reply {
         SAML-AAA-Assertion !* ANY
       }
    
       # create a new SAML assertion, use the contents of control:Tmp-String-1 as the name (if it exists), otherwise use 'moonshot'
       update reply {
         SAML-AAA-Assertion = '<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" IssueInstant="2011-03-19T08:30:00Z" ID="foo" Version="2.0">'
         SAML-AAA-Assertion += '<saml:Issuer>urn:mace:incommon:osu.edu</saml:Issuer>'
         SAML-AAA-Assertion += '<saml:AttributeStatement>'
         SAML-AAA-Assertion += '<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7">'
         SAML-AAA-Assertion += "<saml:AttributeValue>%{%{reply:Tmp-String-1}:-moonshot}</saml:AttributeValue>"
         SAML-AAA-Assertion += '</saml:Attribute></saml:AttributeStatement>'
         SAML-AAA-Assertion += '</saml:Assertion>'
         User-Name := "%{%{reply:Tmp-String-1}:-moonshot}"
       }
     } # if gss-acceptor
   }

   The logic of the code above is simple but very constrained:

   1. You receive a reply from an ID Provider (including your own) in the Moonshot system.
   2. If it is a trust router request, don't do anything.
   3. If that reply contains the Moonshot-Host-TargetedId, execute a SQL query in your database for the Moonshot-Host-TargetedId.
      1. If there is a local account mapping for the Moonshot-Host-TargetedId, set the Tmp-String-1 attribute to the local account for it.
      2. If there is no local account mapping for Moonshot-Host-TargetedId, set the Tmp-String-1 attribute to the Moonshot-Host-TargetedId
   4. If the reply does not contain the Moonshot-Host-TargetedId, do nothing and Tmp-String-1 will not be set to anything.
   5. Next, delete any SAML assertion contained in the SAML-AAA-Assertion attributes in the reply.
   6. Finally, create a new SAML Assertion, but this time use the value of Tmp-String-1, if it exists. If it does not, use 'moonshot'.

4.2. Option 2 - Same local user identifier across all systems

4.2.1. Configure the Database

The first thing that is needed is a database to store these mappings. In your favourite database server software, create a table with three columns:

mysql> CREATE TABLE account_id_map (
	targeted_id varchar(256) NOT NULL, 
	local_uid varchar(32) NOT NULL default 'moonshot',
	auth_type smallint NOT NULL default 0,
	PRIMARY KEY (gss_acceptor,targeted_id)
);

The first column will store the incoming targeted identifier. The incoming value will generally be qualified, i.e., it will be a value with the incoming realm appended to it (for example, value@REALM). The width is limited to the maximum length of the SAML eduPersonTargetedID attribute. Alternatively, you may wish to use the maximum length of any RADIUS attribute (253 octets).

The second column is the local account name. The width is limited to the maximum length of useradd(8) on Unix. On Windows, underlying usernames are limited to 20 characters for compatibility purposes (see Microsoft TechNet: Active Directory Maximum Limits - Scalability for more information on this).

The third column is for information (and possibly integration) purposes and contains an identifier that identifies the service used. Suggested values are zero, indicating a local-to-local mapping, one indicating a Moonshot mapping, and any other value thereafter for clearly defined values as per your organisation's choice. This field could also indicate the level of assurance.

The primary key is the targeted_id, meaning that for a particular external user, only one mapping can exist.

5. Enabling the mapping policy

To use the policy, it has to be enabled by using it.

1. In /etc/freeradius/sites-enabled/abfab-tr-idp, find the post-auth section. At the top, insert onto its own line the following:

   moonshot_saml

   You can adjust where you want to call the policy that inserts the Moonshot policy, as long as it is called in the post-auth section of abfab-tr-idp.

   If you use non-TLS connections for Moonshot, you may wish to repeat Step 2 in /etc/freeradius/sites-enabled/default.

2. Restart FreeRADIUS.

6. Testing the mapping

Create a manual mapping entry in your database with a test user from Janet (please contact us for it).

1. Run FreeRADIUS in debug mode.
2. Execute an authentication request with the Janet test user. The debug output will include the Moonshot-Host-TargetedId that can be copied.

3. Insert the TargetedId together with the chosen username on your local systems with SQL:

   Option 1 - Different user identifiers per system

   mysql> INSERT INTO account_id_map 
   (gss_acceptor, targeted_id, local_uid, auth_type) 
   VALUES ('[value of your GSS-Acceptor-Service-Name]/[value of your GSS-Acceptor-Host-Name],'[value of Janet Moonshot-Host-TargetedId]', 
   '[value of local username to be used]', 1);

   Option 2 - Same user identifier across all systems

   mysql> INSERT INTO account_id_map 
   (targeted_id, local_uid, auth_type) 
   VALUES ([value of Janet Moonshot-Host-TargetedId]', 
   '[value of local username to be used]', 1);

4. Execute another authentication request with the Janet user. You should now see the local username in the SAML-AAA-Assertion.

6.1. Populating the mapping database

To populate the mapping database in a production environment, you will need to create a system that will require the user to log in twice, once with their local user (which should give you access to the local username), and once with Moonshot to gain access to one (or more) of the Moonshot TargetedIds. Then you will be able to create an entry in the database that contains the mapping.