Customizing SAML2 plugins in AM/OpenAM

This book provides information on customizing the SAML2 plugins in AM/OpenAM. These plugins include account mappers, attribute mappers and adapters for both the IdP and SP.


How do I customize SAML2 plugins in AM/OpenAM (All versions)?

The purpose of this article is to provide information on customizing the default SAML2 plugins in AM/OpenAM. These plugins include account mappers, attribute mappers and adapters for both the IdP and SP.

Overview

If you want to customize the default account mappers, attribute mappers or adapters, you need to implement corresponding interfaces or extend an abstract class. Most of those interfaces / abstract classes have an implementation that we recommend to extend when you need a custom plugin. Extending an implementation allows you to delegate the bulk of the work to the default method implementation and only perform small changes according to business requirements.

The following table shows the classes to extend and the corresponding interfaces / abstract classes:

Plugin to customize Implementation class to extend Corresponding Interface/abstract class 
IDP Account Mapper DefaultIDPAccountMapper IDPAccountMapper
SP Account Mapper DefaultLibrarySPAccountMapper SPAccountMapper
IDP Attribute Mapper DefaultLibraryIDPAttributeMapper IDPAttributeMapper
SP Attribute Mapper DefaultSPAttributeMapper SPAttributeMapper
IDP Adapter DefaultIDPAdapter SAML2IdentityProviderAdapter
SP Adapter N/A SAML2ServiceProviderAdapter (Abstract class)

These classes are available from the openam-federation-library-<version>.jar file located in the WEB-INF/lib directory of the AM/OpenAM WAR file. You can find the classes in the following path within the jar file: com/sun/identity/saml2/plugins.

The interfaces are part of the Public API: API Javadoc › Package com.sun.identity.saml2.plugins.

Caution

Disclaimer for the following code, please review before implementing these changes. This code is just a sample; it does not include best practice for Java® code (such as error handling) and will need customizing to fit your use case. Customizing SAML2 plugins is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.  

Customizing a default plugin

See the following articles for specific details on customizing the different SAML2 plugins for different use cases:

The basic process is:

  1. Unpack the AM/OpenAM WAR file and extract the openam-federation-library-<version>.jar file.
  2. Create a new custom class that extends the default implementation class.
  3. Override the method you want to modify and insert your business logic.
  4. Repack the openam-federation-library-<version>.jar with your new custom class.
  5. Add your customization to the AM/OpenAM WAR file:
    • Replace the existing jar file in the WEB-INF/lib directory with your customized jar file.
    • Repack the AM/OpenAM WAR file and deploy as normal.
  6. Update the configuration for the relevant hosted entity provider by replacing the default class with your new custom class.
  7. Restart the web application container in which AM/OpenAM runs.
  8. Test your changes.

See Also

Customizing SAML2 plugins in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Hosted Identity Provider Configuration Properties › Assertion Processing

SAML v2.0 Guide › Hosted Service Provider Configuration Properties › Assertion Processing

SAML v2.0 Guide › Hosted Identity Provider Configuration Properties › Advanced Settings

API Javadoc › Package com.sun.identity.saml2.plugins

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade)

OPENAM-9143 (SAML IdP attribute mappers should work with profile attributes even when the user profile mode is set to dynamic)

OPENAM-4551 (document how to build and use a custom SAML IdP/SP Account Mapper)

OPENAM-4550 (document how to build and use a custom SAML IdP/SP Attribute Mapper)


Account Mappers


How do I customize the default SAML2 IdP account mapper in AM/OpenAM (All versions)?

The purpose of this article is to provide information on customizing the default SAML2 account mapper for the hosted IdP in AM/OpenAM. This is achieved by extending the DefaultIDPAccountMapper class that implements the IDPAccountMapper interface. A common customization is to modify the NameID value included in a SAML2 assertion by adding a static value as prefix and/or suffix.

Overview

If you want to customize the default account mapper, for example to customize the NameID value returned in the assertion, you can do this by implementing a custom IDPAccountMapper. This is achieved by extending the DefaultIDPAccountMapper class. This class is available from the openam-federation-library-<version>.jar file located in the WEB-INF/lib directory of the AM/OpenAM WAR file. You can find this class in the following path within the jar file: com/sun/identity/saml2/plugins.

Caution

Disclaimer for the following code, please review before implementing these changes. This code is just a sample; it does not include best practice for Java® code (such as error handling) and will need customizing to fit your use case. Customizing SAML2 plugins is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.  

Customizing the NameID value

The NameID value included in the SAML assertion is used by the remote SP to identify the end user via account mapping. See How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion? for further information.

There may be a need to modify the NameID value to comply with the business requirement of the remote SP. For example, the SP might want the NameID value to include their domain as a suffix; so if the NameID value is 12345, it would become 12345@sp.example.com when passed in the assertion. This change would only affect the one remote SP; the NameID value for other SPs would remain unchanged.

You can customize the NameID value as follows:

  1. Unpack the AM/OpenAM WAR file and extract the openam-federation-library-<version>.jar file.
  2. Create a new custom class that extends the DefaultIDPAccountMapper class, for example, CustomIDPAccountMapper. You should refer to Interface IDPAccountMapper for further information.
  3. Override the getNameID() method to achieve your desired customization. The resulting class would look similar to this:
    public class CustomIDPAccountMapper extends DefaultIDPAccountMapper{
    
        @Override
        public NameID getNameID(Object session, String hostEntityID, String remoteEntityID, String realm, String nameIDFormat) throws SAML2Exception {
    
            NameID myNameID= super.getNameID(session, hostEntityID, remoteEntityID, realm, nameIDFormat);
    
            if ("http://sp.example.com:38080/openam".equals(remoteEntityID)) {
                myNameID.setValue(myNameID.getValue() + "@sp.example.com");
            }
    
            return myNameID;
        }
    }
    
    
  4. Repack the openam-federation-library-<version>.jar with your new custom class.
  5. Add your customization to the AM/OpenAM WAR file:
    • Replace the existing jar file in the WEB-INF/lib directory with your customized jar file.
    • Repack the AM/OpenAM WAR file and deploy as normal.
  6. Update the configuration for the Hosted IdP with your new custom class:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers  > [Hosted IdP Name] > Assertion Processing > Account Mapper and replace the default class with your custom class.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Hosted IdP Name] > Assertion Processing > Account Mapper and replace the default class with your custom class.
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > [Hosted IdP Name] > Assertion Processing > Account Mapper and replace the default class with your custom class.
  7. Restart the web application container in which AM/OpenAM runs.
  8. Test your changes. 

The resulting assertion will show the modified NameID for the applicable SP. If you used the above snippet of code, this would mean you only see changes for http://sp.example.com, but not for other SPs.

See Also

How do I customize SAML2 plugins in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Assertion Processing

API Javadoc › Interface IDPAccountMapper

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4551 (document how to build and use a custom SAML IdP/SP Account Mapper)


How do I customize the default SAML2 SP account mapper in AM/OpenAM (All versions)?

The purpose of this article is to provide information on customizing the default SAML2 account mapper for the hosted SP in AM/OpenAM. This is achieved by extending the DefaultLibrarySPAccountMapper class that implements the SPAccountMapper interface.

Overview

If you want to customize the default account mapper, for example if you want to present a Terms and Conditions page to users who are federating for the first time, you can do this by implementing a custom SPAccountMapper. This is achieved by extending the DefaultLibrarySPAccountMapper class. This class is available from the openam-federation-library-<version>.jar file located in the WEB-INF/lib directory of the AM/OpenAM WAR file. You can find this class in the following path within the jar file: com/sun/identity/saml2/plugins.

Caution

Disclaimer for the following code, please review before implementing these changes. This code is just a sample; it does not include best practice for Java® code (such as error handling) and will need customizing to fit your use case. Customizing SAML2 plugins is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.  

Customizing the default SP account mapper

You can customize the default SP account mapper as follows:

  1. Unpack the AM/OpenAM WAR file and extract the openam-federation-library-<version>.jar file.
  2. Create a new custom class that extends the DefaultLibrarySPAccountMapper class, for example, CustomSPAccountMapper. You should refer to Interface SPAccountMapper for further information.
  3. Override the getIdentity() method to achieve your desired customization. The resulting class would look similar to this:
    public class CustomSPAccountMapper extends DefaultLibrarySPAccountMapper {
        /**
        * comments to be made here
         */
        @Override
        public String getIdentity (
            Assertion assertion,
            String hostEntityID,
            String realm){
        
            String myIdentity = super.getIdentity(assertion, hostEntityID, realm);
        
            if (myIdentity == null) {
                // write custom code. For example, present a Terms and Conditions page for first time federated users.
            }
    
            //write custom code here if needed.
             
            return myIdentity;
    
        }
    }
    
    
  4. Repack the openam-federation-library-<version>.jar with your new custom class.
  5. Add your customization to the AM/OpenAM WAR file:
    • Replace the existing jar file in the WEB-INF/lib directory with your customized jar file.
    • Repack the AM/OpenAM WAR file and deploy as normal.
  6. Update the configuration for the Hosted SP with your new custom class:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Hosted SP Name] > Assertion Processing > Account Mapper and replace the default class with your custom class.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Hosted SP Name] > Assertion Processing > Account Mapper and replace the default class with your custom class.
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > [Hosted SP Name] > Assertion Processing > Account Mapper and replace the default class with your custom class.
  7. Restart the web application container in which AM/OpenAM runs.
  8. Test your changes. 

See Also

How do I customize SAML2 plugins in AM/OpenAM (All versions)?

How does AM/OpenAM (All versions) use account mapping to identify the end user from a SAML Assertion?

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Assertion Processing

API Javadoc › Interface SPAccountMapper

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4551 (document how to build and use a custom SAML IdP/SP Account Mapper)


Attribute Mappers


How do I customize the default SAML2 IdP attribute mapper in AM/OpenAM (All versions)?

The purpose of this article is to provide information on customizing the default SAML2 attribute mapper for the hosted IdP in AM/OpenAM. This is achieved by extending the DefaultLibraryIDPAttributeMapper class that implements the IDPAttributeMapper interface.

Overview

If you want to customize the default attribute mapper, for example to map a LDAP attribute name and value to a custom format for a specific SP, you can do this by implementing a custom IDPAttributeMapper. This is achieved by extending the DefaultLibraryIDPAttributeMapper class. This class is available from the openam-federation-library-<version>.jar file located in the WEB-INF/lib directory of the AM/OpenAM WAR file. You can find this class in the following path within the jar file: com/sun/identity/saml2/plugins.

Caution

Disclaimer for the following code, please review before implementing these changes. This code is just a sample; it does not include best practice for Java® code (such as error handling) and will need customizing to fit your use case. Customizing SAML2 plugins is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.  

Customizing the default IdP attribute mapper

You can customize the default IdP attribute mapper as follows:

  1. Unpack the AM/OpenAM WAR file and extract the openam-federation-library-<version>.jar file.
  2. Create a new custom class that extends the DefaultLibraryIDPAttributeMapper class, for example, CustomIDPAttributeMapper. You should refer to Interface IDPAttributeMapper for further information.
  3. Override the getAttributes() method to achieve your desired customization. The resulting class would look similar to this:
    public class CustomIDPAttributeMapper extends DefaultLibraryIDPAttributeMapper {
        /**
        * comments to be made here
         */
        @Override
        public List getAttributes (
            Object session, 
            String hostEntityID, 
            String remoteEntityID, 
            String realm){
            
        List<Attribute> attributes = 
            super.getAttributes (session, hostEntityID, remoteEntityID, realm);
            
        if ("http://sp.example.com:38080/openam".equals(remoteEntityID)) {
                //modify attribute list here
            }  
            
        return attributes;
        }
    }
    
  4. Repack the openam-federation-library-<version>.jar with your new custom class.
  5. Add your customization to the AM/OpenAM WAR file:
    • Replace the existing jar file in the WEB-INF/lib directory with your customized jar file.
    • Repack the AM/OpenAM WAR file and deploy as normal.
  6. Update the configuration for the Hosted IdP with your new custom class:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Hosted IdP Name] > Assertion Processing > Attribute Mapper and replace the default class with your custom class.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Hosted IdP Name] > Assertion Processing > Attribute Mapper and replace the default class with your custom class.
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > [Hosted IdP Name] > Assertion Processing > Attribute Mapper and replace the default class with your custom class.
  7. Restart the web application container in which AM/OpenAM runs.
  8. Test your changes. 

See Also

How do I customize SAML2 plugins in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Assertion Processing

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11474 (Custom IDP Attribute mappers may cause failures after upgrade)

OPENAM-9143 (SAML IdP attribute mappers should work with profile attributes even when the user profile mode is set to dynamic)

OPENAM-4550 (document how to build and use a custom SAML IdP/SP Attribute Mapper)


How do I customize the default SAML2 SP attribute mapper in AM/OpenAM (All versions)?

The purpose of this article is to provide information on customizing the default SAML2 attribute mapper for the hosted SP in AM/OpenAM. This is achieved by extending the DefaultSPAttributeMapper class that implements the SPAttributeMapper interface.

Overview

If you want to customize the default attribute mapper, for example to map a LDAP attribute name and value to a custom format, or to add an extra attribute to the local session, you can do this by implementing a custom SPAttributeMapper. This is achieved by extending the DefaultSPAttributeMapper class. This class is available from the openam-federation-library-<version>.jar file located in the WEB-INF/lib directory of the AM/OpenAM WAR file. You can find this class in the following path within the jar file: com/sun/identity/saml2/plugins.

Caution

Disclaimer for the following code, please review before implementing these changes. This code is just a sample; it does not include best practice for Java® code (such as error handling) and will need customizing to fit your use case. Customizing SAML2 plugins is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.  

Customizing the default SP attribute mapper

You can customize the default SP attribute mapper as follows:

  1. Unpack the AM/OpenAM WAR file and extract the openam-federation-library-<version>.jar file.
  2. Create a new custom class that extends the DefaultSPAttributeMapper class, for example, CustomSPAttributeMapper. You should refer to Interface SPAttributeMapper for further information.
  3. Override the getAttributes() method to achieve your desired customization. The resulting class would look similar to this:
    public class CustomSPAttributeMapper extends DefaultSPAttributeMapper {
        /**
         * Constructor
         */
        public CustomSPAttributeMapper() {
        }
        /**
        * comments to be made here
         */
        @Override
        public Map<String,Set<String>> getAttributes (
            List<Attribute> attributes, 
            String userID, 
            String hostEntityID,  
            String remoteEntityID, 
            String realm){
    
         Map<String,Set<String>> attributes = 
            super.getAttributes (attributes, userID, hostEntityID, remoteEntityID, realm);
            
         //insert business logic here such as adding a new attribute
            
         return attributes;
        }
    }
    
    
  4. Repack the openam-federation-library-<version>.jar with your new custom class.
  5. Add your customization to the AM/OpenAM WAR file:
    • Replace the existing jar file in the WEB-INF/lib directory with your customized jar file.
    • Repack the AM/OpenAM WAR file and deploy as normal.
  6. Update the configuration for the Hosted SP with your new custom class:
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Hosted SP Name] > Assertion Processing > Attribute Mapper and replace the default class with your custom class.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers > [Hosted SP Name] > Assertion Processing > Attribute Mapper and replace the default class with your custom class.
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > Entity Providers > [Hosted SP Name] > Assertion Processing > Attribute Mapper and replace the default class with your custom class.
  7. Restart the web application container in which AM/OpenAM runs.
  8. Test your changes. 

See Also

How do I customize SAML2 plugins in AM/OpenAM (All versions)?

SAML Federation in AM/OpenAM

SAML v2.0 Guide › Assertion Processing

API Javadoc › Interface SPAttributeMapper

OpenAM SP SAML Attribute Mapper extension for updating profile attributes

Related Training

N/A

Related Issue Tracker IDs

OPENAM-4550 (document how to build and use a custom SAML IdP/SP Attribute Mapper)


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...