X.509 certificates are used for XML signatures and XML encryption.
Certificates may be specified either programmatically or through configuration. In most cases it’s simpler to specify certificates through configuration.
A certificate may be stored in a file or in the Windows certificate store.
The following sections provide instructions of configuring X.509 certificates.
Local Provider Certificate File
The following configuration entry specifies the local provider’s certificate is contained in the file idp.pfx which is protected by password.
<IdentityProvider Name="ExampleIdentityProvider"
LocalCertificateFile="idp.pfx"
LocalCertificatePassword="password"/>
The certificate file path is not an absolute path and therefore is assumed to be relative to the application’s folder.
The following configuration entry specifies an absolute file path.
<IdentityProvider Name="ExampleIdentityProvider"
LocalCertificateFile="C:\\Certificates\\idp.pfx"
LocalCertificatePassword="password"/>
Partner Provider Certificate File
The following configuration entry specifies the partner provider’s certificate is contained in the file sp.cer.
<PartnerServiceProvider Name="ExampleServiceProvider"
PartnerCertificateFile="sp.cer"/>
The certificate file path is not an absolute path and therefore is assumed to be relative to the application’s folder.
No password is required with a partner certificate file as the file does not contain the private key.
The following configuration entry specifies an absolute file path.
<PartnerServiceProvider Name=" ExampleServiceProvider"
PartnerCertificateFile="C:\\Certificates\\sp.cer"/>
Encrypting the Certificate File Password
When using production certificate files the password should be encrypted. To do this, the ability to encrypt sections of web.config is employed.
The following configuration entry specifies the local provider’s certificate is contained in the file idp.pfx which is protected by an encrypted password.
<IdentityProvider Name="ExampleIdentityProvider"
LocalCertificateFile="idp.pfx"
LocalCertificatePasswordKey="certificateFilePassword"/>
The application’s web.config appSettings section must include the certificate password key.
The .NET framework’s aspnet_regiis utility application is used to encrypt the appSettings section. You must be run this utility as an administrator.
aspnet_regiis –pef appSettings C:\inetpub\wwwroot\ExampleIdentityProvider
The aspnet_regiis utility also is used to decrypt the section.
aspnet_regiis –pdf appSettings C:\inetpub\wwwroot\ExampleIdentityProvider
The IIS account under which the application runs must be granted permission to decrypt web.config.
aspnet_regiis -pa NetFrameworkConfigurationKey "IIS_IUSRS"
Managing the Windows Certificate Store
The Microsoft Management Console may be used to install and manage certificates in the Windows certificate store.
Running the MMC Certificates Snap-In
To run the MMC Certificates snap-in:
- Run the Microsoft Management Console (MMC) as an administrator.
- From the menu, click File > Add/Remove Snap-in…
- Select Certificates from the list of available snap-ins.
- Specify that the computer account for the local computer is to be managed.
Importing a PFX File
To import a certificate and private key contained in a pfx file into the Windows certificate store:
Select the Personal folder in the certificates tree.
From the menu, click Action > All Tasks > Import…
Browse to the pfx file to import.
Supply the password and optionally check the check box to mark the key as exportable.
Place the certificate in the Personal certificate store.
Click Finish to complete the import.
Confirm the certificate is listed and open it to review its details.
Note the certificate’s serial number.
Note the certificate’s thumbprint.
Note the certificate’s subject name.
Private Key Security
To add read permission for the private key:
Right click on the certificate to bring up the context menu and select All Tasks > Manage Private Keys…
Add permissions for the application account. For example, give the IIS_IUSRS group read permission. The user or group to permit is dependent on the version of IIS and its configuration.
Importing a CER File
To import a certificate contained in a cer file into the Windows certificate store:
Select the Personal folder in the certificates tree.
From the menu, click Action > All Tasks > Import…
Browse to the cer file to import.
Place the certificate in the Personal certificate store.
Click Finish to complete the import.
Confirm the certificate is listed and open it to review its details.
Note the certificate’s serial number.
Note the certificate’s thumbprint.
Note the certificate’s subject name.
Local Provider Certificate Store
The following configuration entry specifies the local provider’s certificate is contained in the Windows certificate store and is identified by the certificate’s serial number.
Serial numbers optionally may include separating space characters for readability.
If copying/pasting from the Windows certificate store, invisible Unicode characters may be included. It’s best to first paste to Notepad etc. to avoid these issues.
<IdentityProvider Name="ExampleIdentityProvider"
LocalCertificateSerialNumber="5896b16b7fcc9c9d4ef3ca1a9b2653bb"/>
The following configuration entry specifies the local provider’s certificate is contained in the Windows certificate store and is identified by the certificate’s thumbprint.
Thumbprints optionally may include separating space characters for readability.
If copying/pasting from the Windows certificate store, invisible Unicode characters may be included. It’s best to first paste to Notepad etc. to avoid these issues.
<IdentityProvider Name="ExampleIdentityProvider"
LocalCertificateThumbprint="371629967909a351de5017d6a3a51c6c15f3505c"/>
The following configuration entry specifies the local provider’s certificate is contained in the Windows certificate store and is identified by the certificate subject’s distinguished name.
<IdentityProvider Name="ExampleIdentityProvider"
LocalCertificateSubject="CN=www.idp.com"/>
Alternatively, some subset of the subject’s distinguished name that uniquely identifies the certificate may be used.
<IdentityProvider Name="ExampleIdentityProvider"
LocalCertificateSubject="www.idp.com"/>
Partner Provider Certificate Store
The following configuration entry specifies the partner provider’s certificate is contained in the Windows certificate store and is identified by the certificate’s serial number.
<PartnerServiceProvider Name="ExampleServiceProvider"
PartnerCertificateSerialNumber="44d1779d8c4c32ad4e8f8999e7891c59"/>
The following configuration entry specifies the partner provider’s certificate is contained in the Windows certificate store and is identified by the certificate’s thumbprint.
<PartnerServiceProvider Name="ExampleServiceProvider"
PartnerCertificateThumbprint="2d7b862dcbb6103207cdd75138c04ad2f1fb844c"/>
The following configuration entry specifies the partner provider’s certificate is contained in the Windows certificate store and is identified by the certificate subject’s distinguished name.
<PartnerServiceProvider Name="ExampleServiceProvider"
PartnerCertificateSubject="CN=www.sp.com"/>
Alternatively, some subset of the subject’s distinguished name that uniquely identifies the certificate may be used.
<PartnerServiceProvider Name="ExampleServiceProvider"
PartnerCertificateSubject="www.sp.com"/>