SAML Attribute Service

The RadiantOne service supports SAML attribute queries. It responds to such queries with SAML assertions.

To configure RadiantOne as a SAML Attribute Service, three properties files are required:

1. AttributeService.properties

2. AttributeMapping.properties

3. IdMapping.properties

Examples of these files are included in RadiantOne and located here:

<RLI_HOME>/vds_server/conf/saml/server/

AttributeService.properties

For AttributeService.properties, some of the properties defined in this configuration file already have default values. See below for a list of the properties along with descriptions of each.

entityid

The entity ID as described in the SAML specifications. This will be the entity ID of the RadiantOne SAML Attribute Service. This property is mandatory.

metadatavaliditydelay

Defines the amount of time the RadiantOne SAML Attribute Service metadata will be valid after its generation. The value needs to be in minutes. This property is not mandatory. The default value if none is indicated is 1440 minutes (1 day).

assertionvaliditydelay

Defines the amount of time the assertions generated by the RadiantOne SAML Attribute Service will be valid after its generation. The value needs to be in minutes. This property is not mandatory. The default value if none is indicated is 10 minutes.

endpoint

The end point to which the relying parties need to target their request. This property is mandatory.

signaturecertificatepath

The path to the keystore used by all the signatures of the generated assertions. This property is mandatory.

signaturekeystorepassword

The password of the keystore defined in the property “signaturecertificatepath”. This property is mandatory.

signaturecertificatepassword

The password of the certificate having the alias “signaturecertificatealias” contained in the keystore “signaturecertificatepath”. This property is mandatory.

signaturecertificatealias

The alias of the certificate contained in the keystore “signaturecertificatepath” and that will be used for the signatures. This property is mandatory.

encryptioncertificatepath

The path to the keystore used by all the encryptions of the generated assertions. This property is not mandatory.

encryptionkeystorepassword

The password of the keystore defined in the property “encryptioncertificatepath”. This property is not mandatory.

encryptioncertificatepassword

The password of the certificate having the alias “encryptioncertificatealias” contained in the keystore “encryptioncertificatepath”. This property is not mandatory.

encryptioncertificatealias

The alias of the certificate contained in the keystore “encryptioncertificatepath” and that will be used for the encryptions. This property is not mandatory.

organizationname

The organization name owning the RadiantOne SAML Attribute Service. This property is not mandatory.

givennamecontactperson

The given name of the person to contact in the organization “organizationname”. This property is not mandatory.

surnamecontactperson

The surname of the person to contact in the organization “organizationname”. This property is not mandatory.

emailcontactperson

The email of the person to contact in the organization “organizationname”. This property is not mandatory.

phonecontactperson

The phone number of the person to contact in the organization “organizationname”. This property is not mandatory.

**nameidformatlist

The list of name ID formats supported by the Attribute Service. This property is not mandatory.

attributeprofilelist

The list of attribute profiles supported by the Attribute Service. This property is not mandatory.

attributelist

The attribute list that can be returned by the Attribute Service. This property is not mandatory.

signmetadata

If true, the metadata of the Attribute Service will be signed. This property is not mandatory. The default is false.

signassertions

If true, the assertions generated by the Attribute Service will be signed. This property is not mandatory. The default is false.

signresponses

If true, the SAML response element generated by the Attribute Service will be signed. This property is not mandatory. The default is false.

encryptassertions

If true, the assertions generated by the Attribute Service will be signed. This property is not mandatory. The default is false. acceptonlysignedmetadata

If true, only the relying parties providing signed metadata will be trusted by the Attribute Service. This property is not mandatory. The default is false.

acceptonlysignedrequests

If true, only the signed Attribute Queries will be accepted by the Attribute Service. This property is not mandatory. The default is false.

destinationinrequestmandatory

If true, the Attribute Queries need to contain a Destination attribute in order to be accepted by the Attribute Service. This property is not mandatory. The default is false.

The properties that are marked as mandatory in the list above need to have values. If one of them is not filled, it will be impossible for the RadiantOne SAML Attribute Service to generate its metadata and/or generate assertions in responses of the attribute queries that it will receive.

AttributeMapping.properties

This file indicates the mapping for the SAML format attributes from the request to those that appear in RadiantOne and corresponds to the values “queryAttribute” from the query.properties file. At least one mapping is required to be defined in this file. An example mapping is shown below:

mapping1=urn:idmanagement.gov:acag:ns:v1.0:mail - -> mail

IdMapping.properties

The IdMapping.properties file defines the format of the subject name ID and the value mapping, using regular expression. At least one mapping is required to be defined in this file.

There are two parts to the syntax: before >> : the format of the name ID (it corresponds to the value queryNameIDFormat from the query.properties file). After >> : the value mapping.

Before - -> is the regular expression filter used to match parts of the subject ID value, After - -> is the template with placeholders to be filled. The template can be a DN or an LDAP search URL.

mapping1=urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress >> (.+) --> o=companydirectory?1.1?sub?(mail=$1)

The mapping1 example does a subtree search under o=companydirectory, looking for the entry with “mail” value passed in the request’s subject name.

mapping2=subjectDN >> (.+) --> uid=$1,ou=Accounting,o=companydirectory

The mapping2 example looks for the specified DN where the $1 placeholder is replaced by the value passed in the request’s subject name.

RadiantOne Web Services Port

After modifying the AttributeService.properties, AttributeMapping.properties and IdMapping.properties files as described in the previous section, verify that the RadiantOne HTTP server is enabled. You can check this from the Main Control Panel ->Settings tab-> Server Front End -> Other Protocols as shown below.

Figure 1: RadiantOne HTTP Server Settings

If the HTTP server is enabled, restart the RadiantOne service.

If the HTTP server is not enabled, check the “Enable HTTP Server” box, click on the save button at the top of the screen and restart the RadiantOne service.

SAML Client Metadata

Copy all SAML client metadata files into <RLI_HOME>/<instanceName>/conf/saml/clients.

The SAML Attribute Service leverages the server certificate configured for RadiantOne which supports PKCS12.

To configure the SAML Attribute Service to use a PKCS12 keystore:

1. First, the PKCS12 keystore must be created. For more information on replacing the default self-signed SSL server certificate with a PKCS12 certificate, refer to the RadiantOne System Administration Guide.

2. In a file editor (such as Notepad), open the file client.properties, located at:

   <RLI_HOME>\config\saml

3. Replace the existing values for the parameters signKeystorePath and encKeystorePath with the full path and file name of the PKCS12 certificate/keystore created in step 1 above. This keystore must have a .p12 file extension. In the example below, the keystore, rli.p12, is located at $RLI_HOME/vds_server/conf.

   

   Figure 2: Modifying the Keystore Path Values in client.properties

4. Save the file.

5. In a command processor, navigate to the following location:

   <RLI_HOME>\bin\advanced

6. Execute the following command.

   samlUtils.bat client "C:\radiantone\vds\config\saml\client.properties" "C:\samlHelper\client.xml"

The URL to access the RadiantOne SAML Attribute Service is:

http[s]://<hostname>:<port>/saml/AttributeServiceSoap

An example is shown below:

http://vds.server.com:8089/saml/AttributeServiceSoap

This URL can be reach using the GET and POST HTTP verbs:

GET: by reaching the URL using a GET, the metadata of the RadiantOne SAML Attribute Service is sent to the requester. Do not use localhost as host name to retrieve the metadata. The IP Address or the host name of the machine hosting RadiantOne needs to be used instead.

POST: by reaching the URL using a POST, the requester can send an Attribute Query to the RadiantOne SAML Attribute Service. It responds with an SAML Assertion.

This URL can be used to get the RadiantOne SAML Attribute Service Metadata. An example of the metadata is shown below.

Figure 3: RadiantOne Attribute Service Metadata

RadiantOne includes a SAML client utility that can be used to test the RadiantOne SAML attribute service. This utility, samlUtils.bat (samlUtils.sh on UNIX), can be found in <RLI_HOME>\bin\advanced. In this section, you will perform the following functions.

• Generate the client metadata
• Create the SAML Attribute Query
• Decrypt the Response from the RadiantOne SAML Attribute Service

Generating the Client Metadata

First, the utility generates the client’s.xml metadata file. The attribute query service gets client information including the client’s ID and public key from this file. By default, the RadiantOne SAML Attribute Query service does not encrypt its responses. In this section, you will configure the client xml file to indicate that RadiantOne should encrypt its responses. The instructions in this section are performed on the server side.

1. The following property files are located at <RLI_HOME>/config/saml.

   • Client.properties

   
   The first section/paragraph in this file contains the client’s paramters used for encryption. The second section/paragraph contains the client’s parameters used for signing. The third section/paragraph contains other details about the client, one of which is the “clientEntityID” that must match the issuer in the query sent by the client.

   • Query.properties

   
   The first section/paragraph is used by the utility to sign the query. It must be the same as the first section/paragraph in the client.properties file described above. The second section/paragraph contains query parameters: “queryIssuer” – should have the same value as “clientEntityID” in the client.properties file; “queryNameID” – subject name ID. This is used via ID mapping to look for the corresponding DN in RadiantOne; “queryNameIDFormat” is the format of the previous name ID; “queryID” – the name of the query; “queryDestination” – represents the destination where the query is sent to. This should have the same value as the parameter “entityID” which is located at the top of the service’s metadata; “queryAttribute1, queryAttribute2, …” – the names of the attributes you want to retrieve from RadiantOne FID. If no queryAttributes are sent in the request, then the RadiantOne SAML attribute query service returns all attributes that have a mapping in the AttributeMapping.properties file.

   • ServerEncryption.properties

   
   Contains encryption parameters used by the utility to decrypt the response from the RadiantOne SAML attribute query service. RadiantOne uses the client’s public key to encrypt the response and the utility uses the client’s private key to decrypt it. The encryption parameters contained in this properties file should be the same as in the client.properties file described above.

2. Open a command line and navigate to the folder <RLI_HOME>\bin\advanced. Execute the following command (example shown assumes RadiantOne is installed at C:/radiantone/vds and there is a folder named samlHelper on the C drive where you want the client.xml file to be generated):

   samlUtils.bat client "C:/radiantone/vds/config/saml/client.properties" "C:/samlHelper/client.xml"

   If this command is executed successfully, the file, client.xml, is generated in c:/samlHelper.

3. Copy client.xml.

4. Navigate to <RLI_HOME>\vds_server\conf\saml\clients.

5. Delete the readme file located there.

6. Paste the client.xml file.

7. Navigate to <RLI_HOME>\vds_server\conf\saml\server.

8. Edit the AttributeService.properties file and change the value on line 24 from “encryptassertions=false” to “encryptassertions=true”.

9. Save and close AttributeService.properties.

Creating the SAML Attribute Query

Next, the utility generates an .xml file that contains an attribute query which the client will send to the RadiantOne SAML attribute service. In this example, the client requests the value of the attribute “mail” for the user identified as Aaron Medler. The instructions in this section are performed on the client side.

1. Return to the command line and execute the following command (example shown assumes RadiantOne is installed at C:/radiantone/vds and there is a folder named samlHelper on the C drive where you want the query.xml file to be generated).

   samlUtils.bat query "C:/radiantone/vds/config/saml/query.properties" "C:/samlHelper/query.xml"

   If this command is executed successfully, the file query.xml is created in C:/samlHelper.

2. Open query.xml and copy the content of the file (without character formatting).

3. Start the RadiantOne service.

4. Launch a web client. Refer to the table and image below for instructions on populating the fields in the web client.

![Sample SAML Attribute Query](Media/Image6.4.jpg)

Figure 4: Sample SAML Attribute Query

5. Click Send.

6. To confirm the success of the SAML attribute query, scroll down through the response. If the operation is successful, the response section contains the text “status:Success”, as shown below.

   

   Figure 5: Query Status Successful

7. If the operation is unsuccessful, the response section contains the text “status:RequestDenied”, as shown below.

Figure 6: Query Status Unsuccessful

Decrypting the Response from the RadiantOne SAML Attribute Service

Next, the client decrypts a response from the service. The instructions in this section are performed on the client side.

1. In the web client, copy the contents of the Response section.

2. Paste the contents of the Response section into a file editor such as Notepad.

3. Save the file. In this example, the file is saved as: “C:/samlHelper.encryptedResponse.xml”

4. In the command line, execute the following command (example shown assumes RadiantOne is installed at C:/radiantone/vds and there is a folder named samlHelper on the C drive where you want the decryptedResponse.xml file to be generated).

samlUtils.bat response "C:/radiantone/vds/config/saml/serverEncryption.properties" "C:/samlHelper/encryptedResponse.xml" "C:/samlHelper/decryptedResponse.xml"

5. Open the file “C:/samlHelper/decryptedResponse.xml” and scroll down to see the value of the requested attribute.

Figure 7: Sample Decrypted Response