1. Under Realms > Realm Name > Dashboard > Configure SAMLv2 Providers, click Create Hosted Identity Provider.

2. Unless you already have metadata for the provider, accept the Name for this identity provider in the field provided, or provide your own unique identifier.

   The default name is the URL to the current server which hosts the identity provider, and the default MetaAlias is idp.

   Note

   Ensure the MetaAlias is unique for each provider in a CoT and in the realm. If you need to create an identity provider with a different MetaAlias, navigate to Realms > Realm Name > Applications > Federation > Entity Providers, and select New in the Entity Providers table.

3. Select the Signing Key alias you imported into the AM keystore as part of your preparation for SAML v2.0 configuration.

4. Either add the provider to the circle of trust you already created, or select the Add to new option and provide a New Circle of Trust name.

5. For the attributes you share, map service provider attribute names (Name in Assertion), to user profile names from your identity repository (Local Attribute Name).

   Use this approach to set up a mapping with all SPs in the circle of trust that do not have their own specific mappings configured.

   The default mapping implementation has additional features beyond simply retrieving string attributes from the user profile.

   • Add an attribute that takes a static value by enclosing the profile attribute name in double quotes (").

     For example, you can add a static SAML attribute called partnerID with a value of staticPartnerIDValue by adding partnerID as the Name in Assertion with "staticPartnerIDValue" as the Local Attribute Name.

   • Base64 encode binary attributes when adding them to the SAML attributes by adding ;binary to the end of the attribute name, as in the following example:

     objectGUID=objectGUID;binary

     This maps the local binary attribute objectGUID to a SAML attribute called objectGUID that is Base64 encoded.

   • Use NameFormatURI format as shown in the following example:

     urn:oasis:names:tc:SAML:2.0:attrname-format:uri|objectGUID=objectGUID;binary

6. Click Configure to save your configuration.

7. Export the XML-based metadata from your provider to share with other providers in your circle of trust.

   $ curl \
    --output metadata.xml \
    "http://www.idp.example:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=\
    http://www.idp.example:8080/openam&realm=/realm-name"

   When you have configured your provider in the Top Level Realm, you can omit the query string from the URL.

   Alternatively, provide the URL to other providers so they can load the metadata.

1. Under Realms > Realm Name > Dashboard > Configure SAMLv2 Providers, click Create Hosted Service Provider.

2. Unless you already have metadata for the provider, accept the Name for this service provider in the field provided, or provide your own unique identifier.

   The default name is the URL to the current server which hosts the service provider, and the default MetaAlias is sp.

   Note

   Ensure the MetaAlias is unique for each provider in a CoT and in the realm. If you need to create a service provider with a different MetaAlias, navigate to Realms > Realm Name > Applications > Federation > Entity Providers, and select New in the Entity Providers table.

3. Either add the provider to the circle of trust you already created, or select the Add to new option and provide a New Circle of Trust name.

4. (Optional) If this SP requires more a different attribute mapping configuration than the default IdP attribute mapping, set the mapping in the Attribute Mapping section. Map identity provider attribute names in the Name in Assertion column to user profile names from your identity repository in the Local Attribute Name column.

5. Click Configure to save your configuration.

6. Export the XML-based metadata from your provider to share with other providers in your circle of trust:

   $ curl \
    --output metadata.xml \
    "http://www.sp.example:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=\
    http://www.sp.example:8080/openam&realm=/realm-name"

   When you have configured your provider in the Top Level Realm, you can omit the query string from the URL.

   Alternatively, provide the URL to other providers so they can load the metadata.

1. Obtain the identity provider metadata or the URL where you can obtain it.

2. Under Realms > Realm Name > Dashboard > Configure SAMLv2 Providers, click Configure Remote Identity Provider.

3. Provide the identity provider metadata or link to obtain metadata.

   The remote identity provider's metadata might contain more than one KeyDescriptor elements. If it does, the hosted AM service provider will validate assertions from the identity provider against certificates with key descriptors with an appropriate use attribute. Incoming assertions that cannot be validated against any of the certificates will be rejected by the hosted service provider.

   Note

   Ensure the MetaAlias is unique for each provider configured in a CoT and in the realm.

4. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

5. Click Configure to save your configuration.

1. Obtain the service provider metadata, or the URL where you can obtain it.

2. Under Realms > Realm Name > Dashboard > Configure SAMLv2 Providers, click Configure Remote Service Provider.

3. Provide the service provider metadata or link to obtain metadata.

   The remote service provider's metadata might contain more than one KeyDescriptor element. In this case, the hosted identity provider should consider any incoming SAML requests from the service provider to be valid as long as it can be validated with any of the certificates.

   Note

   Ensure the MetaAlias is unique for each provider configured in a CoT and in the realm.

4. (Optional) If the identity provider has not already mapped the attributes you share, map identity provider attribute names (Name in Assertion) to user profile names from your identity repository (Local Attribute Name).

   Use this approach to set up a mapping that is specific to this SP. Note that a remote SP-specific attribute mapping overrides the attribute mapping configuration specified in the hosted IdP configuration.

   The default mapping implementation has additional features beyond simply retrieving string attributes from the user profile.

   • Add an attribute that takes a static value by enclosing the profile attribute name in double quotes (").

     For example, you can add a static SAML attribute called partnerID with a value of staticPartnerIDValue by adding partnerID as the Name in Assertion with "staticPartnerIDValue" as the Local Attribute Name.

   • Base64 encode binary attributes when adding them to the SAML attributes by adding ;binary to the end of the attribute name, as in the following example:

     objectGUID=objectGUID;binary

     This maps the local binary attribute objectGUID to a SAML attribute called objectGUID that is Base64 encoded.

   • Use NameFormatURI format as shown in the following example:

     urn:oasis:names:tc:SAML:2.0:attrname-format:uri|objectGUID=objectGUID;binary

5. Either add the provider to the circle of trust you already created, or select Add to new and provide a New Circle of Trust name.

6. Click Configure to save your configuration.

How you deploy the discovery service .war file depends on your web application container. The procedure in this section shows how to deploy on Apache Tomcat.

1. Copy the IDPDiscovery-5.1.1.war file to the webapps/ directory.

   $ cp ~/Downloads/openam/IDPDiscovery-5.1.1.war \
    /path/to/tomcat/webapps/disco.war

2. Access the configuration screen through your browser.

   In this example, Apache Tomcat listens for HTTP requests on www.disco.example:8080, and Tomcat has unpacked the application under /disco, so the URL is http://www.disco.example:8080/disco, which redirects to Configurator.jsp.

1. Configure the identity provider discovery service.

   Completed Discovery Service Configuration Screen

   
   
   

   Hints for discovery service configuration parameters follow.

   Debug Directory

   The discovery service logs to flat files in this directory.

   Debug Level

   Default is error. Other options include error, warning, message, and off.

   Set this to message in order to see the service working when you run your initial tests.

   Cookie Type

   Set to PERSISTENT if you have configured AM to use persistent cookies, meaning single sign-on cookies that can continue to be valid after the browser is closed.

   Cookie Domain

   The cookie domain is the common cookie domain used in your circle of trust for identity provider discovery, in this case .disco.example.

   Secure Cookie

   Set this to true if clients should only return cookies when a secure connection is used.

   Encode Cookie

   Leave this true unless your AM installation requires that you do not encode cookies. Normally, cookies are encoded such that cookies remain valid in HTTP.

   HTTP-Only Cookie

   Set to true to use HTTPOnly cookies if needed to help prevent third-party programs and scripts from accessing the cookies.

2. Restrict permissions to the discovery service configuration file in $HOME/libIDPDiscoveryConfig.properties, where $HOME corresponds to the user who runs the web container where you deployed the service.

Each provider has a circle of trust including itself. You configure each of these circles of trust to use the identity provider discovery service as described in the following steps:

1. On the service provider console, login as AM Administrator.

2. On the service provider console, under Realms > Realm Name > Applications > SAML > Circle of Trust > Circle of Trust Name, add SAML2 Writer and Reader Service URLs for the identity provider discovery service endpoints, and save your work.

   In this example, the writer URL is http://www.disco.example:8080/disco/saml2writer, and the reader URL is http://www.disco.example:8080/disco/saml2reader.

3. On each identity provider console, login as AM Administrator.

4. On the identity provider console, under Realms > Realm Name > Applications > SAML > Entity Providers > Circle of Trust > Circle of Trust Name, also add SAML2 Writer and Reader Service URLs for the identity provider discovery service endpoints, and save your work.

Before performing these steps, install the administration tools for each provider as described in "Setting Up Administration Tools" in the Installation Guide. The administration tools include the ssoadm command that you need to export metadata:

1. On each identity provider console, register the service provider as a remote service provider adding to the circle of trust you configured to use the identity provider discovery service.

   The URL to the service provider metadata is something like http://www.sp.example:8080/openam/saml2/jsp/exportmetadata.jsp.

2. Create metadata templates for each identity provider:

   $ ssh www.this-idp.example
   $ cd /path/to/openam-tools/admin/openam/bin
   $ ./ssoadm \
    create-metadata-templ \
    --entityid "http://www.this-idp.example:8080/openam" \
    --adminid amadmin \
    --password-file /tmp/pwd.txt \
    --identityprovider /idp \
    --meta-data-file this-standard.xml \
    --extended-data-file this-extended.xml
   Hosted entity configuration was written to this-extended.xml.
   Hosted entity descriptor was written to this-standard.xml.
   
   $ ssh www.that-idp.example
   $ cd /path/to/openam-tools/admin/openam/bin
   $ ./ssoadm \
    create-metadata-templ \
    --entityid "http://www.that-idp.example:8080/openam" \
    --adminid amadmin \
    --password-file /tmp/pwd.txt \
    --identityprovider /idp \
    --meta-data-file that-standard.xml \
    --extended-data-file that-extended.xml
   
   Hosted entity configuration was written to that-extended.xml.
   Hosted entity descriptor was written to that-standard.xml.

3. For each identity provider extended metadata file, change the value of the hosted attribute to 0, meaning the identity provider is remote.

4. On the service provider, add the identity providers to the circle of trust using the identity provider metadata.

   $ ssh www.sp.example
   $ cd /path/to/openam-tools/admin/openam/bin
   $ ./ssoadm \
    import-entity \
    --cot discocot \
    --meta-data-file ~/Downloads/this-standard.xml \
    --extended-data-file ~/Downloads/this-extended.xml \
    --adminid amadmin \
    --password-file /tmp/pwd.txt
   
   Import file, /Users/mark/Downloads/this-standard.xml.
   Import file, /Users/mark/Downloads/this-extended.xml.
   $ ./ssoadm \
    import-entity \
    --cot discocot \
    --meta-data-file ~/Downloads/that-standard.xml \
    --extended-data-file ~/Downloads/that-extended.xml \
    --adminid amadmin \
    --password-file /tmp/pwd.txt
   
   Import file, /Users/mark/Downloads/that-standard.xml.
   Import file, /Users/mark/Downloads/that-extended.xml.

1. If you have not yet done so, set up AM as described in "To Create a Hosted Identity Provider". As part of the IdP configuration, you specify a signing key alias. In a subsequent step, you will provision Google Apps with this certificate's public key.

   For details about changing the signing certificate, see "To Change Default test Signing Key" in the Setup and Maintenance Guide.

2. Under Realms > Realm Name > Dashboard, click Configure Google Apps.

3. On the first Configure Google Apps for Single Sign-On page, add your domain name(s), such as example.com to the list, and then click Create.

4. On the second Configure Google Apps for Single Sign-On page, save the AM verification certificate to a text file, such as AM.pem.

5. Follow the instructions under To Enable Access to the Google Apps API before clicking Finish.

   1. Access the Google Apps administration page for the first of your domains in a new browser tab or window.

   2. Login as Google Apps administrator.

   3. Select Enable Single Sign-On.

   4. Copy the URLs from the AM page into the Google Apps setup screen.

   5. Upload the certificate file you saved, such as AM.pem as the Google Apps Verification Certificate.

   6. Select Use a domain specific issuer.

   7. Save changes in Google Apps setup.

   8. Repeat the steps above for each domain you have configured.

   9. Click Finish to complete the process.

1. If you have not yet done so, set up AM as described in "To Create a Hosted Identity Provider", using a signing certificate that is needed by Salesforce CRM.

   For details about changing the signing certificate, see "To Change Default test Signing Key" in the Setup and Maintenance Guide.

2. If you do not have an account with administrator credentials on Salesforce CRM, create one. See the Salesforce documentation for information about how to create an account with administrator credentials.

3. In a new browser tab or window, log in to Salesforce CRM with your administrator credentials.

4. If your users go directly to Salesforce to access services, then their single sign-on is SP-initiated from the Salesforce side. Salesforce provides a My Domain feature to facilitate SP-initiated single sign-on for desktop and device users.

   Configure SP-initiated single sign-on in Salesforce as follows:

   1. Select Setup Home > Settings > Company Settings > My Domain.

   2. Select the domain name, and then register the domain.

   3. Wait until the domain is ready for testing to proceed.

   4. After the domain has been created, log out of Salesforce.

   5. Log back in to Salesforce using the domain alias.

   6. Select Setup Home > Settings > Company Settings > My Domain.

   7. Click Deploy to Users.

5. In the AM console, under Realms > Realm Name > Dashboard, click Configure Salesforce CRM.

   Click Configure Salesforce CRM a second time to start the Configure Salesforce CRM wizard.

   The Configure Salesforce CRM for Single Sign-On page appears.

6. Specify values in the Configure Salesforce CRM for Single Sign-On page as follows:

   1. Specify the Salesforce service provider entity in the "Salesforce Service Provider entityID" field. For example, https://openam.my.salesforce.com.

      The entity ID is used as the persistent EntityDescriptor metadata element so that users can have multiple service provider instances. It also appears in the Entity Providers list in the Circle of Trust Configuration.

   2. Configure an attribute mapping to associate a Salesforce CRM attribute with the corresponding AM user profile attribute. For example, you might map the Salesforce CRM IDPEmail attribute to the AM mail attribute.

      The Configure Salesforce CRM wizard requires you to enter at least one attribute mapping.

   3. Click Add to insert the IDPEmail to mail mapping to the Remote to Local Attribute Mapping Table.

   4. If desired, configure additional attribute mappings.

7. Click Create.

   The following message appears:

   Metadata now configured successfully.
   Click OK to retrieve the parameters for configuring the Service Provider.

8. Click OK.

   A second Salesforce CRM Single Sign-On Configuration page appears.

9. Follow the instructions on the second Salesforce CRM Single Sign-On Configuration page:

   1. Specify single sign-on settings for Salesforce as follows:

      1. In Salesforce CRM, navigate to Setup Home > Settings > Identity > Single Sign-On Settings.

      2. Click Edit.

      3. Select the SAML Enabled option.

   2. Create a new SAML single sign-on configuration as follows:

      1. For Issuer, copy the issuer name from the Salesforce CRM Single Sign-On Configuration page in the AM Configure Salesforce CRM wizard.

      2. Set the Name and API Name fields to values of your choosing.

      3. Copy or download the AM verification certificate from the Salesforce CRM Single Sign-On Configuration page in the AM Configure Salesforce CRM wizard. Save the verification certificate to a plain text file.

      4. For Identity Provider Certificate, use the Browse button to locate and upload the file containing the AM verification certificate.

      5. For SAML Identity Type, select the "Assertion contains the Federation ID from the User object" option.

      6. For SAML Identity Location, select the "Identity is in an Attribute" option.

      7. Specify the Identity Provider Login URL as the URL for the AM IdP. For example, https://openam.example.com:8443/openam/SSOPOST/metaalias/idp.

      8. If you require a specific logout page, enter it in the Identity Provider Logout URL field.

      9. If you have a page to which you would like users redirected when encountering errors, enter the URL of your error page in the Custom Error URL field.

      10. Copy the attribute name, such as IDPEmail, from the Salesforce CRM Single Sign-On Configuration page in the AM Configure Salesforce CRM wizard to the Attribute Name field.

      11. Select the Entity ID corresponding to the "My Domain" that you set up.

      12. Click Save.

          The Salesforce Login URL appears.

   3. Perform the final steps required by the AM Configure Salesforce CRM wizard:

      1. Copy and paste the Salesforce Login URL to the Salesforce CRM Single Sign-On Configuration page in the AM Configure Salesforce CRM wizard.

      2. Click Finish to conclude operation of the AM Configure Salesforce CRM wizard.

   4. Return to the Single Sign-On Settings page in Salesforce.

   5. Click Download Metadata to download the Salesforce CRM SP metadata. You will import the metadata into AM in a subsequent step.

   6. Configure attribute mapping and name ID format for the AM identity provider:

      1. In the AM console, navigate to Realms > Realm Name > Applications > SAML > Entity Providers > Identity Provider Name > Assertion Processing.

      2. Review the values in the Attribute Map field, which should be the same values that you configured when you ran the Configure Salesforce CRM wizard. In this example, the values should be IDPEmail=mail.

         If required, modify the values in the Attribute Map field, and then click Save.

      3. In the AM console, navigate to Realms > Realm Name > Applications > SAML > Entity Providers > Identity Provider Name > Assertion Content > NameID Format.

      4. Salesforce requires SAML assertions that specify an unspecified name ID format. In this step, configure the AM-hosted IdP to support this requirement.

         If a value for an unspecified name ID format is already present in the NameID Value Map List, remove it from the list.

      5. Add the value urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified=attribute to the NameID Value Map List. For attribute, specify the attribute that you copied in Step 9.b.x. For example, urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified=mail.

      6. Click Save.

   7. Add users to Salesforce CRM:

      1. In Salesforce CRM, navigate to Setup Home > Administration > Users > Users.

      2. Click Users.

      3. Add users as necessary, making sure the attribute chosen as the Federation ID matches the local attribute you mapped to the remote attribute in AM.

      4. Click Finish.

10. Configure AM as the authentication provider for your Salesforce domain:

    1. In Salesforce CRM, navigate to Setup Home > Settings > Company Settings > My Domain.

    2. Click Edit in the Authentication Configuration section.

       The Authentication Configuration page appears, listing the available identity providers.

    3. Select the new Authentication Service.

    4. Click Save.

11. Reconfigure the remote service provider definition for Salesforce in AM by deleting the service provider definition created by the Configure Salesforce CRM wizard and then importing service provider metadata that you previously exported from Salesforce CRM:

    1. In the AM console, navigate to Realms > Realm Name > Applications > SAML > Entity Providers.

    2. Select the checkbox next to the entity provider definition for the Salesforce CRM service provider, which should be listed as an SP provider with a Remote location.

    3. Click Delete to remove the entity provider configuration.

    4. Click Import Entity.

       The Import Entity Provider page appears.

    5. Specify options on the Import Entity Provider page as follows:

       • Update the Realm Name if desired.

       • Click File as the location of the metadata file.

       • Use the Upload button to navigate to the location of the metadata file that you obtained from Salesforce in a previous step.

12. Add the new remote service provider definition for Salesforce CRM to the federation circle of trust in AM:

    1. In the AM console, navigate to Realms > Realm Name > Applications > SAML > Circle of Trust > Circle of Trust Name.

    2. Move the Salesforce CRM remote service provider from the Available column to the Selected column.

    3. Click Save.

    Configuring Salesforce CRM as a remote service provider is now complete. Users navigating to the Salesforce domain should be redirected to AM for authentication. Upon successful authentication, they should be logged in to Salesforce.

With just-in-time provisioning enabled, Salesforce CRM automatically creates regular and portal users when new users access Salesforce by authenticating to AM.

1. Add mappings to the AM identity provider configuration required by Salesforce just-in-time provisioning:

   1. In the AM console, navigate to Realms > Realm Name > Applications > SAML > Entity Providers > Identity Provider Name > Assertion Processing.

   2. Add the following entries to the Attribute Map property:

      • User.Email=mail

      • User.ProfileID="Standard User"

      • User.LastName=sn

      • User.Username=mail

   3. Click Save.

2. Enable user provisioning in Salesforce CRM:

   1. Log in to your Salesforce domain.

   2. In Salesforce CRM, navigate to Setup Home > Settings > Identity > Single Sign-On Settings.

   3. Click Edit.

   4. Set options in the Just-in-time User Provisioning section as follows:

      • Select the User Provisioning Enabled check box.

      • For User Provisioning Type, select Standard.

   5. Click Save.

   Configuring just-in-time provisioning in Salesforce CRM is now complete. When new users access Salesforce by authenticating to AM, Salesforce automatically creates regular and portal users.

The following steps demonstrate how to map accounts based on an attribute value that is the same in both accounts.

Perform the following steps on the hosted identity provider(s), and again on the hosted service provider(s):

1. Log in to the AM console as administrator.

2. Navigate to Realms > Realm Name > Applications > SAML > Entity Providers Hosted Provider Name > Assertion Processing.

3. If the attribute to use when linking accounts is not yet included in the attribute map, add the attribute mapping, and then save your work.

4. On the hosted service provider, under Auto Federation, select Enabled and enter the local attribute name in the Attribute field, and then save your work.

The following steps demonstrate how to auto-federate using a single anonymous user account on the service provider.

Perform the following steps on the hosted identity provider(s), and again on the hosted service provider(s):

1. Log in to the AM console as administrator.

2. Navigate to Realms > Realm Name > Applications > SAML > Entity Providers > Hosted Provider Name > Assertion Processing.

3. If you want to get attributes from the identity provider and the attributes are not yet in the attribute map, add the attribute mappings, and then save your work.

4. On the hosted service provider, under Transient User, set the single account to which to map all users, such as anonymous, and then save your work.

5. After completing configuration on the providers, use transient identifiers to federate as described in "Using Transient Federation Identifiers".

The following steps demonstrate how to map accounts with dynamic creation of missing accounts on the service provider side:

1. Set up a mapping based on an attribute value as described in "To Map Accounts Based on an Attribute Value". The attributes you map from the identity provider are those that the service provider sets on the dynamically created accounts.

2. On the service provider console, navigate to Realms > Realm Name > Authentication > Settings > User Profile. For the User Profile field, select Dynamic or Dynamic with User Alias, which are described in "User Profile" in the Authentication and Single Sign-On Guide, and then save your work.

3. To test your work, create a user on the identity provider, log out of the AM console, and initiate SSO by logging in as the user you created.

   To initiate SSO, navigate to one of the AM SAML v2.0 JSPs with the appropriate query parameters. The following is an example URL for service provider initiated SSO.

   http://www.sp.example:8080/openam/saml2/jsp/spSSOInit.jsp?
    idpEntityID=http%3A%2F%2Fwww.idp.example%3A8080%2Fopenam
    &metaAlias=/sp

   On success, check http://www.sp.example:8080/openam/idm/EndUser to see the new user account.

The FederationConfig.properties file specifies the paths to the JKS keystore holding the signing or encryption keys for the Fedlet, the keystore password file, and the private key password file.

1. After setting up your keystore and password files as described above, edit the properties file in the configuration directory, such as $HOME/fedlet/FederationConfig.properties, to point to the keystore and password files.

2. Export the certificate to use for signing and encryption purposes.

   $ keytool -export -rfc -keystore keystore.jks -alias test
   Enter keystore password:
   -----BEGIN CERTIFICATE-----
   MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh
   bGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w
   ZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw
   CQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK
   BgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
   AQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+
   RkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY
   Js0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U
   QzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA
   cGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC
   /FfwWigmrW0Y0Q==

3. Edit the standard metadata file for the Fedlet, such as $HOME/fedlet/sp.xml, to include the certificate in KeyDescriptor elements, that are children of the SPSSODescriptor element.

   <EntityDescriptor
    xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="http://www.example.com:8080/fedlet">
    <SPSSODescriptor
     AuthnRequestsSigned="true"
     WantAssertionsSigned="true"
     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>
     <SingleLogoutService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
      Location="http://www.example.com:8080/fedlet/fedletSloRedirect"
      ResponseLocation="http://www.example.com:8080/fedlet/fedletSloRedirect" />
     <SingleLogoutService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="http://www.example.com:8080/fedlet/fedletSloPOST"
      ResponseLocation="http://www.example.com:8080/fedlet/fedletSloPOST" />
     <SingleLogoutService
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
      Location="http://www.example.com:8080/fedlet/fedletSloSoap" />
     <NameIDFormat>
      urn:oasis:names:tc:SAML:2.0:nameid-format:transient
     </NameIDFormat>
     <AssertionConsumerService
      index="0"
      isDefault="true"
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="http://www.example.com:8080/fedlet/fedletapplication" />
     <AssertionConsumerService
      index="1"
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
      Location="http://www.example.com:8080/fedlet/fedletapplication" />
    </SPSSODescriptor>
    <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">
    </RoleDescriptor>
    <XACMLAuthzDecisionQueryDescriptor
     WantAssertionsSigned="false"
     protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" />
   </EntityDescriptor>

4. Edit the extended metadata file for the Fedlet, such as $HOME/fedlet/sp-extended.xml, to set the certificate alias names to the alias for the Fedlet certificate, and the want*Signed and want*Encrypted values to true.

   If you reformat the file, take care not to add white space around string values in elements.

   <EntityConfig xmlns="urn:sun:fm:SAML:2.0:entityconfig"
    xmlns:fm="urn:sun:fm:SAML:2.0:entityconfig" hosted="1"
    entityID="http://www.example.com:8080/fedlet">
    <SPSSOConfig metaAlias="/sp">
     <Attribute name="description">
      <Value></Value>
     </Attribute>
     <Attribute name="signingCertAlias">
      <Value>test</Value>
     </Attribute>
     <Attribute name="encryptionCertAlias">
      <Value>test</Value>
     </Attribute>
     <Attribute name="basicAuthOn">
      <Value>false</Value>
     </Attribute>
     <Attribute name="basicAuthUser">
      <Value></Value>
     </Attribute>
     <Attribute name="basicAuthPassword">
      <Value></Value>
     </Attribute>
     <Attribute name="autofedEnabled">
      <Value>false</Value>
     </Attribute>
     <Attribute name="autofedAttribute">
      <Value></Value>
     </Attribute>
     <Attribute name="transientUser">
      <Value>anonymous</Value>
     </Attribute>
     <Attribute name="spAdapter">
      <Value></Value>
     </Attribute>
     <Attribute name="spAdapterEnv">
      <Value></Value>
     </Attribute>
     <Attribute name="fedletAdapter">
      <Value>com.sun.identity.saml2.plugins.DefaultFedletAdapter</Value>
     </Attribute>
     <Attribute name="fedletAdapterEnv">
      <Value></Value>
     </Attribute>
     <Attribute name="spAccountMapper">
      <Value>com.sun.identity.saml2.plugins.DefaultLibrarySPAccountMapper</Value>
     </Attribute>
     <Attribute name="useNameIDAsSPUserID">
      <Value>false</Value>
     </Attribute>
     <Attribute name="spAttributeMapper">
      <Value>com.sun.identity.saml2.plugins.DefaultSPAttributeMapper</Value>
     </Attribute>
     <Attribute name="spAuthncontextMapper">
      <Value>com.sun.identity.saml2.plugins.DefaultSPAuthnContextMapper</Value>
     </Attribute>
     <Attribute name="spAuthncontextClassrefMapping">
      <Value
      >urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport|0|default</Value>
     </Attribute>
     <Attribute name="spAuthncontextComparisonType">
      <Value>exact</Value>
     </Attribute>
     <Attribute name="attributeMap">
      <Value>*=*</Value>
     </Attribute>
     <Attribute name="saml2AuthModuleName">
      <Value></Value>
     </Attribute>
     <Attribute name="localAuthURL">
      <Value></Value>
     </Attribute>
     <Attribute name="intermediateUrl">
      <Value></Value>
     </Attribute>
     <Attribute name="defaultRelayState">
      <Value></Value>
     </Attribute>
     <Attribute name="appLogoutUrl">
      <Value>http://www.example.com:8080/fedlet/logout</Value>
     </Attribute>
     <Attribute name="assertionTimeSkew">
      <Value>300</Value>
     </Attribute>
     <Attribute name="wantAttributeEncrypted">
      <Value>true</Value>
     </Attribute>
     <Attribute name="wantAssertionEncrypted">
      <Value>true</Value>
     </Attribute>
     <Attribute name="wantNameIDEncrypted">
      <Value>true</Value>
     </Attribute>
     <Attribute name="wantPOSTResponseSigned">
      <Value></Value>
     </Attribute>
     <Attribute name="wantArtifactResponseSigned">
      <Value></Value>
     </Attribute>
     <Attribute name="wantLogoutRequestSigned">
      <Value></Value>
     </Attribute>
     <Attribute name="wantLogoutResponseSigned">
      <Value></Value>
     </Attribute>
     <Attribute name="wantMNIRequestSigned">
      <Value></Value>
     </Attribute>
     <Attribute name="wantMNIResponseSigned">
      <Value></Value>
     </Attribute>
     <Attribute name="responseArtifactMessageEncoding">
      <Value>URI</Value>
     </Attribute>
     <Attribute name="cotlist">
      <Value>fedlet-cot</Value>
     </Attribute>
     <Attribute name="saeAppSecretList">
     </Attribute>
     <Attribute name="saeSPUrl">
      <Value></Value>
     </Attribute>
     <Attribute name="saeSPLogoutUrl">
     </Attribute>
     <Attribute name="ECPRequestIDPListFinderImpl">
      <Value>com.sun.identity.saml2.plugins.ECPIDPFinder</Value>
     </Attribute>
     <Attribute name="ECPRequestIDPList">
      <Value></Value>
     </Attribute>
     <Attribute name="ECPRequestIDPListGetComplete">
      <Value></Value>
     </Attribute>
     <Attribute name="enableIDPProxy">
      <Value>false</Value>
     </Attribute>
     <Attribute name="idpProxyList">
      <Value></Value>
     </Attribute>
     <Attribute name="idpProxyCount">
      <Value>0</Value>
     </Attribute>
     <Attribute name="useIntroductionForIDPProxy">
      <Value>false</Value>
     </Attribute>
     <Attribute name="spSessionSyncEnabled">
      <Value>false</Value>
     </Attribute>
     <Attribute name="relayStateUrlList">
     </Attribute>
    </SPSSOConfig>
    <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>fedlet-cot</Value>
     </Attribute>
    </AttributeQueryConfig>
    <XACMLAuthzDecisionQueryConfig metaAlias="/pep">
     <Attribute name="signingCertAlias">
      <Value>test</Value>
     </Attribute>
     <Attribute name="encryptionCertAlias">
      <Value>test</Value>
     </Attribute>
     <Attribute name="basicAuthOn">
      <Value>false</Value>
     </Attribute>
     <Attribute name="basicAuthUser">
      <Value></Value>
     </Attribute>
     <Attribute name="basicAuthPassword">
      <Value></Value>
     </Attribute>
     <Attribute name="wantXACMLAuthzDecisionResponseSigned">
      <Value>false</Value>
     </Attribute>
     <Attribute name="wantAssertionEncrypted">
      <Value>true</Value>
     </Attribute>
     <Attribute name="cotlist">
      <Value>fedlet-cot</Value>
     </Attribute>
    </XACMLAuthzDecisionQueryConfig>
   </EntityConfig>

5. Make a copy of sp-extended.xml called sp-extended-copy.xml and set hosted="0" in the root element of the copy.

   Use the copy, sp-extended-copy.xml, when importing the Fedlet configuration into AM. AM must register the Fedlet as a remote service provider.

6. In the AM console delete the original SP entity configuration for the Fedlet, and then import the updated metadata for the new configuration into AM on the IdP side.

7. Restart the Fedlet or the container in which it runs in order for the Fedlet to pick up the changes to the configuration properties and the metadata.

Follow these steps for a very simple demonstration of how to customize the Fedlet:

1. Backup fedletSampleApp.jsp.

   $ cd /path/to/tomcat/webapps/fedlet/
   $ cp fedletSampleApp.jsp fedletSampleApp.jsp.orig

2. Edit fedletSampleApp.jsp to reduce it to a single redirection to myapp.jsp. An implementation of the <html> element of the file follows below.

   <html>
   <head>
       <title>Fedlet Sample Application</title>
       <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   </head>
   
   <body>
   <%
       // BEGIN : following code is a must for Fedlet (SP) side application
       Map map;
       try {
           // invoke the Fedlet processing logic. this will do all the
           // necessary processing conforming to SAML v2.0 specifications,
           // such as XML signature validation, Audience and Recipient
           // validation etc.
           map = SPACSUtils.processResponseForFedlet(request, response,
               new PrintWriter(out, true));
           response.sendRedirect("myapp.jsp");
       } catch (SAML2Exception sme) {
           SAMLUtils.sendError(request, response,
               response.SC_INTERNAL_SERVER_ERROR, "failedToProcessSSOResponse",
               sme.getMessage());
           return;
       } catch (IOException ioe) {
           SAMLUtils.sendError(request, response,
               response.SC_INTERNAL_SERVER_ERROR, "failedToProcessSSOResponse",
               ioe.getMessage());
           return;
       } catch (SessionException se) {
           SAMLUtils.sendError(request, response,
               response.SC_INTERNAL_SERVER_ERROR, "failedToProcessSSOResponse",
               se.getMessage());
           return;
       } catch (ServletException se) {
           SAMLUtils.sendError(request, response,
               response.SC_BAD_REQUEST, "failedToProcessSSOResponse",
               se.getMessage());
           return;
       }
       // END : code is a must for Fedlet (SP) side application
   %>
   </body>
   </html>

3. Add a myapp.jsp page to the Fedlet, such as the following:

   <html>
   <head>
   <title>My Application</title>
   <meta http-equiv="Content-Type" content="text/html" />
   </head>
   
   <body>
   
   <h1>My Application</h1>
   
   <p>After you change the <code>fedletSampleApp.jsp</code>,
      all it does is redirect to this home page after
      successful login.</p>
   
   </body>
   </html>

4. Browse to the Fedlet URL, such as http://openam.example.com:8080/fedlet/, and try one of the login methods.

   After login you are redirected to myapp.jsp.

When the Fedlet is involved in only a single circle of trust with one IdP and the Fedlet as an SP, the only settings to change are cot-name and sun-fm-trusted-providers.

1. Save a copy of the template as fedlet.cot in the configuration folder, as in the following example.

   $ cp ~/Downloads/fedlet/conf/fedlet.cot-template ~/fedlet/fedlet.cot

2. Set cot-name to the name of the circle of trust.

3. Set sun-fm-trusted-providers to a comma-separated list of the entity names for the IdP and SP.

   For example, if the IdP is AM with entity ID https://openam.example.com:8443/openam and the SP is the Fedlet with entity ID https://sp.example.net:8443/fedlet, then set the property as follows.

   sun-fm-trusted-providers=https://openam.example.com:8443/openam,\
    https://sp.example.net:8443/fedlet
       

This procedure concerns deployments where the Fedlet participates as SP in multiple Circles of Trust, each involving their own IdP.

1. For each circle of trust, save a copy of the template in the configuration folder.

   The following example involves two Circles of Trust.

   $ cp ~/Downloads/fedlet/conf/fedlet.cot-template ~/fedlet/fedlet.cot
   $ cp ~/Downloads/fedlet/conf/fedlet.cot-template ~/fedlet/fedlet2.cot

2. Set up IdP XML files for each IdP as described in "Configuring the Identity Providers".

3. For each circle of trust, set up the cot file as described in "To Configure a circle of trust With a Single IdP".

4. In the extended SP XML file described in "Configuring the Identity Providers", set the Attribute element with name cotlist to include values for all Circles of Trust. The values are taken from the cot-name settings in the cot files.

   The following example works with two Circles of Trust, cot and cot2.

   <Attribute name="cotlist">
       <Value>cot</Value>
       <Value>cot2</Value>
   </Attribute>
   

   The same Attribute element is also available in extended IdP XML files for cases where an IdP belongs to multiple Circles of Trust.

When the circle of trust involves multiple IdPs, use the Fedlet in combination with the AM IdP Discovery service.

1. Set up the AM IdP Discovery service.

   For details see "Deploying the Identity Provider Discovery Service".

2. Configure the circle of trust as described in "To Configure a circle of trust With a Single IdP", but specifying multiple IdPs, including the IdP that provides the IdP Discovery service.

3. Set the sun-fm-saml2-readerservice-url and the sun-fm-saml2-writerservice-url properties as defined for the IdP Discovery service.