<add> of <knownCertificates>

Article
09/15/2021

Adds an X.509 certificate to the collection of known certificates.

<configuration>
  <system.serviceModel>
    <behaviors>
      <serviceBehaviors>
        <behavior>
          <serviceCredentials>
            <issuedTokenAuthentication>
              <knownCertificates>
                <add>

Syntax

<knownCertificates>
   <add findValue="String"
      storeLocation="CurrentUser/LocalMachine"
      storeName="AddressBook/AuthRoot/CertificateAuthority/Disallowed/My/Root/TrustedPeople/TrustedPublisher"
      x509FindType="FindByThumbprint/FindBySubjectName/FindBySubjectDistinguishedName/FindByIssuerName/FindByIssuerDistinguishedName/FindBySerialNumber/FindByTimeValid/FindByTimeNotYetValid/FindBySerialNumber/FindByTimeExpired/FindByTemplateName/FindByApplicationPolicy/FindByCertificatePolicy/FindByExtension/FindByKeyUsage/FindBySubjectKeyIdentifier"/>
</knownCertificates>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute	Description
findValue	String. The value to search for.
storeLocation	Enumeration. One of the two store locations to search.
storeName	Enumeration. One of the system stores to search.
x509FindType	Enumeration. One of the certificate fields to search.

findValue Attribute

Value	Description
String	The value depends on the field (specified by the X509FindType attribute) being searched. For example, if searching for a thumbprint, the value must be a string of hexadecimal numbers.

x509FindType Attribute

Value	Description
Enumeration	Values include: FindByThumbprint, FindBySubjectName, FindBySubjectDistinguishedName, FindByIssuerName, FindByIssuerDistinguishedName, FindBySerialNumber, FindByTimeValid, FindByTimeNotYetValid, FindBySerialNumber, FindByTimeExpired, FindByTemplateName, FindByApplicationPolicy, FindByCertificatePolicy, FindByExtension, FindByKeyUsage, FindBySubjectKeyIdentifier.

storeLocation Attribute

Value	Description
Enumeration	CurrentUser or LocalMachine.

storeName Attribute

Value	Description
Enumeration	Values include: AddressBook, AuthRoot, CertificateAuthority, Disallowed, My, Root, TrustedPeople, and TrustedPublisher.

Child Elements

None.

Parent Elements

Element	Description
<knownCertificates>	Represents a collection of X.509 certificates that are provided by a Security Token Service (STS) for validation of security tokens.

Remarks

The issued token scenario has three stages. In the first stage, a client trying to access a service is referred to a secure token service. The secure token service then authenticates the client and subsequently issues the client a token, typically a Security Assertions Markup Language (SAML) token. The client then returns to the service with the token. The service examines the token for data that allows the service to authenticate the token and therefore the client. To authenticate the token, the certificate the secure token service uses must be known to the service.

The <issuedTokenAuthentication> element is the repository for any such secure token service certificates. To add certificates, use the <knownCertificates>. Insert an <add> element <knownCertificates> Element for each certificate, as shown in the following example.

<issuedTokenAuthentication>
  <knownCertificates>
    <add findValue="www.contoso.com"
         storeLocation="LocalMachine"
         storeName="My"
         X509FindType="FindBySubjectName" />
  </knownCertificates>
</issuedTokenAuthentication>

By default, the certificates must be obtained from a secure token service. These "known" certificates ensure that only legitimate clients can access a service.

To review conditions required for a client to be authenticated by a federated service, as well as more information on using this configuration element, see How to: Configure Credentials on a Federation Service. For more information about federated scenarios, see Federation and Issued Tokens.

Example

The following example adds certificate to the repository for any STS certificates.

<serviceBehaviors>
  <behavior name="myServiceBehavior">
    <serviceCredentials>
      <issuedTokenAuthentication>
        <knownCertificates>
          <add findValue="www.contoso.com"
               storeLocation="LocalMachine"
               storeName="CertificateAuthority"
               x509FindType="FindByIssuerName" />
        </knownCertificates>
      </issuedTokenAuthentication>
    </serviceCredentials>
  </behavior>
</serviceBehaviors>

Share via