Chapter 10. Using Fedlets in .NET Applications
Prev   Next

Chapter 10. Using Fedlets in .NET Applications

This chapter explains how to use the Fedlet in your .NET application. You must configure the OpenAM .NET Fedlet to work with the identity provider.

Before you try the .NET Fedlet with OpenAM, create a hosted identity provider in a Circle of Trust to which you plan to add the Fedlet. You can perform these steps using the Create Hosted Identity Provider wizard on the Common Tasks page of the OpenAM console. The .NET Fedlet demo requires a signing key for the Identity Provider. For evaluation, use the test certificate installed with OpenAM.

Before configuring the .NET Fedlet, prepare Microsoft IIS 7 with ASP.NET v4. Import and configure access on Windows to any certificates and private keys the .NET Fedlet needs. Also prepare Windows to allow the .NET Fedlet to log messages to Windows Event Log.

Procedure 10.1. To Prepare IIS For Installing the .NET Fedlet

Microsoft Internet Information Server must be installed with ASP.NET v4 in order to support the .NET Fedlet application. The following steps describe how to set up IIS on Windows Server 2008 R2 to support the .NET Fedlet.

  1. Logon to the Windows server as Administrator.

  2. In Server Manager, add the IIS 7 role to install IIS 7.

    When adding the IIS 7 role, the wizard presents you with additional installation options. Under Application Development, select ASP.NET.

  3. Under Roles > Web Server (IIS) > Internet Information Services (IIS) Manager > server-name > Application Pools, change .NET Framework Version for your application pools to v4.0.

Procedure 10.2. To Import Test Key Pairs on Windows

OpenAM ships with a test key pair unpacked during deployment into a Java Key Store under OpenAM's configuration directory. You can import this key pair on Windows, so that the .NET Fedlet demo can use the certificate and private key to perform signing, encryption, and logging in Windows Event Log. The following steps describe how to get the key pair imported and available to the .NET Fedlet on Windows Server 2008 R2.

See Windows documentation for instructions on using your own key pair when you plan to deploy the .NET Fedlet in production.

  1. Move the key pair from the Java Key Store to a PKCS#12 key store.

    You can use the Java keytool command to perform this step on the system where OpenAM is installed if you do not have the command installed on the Windows system.

    $ keytool
 -importkeystore
 -srckeystore keystore.jks
 -destkeystore keystore.p12
 -srcstoretype JKS
 -deststoretype PKCS12
 -srcstorepass changeit
 -deststorepass changeit
 -srcalias test
 -destalias test
 -srckeypass changeit
 -destkeypass changeit
 -noprompt

  2. If necessary, copy the resulting keystore.p12 file to the Windows system.

  3. Open Microsoft Management Console.

    Select Start > Run, then enter mmc.

  4. In the console, add the Certificates snap-in for the Local Computer store.

  5. Select Certificates > Personal > More Actions > All Tasks > Import...

  6. In the Certificate Import Wizard select the keystore.p12 file to import the keys. The password is changeit.

    Also select Mark this key as exportable.

    Accept other defaults until you click Finish.

  7. In Certificates > Personal > Certificates > test > More Actions > Properties, make sure the Friendly name is test.

  8. Certificates > Personal > Certificates > test > More Actions > All Tasks > Manage Private Keys, add access for Everyone (or at least the IIS 7 account, IUSR).

Procedure 10.3. To Prepare Windows For .NET Fedlet Event Logging

After importing the key pair for the .NET Fedlet, edit the registry to add the key that allows the .NET Fedlet to write to the Windows Event Log, and create an Event Log Custom View for the .NET Fedlet.

  1. Edit the Windows registry.

    1. Open the Windows registry editor.

      Select Start > Run, then enter regedit.

    2. Browse to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application.

    3. Add a new key named Fedlet.

      Right-click Application > New > Key.

    4. Close the Windows registry editor.

  2. Add the Event Log Custom View.

    1. Select Start > Administrative Tools > Event Viewer.

    2. Select Action > Create Custom View...

    3. Select all Event level options.

    4. Select By source, and then in the drop-down menu, select Fedlet.

    5. Click OK to finish creating the custom view.

      When the .NET Fedlet logs messages, you can read them under Event Viewer (Local) > Custom Views > Fedlet.

Procedure 10.4. To Install the .NET Fedlet as a Demo Application

Follow these steps to configure and install the .NET Fedlet demo application. These instructions are sufficient to test single sign-on and single logout. If you want to try the attribute query test, see the procedure, Procedure 10.5, “To Try the .NET Fedlet Attribute Query”.

  1. Download the .NET Fedlet (Fedlet-aspnet.zip) from the OpenAM nightly builds page. Contact info@forgerock.com if you need .NET Fedlet support.

    Next, unpack the contents of the .zip file into a working directory.

    bin\

    This folder contains the Fedlet.dll library, that you copy to your application's bin\ folder.

    conf\

    This folder contains the templates you edit to prepare your Fedlet configuration, including the identity provider and Fedlet (SP) metadata for federation. The completed configuration files belong in your application's App_Data\ folder.

    readme.txt

    This file describes how to set up and configure .NET Fedlets.

    SampleApp\

    This folder contains the demo application.

  2. To ensure the .NET Fedlet can write messages to Windows Event Log, edit SampleApp\Web.config, to make sure that the certificate alias reflects the key pair installed in the Windows Local Computer Store and available to the IIS 7 application pool user.

    Default settings set the log level to write informational messages, and use the test key pair shipped with OpenAM.

    <appSettings>
    <add key="fedletLogLevel" value="info" />
    <add key="fedletMutualAuthCertAlias" value="test" />
</appSettings>

    The key pair specified by the fedletMutualAuthCertAlias is used for SSL Mutual Certificate authentication when the certificate based authentication is required by and configured for the web container where the Identity Provider is deployed.

  3. Edit the template files in the SampleApp\App_Data\ folder based on where you deploy the Fedlet demo application, and on how your identity provider is configured.

    • Edit fedlet.cot to set cot-name to the name of the Circle of Trust, and to set sun-fm-trusted-providers to include the entity ID of the identity provider, and the entity ID of the Fedlet service provider.

    • Edit sp.xml and sp-extended.xml to configure the entity IDs, URLs, and Circle of Trust names to correspond to your sample application.

    Example files for a .NET Fedlet deployed at http://openam.example.com/fedlet and an Identity Provider in OpenAM deployed at http://openam.example.com:8080/openam are available on the OpenAM Community Site. The Circle of Trust name in the examples is cot, and both entities use the test key pair.

  4. Export the identity provider metadata from OpenAM, and copy the resulting idp.xml and idp-extended.xml metadata to the Fedlet SampleApp\App_Data\ folder.

    $ ssoadm
 create-metadata-templ
 --entityid "http://openam.example.com:8080/openam"
 --adminid amadmin
 --password-file /tmp/pwd.txt
 --identityprovider /idp
 --meta-data-file idp.xml
 --extended-data-file idp-extended.xml
 --idpscertalias test

Hosted entity configuration was written to idp-extended.xml.
Hosted entity descriptor was written to idp.xml.

    You can also perform this step using ssoadm.jsp if it is enabled.

  5. Register the Fedlet with OpenAM as a remote service provider using the sp.xml and sp-extended.xml metadata.

    $ ssoadm
 import-entity
 --adminid amadmin
 --password-file /tmp/pwd.txt
 --cot fedlet-cot
 --meta-data-file sp.xml
 --extended-data-file sp-extended.xml

Import file, sp.xml.
Import file, sp-extended.xml.

    You can also perform this step in OpenAM console by selecting Federation > Entity Providers > Import Entity...

  6. Deploy the .NET Fedlet demo application in IIS.

    1. Add read and execute permissions for Everyone to the SampleApp folder.

    2. Add the .NET Fedlet as an application.

      Select IIS console > server-name > Sites > Default Web Site > View Applications > Add Applications.

      In the window to add the application, Alias is the deployment URI to the .NET Fedlet, so fedlet for /fedlet. Physical path is the file system path to the SampleApp folder.

    3. Restart IIS.

  7. Try the demo application links to run .NET Fedlet initiated single sign-on.

    At first try the .NET Fedlet as Administrator using Internet Explorer on the Windows system where you installed the Fedlet. This allows you to see more explicit error messages should any such messages appear.

    1. Access the .NET Fedlet.


      [D]

    2. Try SSO with user name demo, password changeit.


      [D]

      If you instead get HTTP 500.19 error status, ASP.NET did not register correctly. Register ASP.NET v4 manually as Administrator.

      PS C:\> C:\Windows\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i
Start installing ASP.NET (4.0.30319).
....
Finished installing ASP.NET (4.0.30319).
Procedure 10.5. To Try the .NET Fedlet Attribute Query

To try the .NET Fedlet Attribute Query test, the Identity Provider must be configured with the Attribute Authority (AttrAuth) type and should sign responses. The Fedlet must be configured to deal with signed and encrypted responses. Furthermore, map the attributes to request in both the Identity Provider and the Fedlet configurations.

  1. Add the Attribute Authority type to the hosted Identity Provider.

    1. On OpenAM where the Identity Provider is hosted, log in to OpenAM console as amadmin.

    2. Under Federation > Entity Providers, select the Identity Provider, and then click New..., even though you plan to change the configuration rather than create a new provider.

    3. Select the protocol of the provider: SAMLv2.

    4. In the Create SAMLv2 Entity Provider page, do the following.

      • Set the Realm.

      • Set the Entity Identifier to the same entity identifier you selected in the previous screen.

      • In the Attribute Authority section, set the Meta Alias for example to /attra, and set the Signing certificate alias and Encryption certificate alias values to test (to use the test certificate).

      • Click Create to save your changes.

        Disregard any error messages stating that the entity already exists.

      AttrAuth now appears in the list of Types for your Identity Provider.

  2. Under Federation > Entity Providers, click the Identity Provider link to open the provider's configuration.

  3. Make sure attributes for the query are mapped on the Identity Provider.

    Under IDP > Attribute Mapper, add the following values to the Attribute Map if they are not yet present.

    • cn=cn

    • sn=sn

    • uid=uid

    Click Save to save your changes.

  4. As described in the procedure, Procedure 10.4, “To Install the .NET Fedlet as a Demo Application”, export the Identity Provider metadata from OpenAM, and copy the resulting idp.xml and idp-extended.xml metadata to the .NET Fedlet SampleApp\App_Data\ folder.

  5. Update the .NET Fedlet configuration and metadata.

    1. To ensure the .NET Fedlet can write messages to Windows Event Log, edit SampleApp\Web.config, to make sure that the certificate alias reflects the key pair installed in the Windows Local Computer Store and available to the IIS 7 application pool user.

      Default settings set the log level to write informational messages, and use the test key pair shipped with OpenAM.

      <appSettings>
    <add key="fedletLogLevel" value="info" />
    <add key="fedletMutualAuthCertAlias" value="test" />
</appSettings>

      The key pair specified by the fedletMutualAuthCertAlias is used for SSL Mutual Certificate authentication when the certificate based authentication is required by and configured for the web container where the Identity Provider is deployed.

    2. Edit the .NET Fedlet metadata files in SampleApp\App_Data, fedlet.cot, sp.xml, and sp-extended.xml to replace the following if you have not already done so.

      • Replace FEDLET_COT with the name of the Circle of Trust.

      • Replace FEDLET_ENTITY_ID with the entity identifier such as http://openam.example.com/fedlet.

      • Replace FEDLET_DEPLOY_URI with the URL to the .NET Fedlet, generally theh same as the entity identifier.

      • Replace IDP_ENTITY_ID with the entity identifier of the Identity Provider such as http://openam.example.com:8080/openam.

    3. Set up signing and encryption in sp.xml for the .NET Fedlet.

      The Attribute Authority encrypts the response with the Fedlet's public key, and the Fedlet decrypts the response with its private key. You can set up both signing and encryption by adding a <KeyDescriptor> as the first element in the <SSODescriptor>, as in the following example.

      <KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </KeyDescriptor>
    <KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
      <EncryptionMethod
        Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
        <xenc:KeySize
          xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
          >128</xenc:KeySize>
      </EncryptionMethod>
    </KeyDescriptor>

      For the Attribute Query feature, add a <RoleDescriptor> to the <EntityDescriptor> after the <SSODescriptor>. The <RoleDescriptor> describes the certificates that are used for signing and encryption.

      <RoleDescriptor
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:query="urn:oasis:names:tc:SAML:metadata:ext:query"
        xsi:type="query:AttributeQueryDescriptorType"
        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </KeyDescriptor>
    <KeyDescriptor use="encryption">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>
MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
/FfwWigmrW0Y0Q==
          </ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
      <EncryptionMethod
        Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
        <xenc:KeySize
          xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
          >128</xenc:KeySize>
      </EncryptionMethod>
    </KeyDescriptor>
  </RoleDescriptor>

    4. Edit sp-extended.xml for your configuration.

      Set the signing and encryption certificate aliases.

      <Attribute name="signingCertAlias">
  <Value>test</Value>
</Attribute>
<Attribute name="encryptionCertAlias">
  <Value>test</Value>
</Attribute>

      Update the attribute map in to coincide with the mapped attributes on the Identity Provider.

      <Attribute name="attributeMap">
   <Value>cn=cn</Value>
   <Value>sn=sn</Value>
   <Value>uid=uid</Value>
</Attribute>

      Add a logout URL.

      <Attribute name="appLogoutUrl">
   <Value>http://openam.example.com/fedlet/logout.aspx</Value>
</Attribute>

      Add an <AttributeQueryConfig> to the <EntityDescriptor> that references the certificate aliases.

      <AttributeQueryConfig metaAlias="/attrQuery">
  <Attribute name="signingCertAlias">
    <Value>test</Value>
  </Attribute>
  <Attribute name="encryptionCertAlias">
    <Value>test</Value>
  </Attribute>
  <Attribute name="wantNameIDEncrypted">
    <Value>true</Value>
  </Attribute>
  <Attribute name="cotlist">
    <Value>cot</Value>
  </Attribute>
</AttributeQueryConfig>

    5. Check your work by comparing and contrasting your configuration with the sample configuration files on the OpenAM Community Site.

    6. In OpenAM console where the hosted Identity Provider is configured, under Federation > Entity Providers delete the .NET Fedlet configuration if it exists.

    7. Under Federation > Entity Providers, click Import Entity..., and then import the .NET Fedlet configuration using your sp.xml and sp-extended.xml metadata files.

  6. Deploy the .NET Fedlet as described in the deploy step of the procedure, Procedure 10.4, “To Install the .NET Fedlet as a Demo Application”, making sure you restart IIS.

  7. Try the .NET Fedlet Attribute Query test.

    At first try the .NET Fedlet as Administrator using Internet Explorer on the Windows system where you installed the Fedlet. This allows you to see more explicit error messages should any such messages appear.

    1. Access the .NET Fedlet.


      [D]

    2. Try SSO with user name demo, password changeit.


      [D]

      If you instead get HTTP 500.19 error status, ASP.NET did not register correctly. Register ASP.NET v4 manually as Administrator.

      PS C:\> C:\Windows\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i
Start installing ASP.NET (4.0.30319).
....
Finished installing ASP.NET (4.0.30319).

    3. At the bottom of the web page, et the attributes in the Attribute Query page to match the mapped attributes, and then click Send.

    4. Check that you see the attribute values in the response page.


      [D]
Prev   Next
Chapter 9. Using Fedlets in Java Web Applications Home Chapter 11. Using Secure Attribute Exchange