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.
<appSettings>
<add key="certificateFilePassword" value="password"/>
</appSettings>
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.
|