Modifying the PKI Policy

An example PKI policy is shown below. Trusted issuers are defined in the Trust elements enclosed in a PKI element. In this example, a base64-encoded certificate of the issuer of the HST certificates is introduced. Consequently, all the HST certificates are accepted as valid user credentials. The corresponding CRL distribution point is defined in the crl attribute.

Other trusted issuers may be added by defining a new Trust element for each trusted issuer.

The user's certificate is defined to be included in a SAML assertion by defining the Subject element's KeyInfoConfirmationData attribute as true. User's certificate is required by UAS to be able to perform a satu-hetu transformation in case of HST certificates. It may be omitted if the HST certificates are not used or if there is no need for the user's hetu.

Attributes to be sent to UAS are defined in the Attribute element. The name of the attribute is defined in the name attribute of the Add element. The content of the attribute is defined in the enclosed elements. In this example, three different attributes are defined. The username attribute is defined as a sha-1 digest (fingerprint) of the certificate. The username.dn attribute is defined as the subject-field of the certificate. The satu attribute is defined as the certificate subject-field's component with oid 2.5.4.5, which is satu in case of HST certificates.

Listing 1. Example policy.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<Policy xmlns="http://ubisecure.com/schema/certagent.xsd">
	<PKI>
		<!-- VRK Gov. CA for Citizen Qualified Certificates -->
	    <!-- CRL distribution point URL and trusted issuer's base64-encoded certificate --> 
		<Trust crl="ldap://ldap.fineid.fi:389/cn%3dVRK%20Gov.%20CA%20for%20Citizen%20Qualified%20Certificates,ou%3dValtion%20kansalaisvarmenteet,o%3dVaestorekisterikeskus%20CA,dmdName%3dFINEID,c%3dFI?certificateRevocationList??objectClass=cRLDistributionPoint">


MIIFjDCCBHSgAwIBAgIDAYiZMA0GCSqGSIb3DQEBBQUAMIGjMQswCQYDVQQGEwJG STEQMA4GA1UECBMHRmlubGFuZDEhMB8GA1UEChMYVmFlc3RvcmVraXN0ZXJpa2Vz a3VzIENBMSkwJwYDVQQLEyBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eSBTZXJ2aWNl czEZMBcGA1UECxMQVmFybWVubmVwYWx2ZWx1dDEZMBcGA1UEAxMQVlJLIEdvdi4g Um9vdCBDQTAeFw0wMzAxMTAxMjU5MDVaFw0xOTAxMDkxMjU4MzBaMIGhMQswCQYD VQQGEwJGSTEQMA4GA1UECBMHRmlubGFuZDEhMB8GA1UEChMYVmFlc3RvcmVraXN0 ZXJpa2Vza3VzIENBMSQwIgYDVQQLExtWYWx0aW9uIGthbnNhbGFpc3Zhcm1lbnRl ZXQxNzA1BgNVBAMTLlZSSyBHb3YuIENBIGZvciBDaXRpemVuIFF1YWxpZmllZCBD ZXJ0aWZpY2F0ZXMwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5Aj52 7olxDHOtkQQU+BG1FUs0xOy8Qw2z3NmgV7yOkYRwi/C7aAbvaye712q8APGiDa+P f0N/XzQNynWWyzC2krv+fQq5YjGypRbnvciAtGbJQSXBoX58eV6sd5CWLKGMo1gH xsXNU6L9v9XlSWLUH4xbYvQt+oxfptgJbK5E+71OYC8DL0KU6xmlEfuPNQZ1Rf3p qqlEfmQjP24ubcgy3ZAHVTFBh7rT66pw+L5zAVPYBCyUG7rdXHS9hulRa4Y8w3BF RBxbChHsc7tuKk9kQmNGhQAJ7CdJx3V5kPsrxnuztOunimeBKoB5X3wgvk9f64n6 0Jp0qumnY4l9V6oZAgMBAAGjggHHMIIBwzASBgNVHRMBAf8ECDAGAQH/AgEAMBEG CWCGSAGG+EIBAQQEAwIBBjCBywYDVR0gBIHDMIHAMIG9BgkqgXaEBQEKAQEwga8w gYQGCCsGAQUFBwICMHgadlZhcm1lbm5lcG9saXRpaWtrYSBvbiBzYWF0YXZpbGxh IC0gQ2VydGlmaWthdCBwb2xpY3kgZmlubnMgLSBDZXJ0aWZpY2F0ZSBwb2xpY3kg aXMgYXZhaWxhYmxlIGh0dHA6Ly93d3cuZmluZWlkLmZpL2NwczEwJgYIKwYBBQUH AgEWGmh0dHA6Ly93d3cuZmluZWlkLmZpL2NwczEvMEIGCCsGAQUFBwEBBDYwNDAy BggrBgEFBQcwAoYmaHR0cDovL3Byb3h5LmZpbmVpZC5maS9jYS92cmtyb290Yy5j cnQwDgYDVR0PAQH/BAQDAgHGMB8GA1UdIwQYMBaAFNvp4ZvS0SQL/KvjoGfqrpxL d/SwMDgGA1UdHwQxMC8wLaAroCmGJ2h0dHA6Ly9wcm94eS5maW5laWQuZmkvYXJs L3Zya3Jvb3RhLmNybDAdBgNVHQ4EFgQUiFpvHUJHgob91+kNslfPTVAoBBcwDQYJ KoZIhvcNAQEFBQADggEBAEXit6ypQO+0RbVTK57SKT1jsqE8dUiwL8oevvdBiFpR 4HxEZZy8e/OGAvF3Hc/Hjc8cOjlsYToqztg16cOFI4vHZ+yC8rWh4TpuWgvkS80h //jcweAayp6E/Z0z928vTNILBD34YJQvpU4u7jyhSaY3tzybKjlSAo5lahiI32a9 MNZXGoNv+j+MKq1NJkpgpy6/VEa5Z4RdRx43/EZhs45WvxTfER+nUC1loQngFKOS jdWG3GhOAh13nM9jYASBtC7ONddvoByfzwUOQ+BOf08R2bvZA+2CDFI8PuYqxCFv BMCpQSCdVL6tEYxeWIQb+uIQsfAEfjC3AQuTNh/UiW8=
	 	</Trust> 
	</PKI>
	<!-- Add certificate to saml assertion -->
		<Subject KeyInfoConfirmationData="true"/>
	<!-- Add attributes to saml assertion -->
		<Attributes>


		<!-- SHA-1 fingerprint -->
		<Add name="username"> 
			<Digest source="subject" algorithm="sha1" /> </Add>
		<!-- Subject's distinguished name -->
		<Add name="username.dn">
			<Field source="subject"/> </Add>
		<!-- Attribute 2.5.4.5 (satu in HST-certificates) -->
		<Add name="satu">
			<Attribute source="subject" oid="2.5.4.5"/>
		</Add>
	</Attributes>
</Policy>

PKI Policy

This chapter provides in-depth description of PKI policy files. Policy files are XML documents defining the trusted issuers and attributes to be sent to service provider.

File Structure

All PKI policy –related configuration files are located in certap/webapp/WEB-INF/uap/pki and all paths discussed in this chapter are relative to that directory.

By default, a policy file policy.xml is used for all service providers. However, this may not be sufficient in some installations. Therefore, it is possible to define different policy-file for each service provider by creating a mapping file policy.properties.

listing 2. Example policy.properties

https://example.com/uas/saml2/names/ac/hst.prod.1 = policy/hst_prod.xml
https://example.com/uas/saml2/names/ac/hst.test.1 = policy/hst_test.xml

Each line defines an entity id of a service provider and a policy file to be used. If mapping file is defined, all service providers must have an entry. If an entry is not found for specific service provider, authentication process fails.

PKI Policy XML-Document

An example of PKI policy XML document is provided below.

Listing 3. Example policy.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<Policy 
		xmlns="http://ubisecure.com/schema/certagent.xsd">
	<PKI>
		<Trust crl="ldap://ldap.fineid.fi:389/cn%3dVRK%20Gov.%20CA%20for%20Citizen%20Qualified%20Certificates,ou%3dValtion%20kansalaisvarmenteet,o%3dVaestorekisterikeskus%20CA,dmdName%3dFINEID,c%3dFI?certificateRevocationList??objectClass=cRLDistributionPoint">
			MIIFjDCCBHSgAwIBAgIDAYiZMA0GCSqGSIb3DQEBBQUAMIGjMQswCQYDVQQGEwJG
			STEQMA4GA1UECBMHRmlubGFuZDEhMB8GA1UEChMYVmFlc3RvcmVraXN0ZXJpa2Vz
			a3VzIENBMSkwJwYDVQQLEyBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eSBTZXJ2aWNl
			czEZMBcGA1UECxMQVmFybWVubmVwYWx2ZWx1dDEZMBcGA1UEAxMQVlJLIEdvdi4g
			Um9vdCBDQTAeFw0wMzAxMTAxMjU5MDVaFw0xOTAxMDkxMjU4MzBaMIGhMQswCQYD
			VQQGEwJGSTEQMA4GA1UECBMHRmlubGFuZDEhMB8GA1UEChMYVmFlc3RvcmVraXN0
			ZXJpa2Vza3VzIENBMSQwIgYDVQQLExtWYWx0aW9uIGthbnNhbGFpc3Zhcm1lbnRl
			ZXQxNzA1BgNVBAMTLlZSSyBHb3YuIENBIGZvciBDaXRpemVuIFF1YWxpZmllZCBD
			ZXJ0aWZpY2F0ZXMwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5Aj52
			7olxDHOtkQQU+BG1FUs0xOy8Qw2z3NmgV7yOkYRwi/C7aAbvaye712q8APGiDa+P
			f0N/XzQNynWWyzC2krv+fQq5YjGypRbnvciAtGbJQSXBoX58eV6sd5CWLKGMo1gH
			xsXNU6L9v9XlSWLUH4xbYvQt+oxfptgJbK5E+71OYC8DL0KU6xmlEfuPNQZ1Rf3p
			qqlEfmQjP24ubcgy3ZAHVTFBh7rT66pw+L5zAVPYBCyUG7rdXHS9hulRa4Y8w3BF
			RBxbChHsc7tuKk9kQmNGhQAJ7CdJx3V5kPsrxnuztOunimeBKoB5X3wgvk9f64n6
			0Jp0qumnY4l9V6oZAgMBAAGjggHHMIIBwzASBgNVHRMBAf8ECDAGAQH/AgEAMBEG
			CWCGSAGG+EIBAQQEAwIBBjCBywYDVR0gBIHDMIHAMIG9BgkqgXaEBQEKAQEwga8w
			gYQGCCsGAQUFBwICMHgadlZhcm1lbm5lcG9saXRpaWtrYSBvbiBzYWF0YXZpbGxh
			IC0gQ2VydGlmaWthdCBwb2xpY3kgZmlubnMgLSBDZXJ0aWZpY2F0ZSBwb2xpY3kg
			aXMgYXZhaWxhYmxlIGh0dHA6Ly93d3cuZmluZWlkLmZpL2NwczEwJgYIKwYBBQUH
			AgEWGmh0dHA6Ly93d3cuZmluZWlkLmZpL2NwczEvMEIGCCsGAQUFBwEBBDYwNDAy
			BggrBgEFBQcwAoYmaHR0cDovL3Byb3h5LmZpbmVpZC5maS9jYS92cmtyb290Yy5j
			cnQwDgYDVR0PAQH/BAQDAgHGMB8GA1UdIwQYMBaAFNvp4ZvS0SQL/KvjoGfqrpxL
			d/SwMDgGA1UdHwQxMC8wLaAroCmGJ2h0dHA6Ly9wcm94eS5maW5laWQuZmkvYXJs
			L3Zya3Jvb3RhLmNybDAdBgNVHQ4EFgQUiFpvHUJHgob91+kNslfPTVAoBBcwDQYJ
			KoZIhvcNAQEFBQADggEBAEXit6ypQO+0RbVTK57SKT1jsqE8dUiwL8oevvdBiFpR
			4HxEZZy8e/OGAvF3Hc/Hjc8cOjlsYToqztg16cOFI4vHZ+yC8rWh4TpuWgvkS80h
			//jcweAayp6E/Z0z928vTNILBD34YJQvpU4u7jyhSaY3tzybKjlSAo5lahiI32a9
			MNZXGoNv+j+MKq1NJkpgpy6/VEa5Z4RdRx43/EZhs45WvxTfER+nUC1loQngFKOS
			jdWG3GhOAh13nM9jYASBtC7ONddvoByfzwUOQ+BOf08R2bvZA+2CDFI8PuYqxCFv
			BMCpQSCdVL6tEYxeWIQb+uIQsfAEfjC3AQuTNh/UiW8=
		</Trust>
	</PKI> 


	<Subject KeyInfoConfirmationData="true"/> 

	<Attributes>
		<Add name="username">
			<Digest source="subject" algorithm="sha1" />
		</Add>
	<Add name="username.dn">
		<Field source="subject"/>
	</Add>
	<Add name="ais">
		<Field source="subject" normalize="altSecurityIdentities"/>
	</Add>
	<Add name="satu">
		<Attribute source="subject" oid="2.5.4.5"/>
	</Add>
	<Add name="username.name">
		<Concat>
			<Attribute source="subject" oid="2.5.4.4"/>
			<Text content="&#32"/>
			<Attribute source="subject" oid="2.5.4.42"/>
		</Concat>
	</Add>
	</Attributes>
</Policy>

The policy document defines the trusted CA certificates and their respective CRL (Certificate Revocation List) distribution points.

In addition to certificate path validation tasks, this configuration also defines the contents of the SAML Assertion. For example, the client certificate may be included in SAML assertion, specific attributes may be extracted from the certificate and relayed back to service provider, a fingerprint of the certificate may be computed with specified message digest algorithm, and several normalization schemes may be applied for extracted attributes.

The structure and data types of the configuration document are described in the following schema.

NOTE: This version is modified for improved readability and may differ from actual schema used.

Schema Explanation

The <Policy/> element

<xs:element name="Policy" type="PolicyType" />
<xs:complexType name="PolicyType">
	<xs:sequence>
		<xs:element ref="PKI" />
		<xs:element ref="Subject" />
		<xs:element ref="Attributes" />
	</xs:sequence>
</xs:complexType>

The policy element defines three required child elements: PKI, Subject and Attributes.

The <PKI/> element

<xs:element name="PKI" type="PKIType" />
<xs:complexType name="PKIType">
	<xs:sequence minOccurs="1" maxOccurs="unbounded">
		<xs:element ref="Trust" />
	</xs:sequence>
</xs:complexType>

The PKI element encapsulates <Trust/> definitions. At least one certificate authority (CA) must be configured.

The <Trust /> element

<xs:element name="Trust" type="TrustType" /> 
<xs:complexType name="TrustType">
	<xs:simpleContent>
		<xs:extension base="xs:base64Binary">
			<xs:attribute name="crl" type="xs:anyURI" />
		</xs:extension>
	</xs:simpleContent>
</xs:complexType>

The <Trust /> element represents a trusted certificate authority. The element contains an attribute defining a CRL distribution URL and the element contains a Base64-encoded certificate.

The <Subject /> element

<xs:element name="Subject" type="SubjectType" />
<xs:complexType name="SubjectType">
	<xs:attribute name="KeyInfoConfirmationData" type="xs:boolean" />
</xs:complexType>

The <Subject /> element contains a Boolean type attribute called KeyInfoConfirmationData which defines whether the client certificate sent to service provider in SAML assertion.

The <Attributes /> element

<xs:element name="Attributes" type="AttributesType" />
<xs:complexType name="AttributesType">
	<xs:sequence minOccurs="0" maxOccurs="unbounded">
		<xs:element ref="Add" />
	</xs:sequence>
</xs:complexType>

The <Attributes/> element is the container for response attributes. Response attributes are defined using the <Add/> directive.

The <Add /> element

<xs:element name="Add" type="AddType" />
<xs:complexType name="AddType">
	<xs:group ref="ValueGroup" />
	<xs:attribute name="name" type="xs:string" use="required" />
</xs:complexType>

This element is used to add response attributes to the assertion. Each <Add/> element can contain one of the child elements defined in ValueGroup.

<xs:group name="ValueGroup">
	<xs:choice>
		<xs:element ref="Attribute" />
		<xs:element ref="Concat" />
		<xs:element ref="Digest" />
		<xs:element ref="Field" />
		<xs:element ref="Text" />
	</xs:choice>
</xs:group>

The <Attribute /> element

<xs:element name="Attribute" type="AttributeType" />
<xs:complexType name="AttributeType">
	<xs:complexContent>
		<xs:attribute name="source" type="SourceAttributeType" use="required" />
		<xs:attribute name="oid" type="xs:string" use="required" />
	</xs:complexContent>
</xs:complexType>

The <Attribute /> element contains the source and OID attributes. OID-element represents an object identifier and the source defines if the OID is looked up from the distinguished name of the subject or the issuer.

The <Concat /> element

	<xs:element name="Concat" type="ConcatType" />
	<xs:complexType name="ConcatType">
		<xs:complexContent>
			<xs:group ref="ValueGroup" maxOccurs="unbounded" />
		</xs:complexContent>
	</xs:complexType>

The <Concat/> element concatenates information defined by elements of the ValueGroup definition. Each defined element is individually parsed to a textual representation and concatenated with each other to form a single string.

<xs:group name="ValueGroup">
	<xs:choice>
		<xs:element ref="Attribute" />
		<xs:element ref="Concat" />
		<xs:element ref="Digest" />
		<xs:element ref="Field" />
		<xs:element ref="Text" />
	</xs:choice>
</xs:group>

The <Digest /> element

<xs:element name="Digest" type="DigestType" />
<xs:complexType name="DigestType">
	<xs:complexContent>
		<xs:attribute name="source" type="SourceAttributeType" use="required" />
		<xs:attribute name="algorithm" use="required">
			<xs:simpleType>
				<xs:restriction base="xs:string">
					<xs:enumeration value="md5" />
					<xs:enumeration value="sha1" />
				</xs:restriction>
			</xs:simpleType> 
		</xs:attribute>
	</xs:complexContent>
</xs:complexType>

The <Digest /> element computes the hash of either the client's or CA's certificate. Allowed algorithms are md5 or sha-1, defined with the strings "md5" or "sha1".

The <Field /> element

<xs:element name="Field" type="FieldType" /> 
<xs:complexType name="FieldType">
<xs:complexContent>
<xs:attribute name="source" type="SourceAttributeType" use="required" />
<xs:attribute name="normalize" type="xs:string" use="optional" />
</xs:complexContent>
</xs:complexType>

The <Field /> element allows submitting either the subject's or CA's distinguished name. The names' string representations are, by default, serialized by the JDK X500Principal.toString() –method. The normalization routine can be controlled by defining one of the following values:

Value	Description
RFC1779	http://java.sun.com/j2se/1.5.0/docs/api/javax/security/auth/x500/X500Principal.html#getName(java.lang.String) This value is case insensitive
RFC2253	http://java.sun.com/j2se/1.5.0/docs/api/javax/security/auth/x500/X500Principal.html#getName(java.lang.String) This value is case insensitive
CANONICAL	http://java.sun.com/j2se/1.5.0/docs/api/javax/security/auth/x500/X500Principal.html#getName(java.lang.String) This value is case insensitive
altSecurityIdentities	https://msdn.microsoft.com/en-us/library/ms675221(v=vs.85).aspx This value is case sensitive. The normalization routine features reversing the subject's and issuer's DNs, replacing DN component names by a certain scheme and finally concatenating them to the form "<I>issuer dn<S>subject dn" The component name normalization scheme (Active Directory with Windows 2003 Service Pack 1) OID.2.5.4.3=CN OID.2.5.4.6=C OID.2.5.4.7=L OID.2.5.4.8=S OID.2.5.4.10=O OID.2.5.4.11=OU OID.2.5.4.12=T OID.2.5.4.4=SN OID.2.5.4.42=G OID.2.5.4.5=SERIALNUMBER

The <Text /> element

<xs:element name="Text" type="TextType" />
<xs:complexType name="TextType">
	<xs:complexContent>
		<xs:attribute name="content" type="xs:string" />
	</xs:complexContent>
</xs:complexType>

This element can be used to include arbitrary text in the response attributes or use the text in concatenation with other elements.

Browser not supported