Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for J2EE Agents

ProcedureTo Configure Web Services Security Support in J2EE Agents for Policy Agent 3.0

Before You Begin

The instructions that follow start with the assumption that OpenSSO Enterprise server and a J2EE agent instance have been properly installed and configured.

  1. Create a web service provider configuration for the web service provider endpoint protected by the J2EE Agent instance as follows:

    1. Log in to OpenSSO Enterprise Console as a user with AgentAdmin privileges, such as amadmin.

      The OpenSSO Enterprise login page is available at a URL similar in format to the following:

      http://OpenssoHost.example.com:58080/opensso
    2. Click the Access Control tab.

    3. Click the name of the appropriate realm, such as the following: /(Top Level Realm).

    4. Click the Agents tab.

    5. Click the Web Service Provider tab.

    6. Click the New button in the Agent section.

    7. Enter the full URL of the web service provider endpoint as the name of the Web Service Provider agent.

      For example, http://myhost.mydomain.com:8080/StockService/StockService.

    8. Enter a password.

    9. Click the Create button.

  2. Create an agent authenticator type agent profile as follows.

    This agent and its password will be used for the agent to authenticate to the OpenSSO Enterprise server.

    Fore more information about the agent authenticator, see About the Agent Authenticator in Policy Agent 3.0.

    1. Log in to OpenSSO Enterprise Console as a user with AgentAdmin privileges, such as amadmin.

    2. Click the Access Control tab.

    3. Click the name of the appropriate realm, such as the following: /(Top Level Realm).

    4. Click the Agents tab.

    5. Click on Agent Authenticator tab.

    6. Click the New button.

    7. Enter an agent authenticator name and password.

    8. Click the Create button.

    9. On the Agent Authenticator page, click the link for the newly created agent authenticator.

      The agent authenticator page is displayed. In the section labeled "Agent Profiles allowed to Read," two lists exist: Available and Selected. The Available list has all the available agents in the system, and the Selected list has all the agents whose configurations can be read by this agent authenticator.

    10. From the available list, select the following items:

      • The J2EE agent profile name (this is the profile name of a previously installed J2EE agent instance)

      • The web service provider agents protected by the J2EE agent

      • The item labeled SecurityTokenService

    11. Click Add to move the selected items from the Available list to the Selected list

    12. Click Save

  3. Stop the agent container.

  4. Edit the OpenSSOAgentBootstrap.properties file of the previously installed J2EE agent, as follow:

    The bootstrap file is located at the following location:

    PolicyAgent-base/AgentInstance-Dir/config
    

    For information about this location, see Table P–6

    1. Using your text editor of choice, open the OpenSSOAgentBootstrap.properties file.

    2. At the end of the bootstrap file, add five lines as follows:

      1. Add the following line:

        com.sun.identity.wss.trustclient.enablemetro=false
      2. Add the four following lines related to keystore information.

        The various place holders for these four lines must be replaced with the actual keystore information.

        com.sun.identity.saml.xmlsig.keystore=KeystorePathName
        com.sun.identity.saml.xmlsig.storepass=FileContainingEncryptedKeystorePassword
        com.sun.identity.saml.xmlsig.keypass=FileContainingEncryptedKeyPassword
        com.sun.identity.saml.xmlsig.certalias=KeyAliasName
        
    3. Change the value for the property named com.sun.identity.agents.app.username to the agent authenticator name.

      Therefore, the setting would be as such:

      com.sun.identity.agents.app.username = AgentAuthenticatorName
      

      where AgentAuthenticatorName represents the name provided for the agent authenticator as demonstrated previously in this task.

    4. Change the value for the property named com.iplanet.am.service.secret to the agent authenticator password.

      Therefore, the setting would be as such:

      com.iplanet.am.service.secret = EncryptedAgentAuthenticatorPassword
      

      where EncryptedAgentAuthenticatorPassword represents the encrypted version of the password provided for the agent authenticator as demonstrated previously in this task.


      Note –

      To encrypt the password, use the agentadmin --encrypt command as described in agentadmin --encrypt.


    5. Save and close the bootstrap file.

  5. Configure the J2EE agent to enable Web Services Security as follows:

    1. Using a browser, navigate through OpenSSO Enterprise Console to the agent properties of the J2EE agent that you want to configure.

      For the steps to navigate to the J2EE agent properties, see To Navigate in OpenSSO Enterprise 8.0 Console to the J2EE Agent Properties.

    2. Enable the property labeled Web Service Enable (Tab: Advanced, Name: com.sun.identity.agents.config.webservice.enable)

    3. Add the web service endpoint URIs as values for the property labeled Web Service End Points (Tab: Advanced, Name: com.sun.identity.agents.config.webservice.endpoint) as follows:

      1. Add a value, such as /StockService/StockService, in the New Value field and.

      2. Click Add.

    4. Add the web service endpoint related WSDL to the not enforced URI list (Tab: Advanced, Name: com.sun.identity.agents.config.notenforced.uri) as follows:

      com.sun.identity.agents.config.notenforced.uri[n]=your-wsp-endpointuri?wsdl*

      For example:

      com.sun.identity.agents.config.notenforced.uri[0]=/StockService/StockService?wsdl*

    5. Click Save on the Advanced page.

  6. Change the Security Token Service as follows:

    1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

    2. Click the Configuration tab.

    3. Click the Global tab.

    4. Click Security Token Service in the Global Properties list.

    5. Add a new value to the property labeled For the Trusted Issuers, in the Token Validation Attributes section as follows:

      1. For the Trusted Issuers property, enter the fully qualified domain name of the OpenSSO Enterprise server in the New Value field.

      2. Click Add.

      3. Click Save on the Security Token Service page.

  7. Set up a Web Services Security profile by following the substep alternative that fits your site's requirements.

    The J2EE agents in the Policy Agent 3.0 software set together with OpenSSO Enterprise server support various Web Services Security profiles including UsernameToken, X509Token, and SAML2 Token. The following alternative steps describe how to set up the four different profiles. Implement the substeps for the appropriate profile for your site's deployment.

    • Set up the UsernameToken-Plain profile as follow:

      1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

      2. Click the Access Control tab.

      3. Click the name of the appropriate realm, such as the following: /(Top Level Realm).

      4. Click the Agents tab.

      5. Click the Web Service Provider sub tab.

      6. Click the web service provider.

        For example, http://myhost.mydomain.com:8080/StockService/StockService.

      7. Select the checkbox next to UserNameToken-Plain to choose it as a Security Mechanism.

      8. In the Authentication Chain drop-down list, select ldapService.

      9. In the "Web Service End Point" field, enter the name of the web service provider.

        For example, http://myhost:mydomain.com:8080/StockService/StockService.

      10. (Optional) If you would like, you can choose to enable request signature verification, request decryption, response signing, and response encryption.

      11. Click Save on that page.

      12. Click “Back to Main Page.”

      13. Click the Web Service Client subtab.

      14. Click the corresponding web service client profile.

        The phrase “corresponding web service client profile” in this case refers to a client profile that you create. You can edit the default profile “wsc” or create a new web service client.

      15. Select UserNameToken-Plain as the Security Mechanism.

      16. (Optional) If applicable, you can choose to enable request signing, request encryption, response signature verification, and response decryption.


        Note –

        The web service client and web service provider signing and encryption should be in sync. For example, if in the web service client, the request signing is enabled, then in the web service provider the request signature verification should be enabled as well.


      17. Click Save on that page.

    • Set up the X509Token profile as described in the substeps that follow.

      1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

      2. Create an authentication module, such as certmod, assigning the following type: Certificate.

        See the Sun OpenSSO Enterprise 8.0 Administration Guide for more information about creating authentication modules and authentication chains.

      3. Create an authentication chain, such as certauth, that includes the module, such as certmod, that you just created in the previous substep.

      4. Navigate to the web service provider.

        For example, http://myhost.mydomain.com:8080/StockService/StockService.

      5. Select the checkbox next to X509Token to choose it as a Security Mechanism.

      6. In the Authentication Chain drop-down list, select the newly created authentication chain, such as certauth.

      7. In the "Web Service End Point" field, enter the name of web service provider.

        For example, http://myhost:mydomain.com:8080/StockService/StockService.

      8. (Optional) If you would like, you can choose to enable request signature verification, request decryption, response signing, and response encryption.

      9. Click Save on that page.

      10. Click “Back to Main Page.”

      11. Click the Web Service Client subtab.

      12. Select the corresponding web service client profile.

        The phrase “corresponding web service client profile” in this case refers to a client profile that you create. You can edit the default profile “wsc” or create a new web service client.

      13. Select X509Token as the Security Mechanism.

      14. (Optional) If applicable, you can choose to enable request signing, request encryption, response signature verification, and response decryption.


        Note –

        The web service client and web service provider signing and encryption should be in sync. For example, if in the web service client, the request signing is enabled, then in the web service provider the request signature verification should be enabled as well.


      15. Click Save on that page.

    • Set up the SAML2-HolderOfKey profile as described in the substeps that follow.

      1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

      2. Navigate to the web service provider.

        For example, http://myhost.mydomain.com:8080/StockService/StockService.

      3. Select the checkbox next to SAML2-HolderOfKey to choose it as a Security Mechanism.

      4. In the Authentication Chain drop-down list, select ldapService.

      5. If not already entered, enter urn:sun.wss.ssotoken in the field for Token Conversion Type.

      6. In the "Web Service End Point" field, enter the name of the web service provider.

        For example, http://myhost:mydomain.com:8080/StockService/StockService.

      7. (Optional) If you would like, you can choose to enable request signature verification, request decryption, response signing, and response encryption.

      8. Click Save on that page.

      9. Click “Back to Main Page.”

      10. Click the Web Service Client subtab.

      11. Select the corresponding web service client profile.

        The phrase “corresponding web service client profile” in this case refers to a client profile that you create. You can edit the default profile “wsc” or create a new web service client.

      12. Select SAML2-HolderOfKey as the Security Mechanism.

      13. (Optional) If applicable, you can choose to enable request signing, request encryption, response signature verification, and response decryption.


        Note –

        The web service client and web service provider signing and encryption should be in sync. For example, if in the web service client, the request signing is enabled, then in the web service provider the request signature verification should be enabled as well.


      14. Click Save on that page.

    • Set up the SAML2-SenderVouches profile as described in the substeps that follow.

      1. As a user with AgentAdmin privileges, such as amadmin, use a browser to log in to the OpenSSO Enterprise Console.

      2. Navigate to the web service provider.

        For example, http://myhost.mydomain.com:8080/StockService/StockService.

      3. Select the checkbox next to SAML2-SenderVouches to choose it as a Security Mechanism.

      4. In the Authentication Chain drop-down list, select ldapService.

      5. If not already entered, enter urn:sun.wss.ssotoken in the field for Token Conversion Type.

      6. In the "Web Service End Point" field, enter the name of the web service provider.

        For example, http://myhost:mydomain.com:8080/StockService/StockService.

      7. (Optional) If you would like, you can choose to enable request signature verification, request decryption, response signing, and response encryption.

      8. Click Save on that page.

      9. Click “Back to Main Page.”

      10. Click the Web Service Client subtab.

      11. Select the corresponding web service client profile.

        The phrase “corresponding web service client profile” in this case refers to a client profile that you create. You can edit the default profile “wsc” or create a new web service client.

      12. Select SAML2-SenderVouches as the Security Mechanism.

      13. (Optional) If applicable, you can choose to enable request signing, request encryption, response signature verification, and response decryption.


        Note –

        The web service client and web service provider signing and encryption should be in sync. For example, if in the web service client, the request signing is enabled, then in the web service provider the request signature verification should be enabled as well.


      14. Click Save on that page.

  8. Enable Web Services Security in the web service provider as described in the substeps that follow.

    1. Using your text editor of choice, open the web.xml file of the web service provider.

    2. Add the agent filter element as the first filter in the web.xml file.

      For example, add the following:

            <filter>
                <filter-name>Agent</filter-name>
                <filter-class> com.sun.identity.agents.filter.AmAgentFilter </filter-class>
            </filter> 
    3. Add the agent filter mapping element as the first filter mapping in the web.xml file.

      For example, add the following:

            <filter-mapping>
                <filter-name>Agent</filter-name>
                <url-pattern>/*</url-pattern>
                <dispatcher>REQUEST</dispatcher>
                <dispatcher>INCLUDE</dispatcher>
                <dispatcher>FORWARD</dispatcher>
                <dispatcher>ERROR</dispatcher>
            </filter-mapping> 
    4. Save and close the web.xml file.

  9. Recreate the web service provider .war file.

  10. Redeploy the web service provider on the application server.