How To

How do I integrate ADFS with AM/OpenAM (All versions) using SAML2 federation?

Last updated Mar 8, 2019

The purpose of this article is to provide information on integrating Active Directory Federation Services (ADFS) with AM/OpenAM using SAML2 federation. This article assumes you already have a working AM/OpenAM and have installed ADFS on your Microsoft® Windows® server.


Overview

The use case in this article for integrating ADFS with AM/OpenAM using SAML2 federation, describes how to configure AM/OpenAM to act as the service provider (SP) and ADFS as the identity provider (IdP). ADFS does not provide strictly compliant SAML2 metadata, concepts such as "ClaimTypesOffered" are related to WS-Fed protocols and not SAML2, instructions include generating ADFS metadata with the appropriate SAML attributes for AM/OpenAM.

The expected access flow in a federated environment is as follows: 

  1. The user tries to access a resource on AM/OpenAM. Assuming they don't already have a valid session, AM/OpenAM starts the SAML flow by redirecting to the ADFS login page with a SAML AuthN request.
  2. The user enters their ADFS credentials, ADFS receives the request and issues an HTTP 401 Unauthorized response along with a WWW-Authenticate header that contains the information on how to authorize correctly for the target resource.
  3. The authentication response is returned; for NTLM/Kerberos this is an automated process via the SPNEGO protocol.
  4. ADFS receives the authentication response and if successful, it generates a SAML response.
  5. The client browser is redirected back to AM/OpenAM, which decodes the SAML response and issues a session token.
Note

This article is specific to implementing SSO Federation between AM/OpenAM and Microsoft ADFS only. Configuring ADFS or SSL is outside the scope of this article. Please refer to Microsoft (AD FS) Certificate Requirements for Federation Servers for prerequisites.

Assumptions

This article makes the following assumptions:

  • You already have a working AM/OpenAM environment installed and configured. 
  • The AM/OpenAM web container is configured to connect over SSL (HTTPS).
  • You are using DS/OpenDJ for your user store.
  • You have installed ADFS on your Microsoft Windows server. 
  • You have configured AM/OpenAM to trust the signing certificate by importing it into the keystore or truststore used for SAML. If AM/OpenAM does not trust this certificate, metadata imports will fail. See FAQ: SAML certificate management in AM/OpenAM (Q. Do I have to import a certificate into the keystore for XML signing or will AM/OpenAM use the certificate provided in the MetaData?) for further information. 

Configuring AM/OpenAM

Caution

Before you start integrating, you should ensure that either the same users exist in both the AM/OpenAM and ADFS user stores, or alternatively you have set the User Profile option to Dynamic; see Authentication and Single Sign-On Guide › User Profile for further information.

The following instructions guide you through using metadata template files; this is preferable to creating entity providers using the AM/OpenAM console as those options create basic providers that will need many changes. ADFS allows you to generate a template file as well; although the format is not compatible with AM/OpenAM and does not include the extended metadata files, you can remove the invalid parts from the standard metadata file and use the AM/OpenAM template for the extended metadata file.

This example process uses the following values:

  • The URL for the hosted SP is https://sp.example.com:8443/openam - this is also used as the name of the SP entity provider.
  • The IdP entity provider is called https://idp01.example.net/adfs/services/trust - this is the Federation Service identifier value that is specified in the ADFS Federation Service Properties window. 
  • The URL for the ADFS server is https://idp01.example.net.

You can configure AM/OpenAM for integration with ADFS as follows:

  1. Generate the hosted AM/OpenAM service provider template files using the ssoadm create-metadata-templ command, for example:
    $ ./ssoadm create-metadata-templ -u amadmin -f pwd.txt -y https://sp.example.com:8443/openam -c saml2 -m sp.xml -x sp-extend.xml -s /sp
    
  2. Edit the sp.xml file and ensure all the values match your AM/OpenAM environment. In particular, you should change the following values to true if you want Authn Requests and/or Assertions signed:
    <SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true"
    
  3. Edit the sp-extend.xml file and ensure all the values match your AM/OpenAM environment. In particular, you should add a UPN=uid mapping for NameID Mapping if you are using the 'unspecified' NameID format:
    <Attribute>
      	<Value>UPN=uid</Value>
    </Attribute>
    
    
  4. Generate the remote ADFS identity provider template files using the create-metadata-templ command, for example:
    $ ./ssoadm create-metadata-templ -u amadmin -f pwd.txt -y https://idp01.example.net/adfs/services/trust -c saml2 -m idp.xml -x idp-extend.xml -i /adfs
    
  5. Generate the ADFS metadata by navigating to the metadata link, for example, it would be the following URL in this example:
    https://idp01.example.net/federationmetadata/2007-06/Federationmetadata.xml
    Save this as idp.xml to replace the standard metadata file you generated in step 4. 
  6. Edit the idp.xml file and remove the following sections: 
    • ds: Signature
    • RoleDescriptor
    • SPSSODescriptor
    This leaves just the IDPSSODescriptor section. Be careful editing this file, as ADFS generates the XML all on one line.
  7. Edit the idp-extend.xml file and ensure all the values match your environment. In particular, you must change the hosted flag to false:
    xmlns:fm="urn:sun:fm:SAML:2.0:entityconfig" hosted="false"
    
  8. Log into the console for the SP and create a new circle of trust (COT):
    • AM 6 and later console: navigate to Realms > [Realm Name] > Applications > Federation, click Add Circle of Trust and enter a name for the new COT, for example, ADFS.
    • AM 5.x console: navigate to Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > New and enter a name for the new COT, for example, ADFS.
    • Pre-AM 5 console: navigate to Federation > Circle of Trust Configuration > New and enter a name for the new COT, for example, ADFS.
  9. Import both the standard and extended metadata files for both providers using the Import Entity button; your COT and entity providers setup should now look like this:

  1. Check both the entity provider details in the console are correct for your environment. In particular, you should check:
    • The appropriate Signing and Encryption options are selected for the SP (Assertion Content tab).
    • The NameID Mapping is set for the IdP (Services tab). For this example, it should be set to: https://idp01.example.net/adfs/ls/
  2. Export the SP metadata as described in How do I export and import SAML2 metadata in AM/OpenAM (All versions)? and give this to the ADFS administrator so they can import it into the IdP to “Add Relying Party Trust" to complete the setup . They will then need to create the Claim Rules to define what information can be sent to AM/OpenAM. Typically this will include the following rules:
    • Generic LDAP rule to map internal Active Directory LDAP attributes to claim types. You must map LDAP attribute: SAM-Account-Name to Outgoing Claim Type: sAmAcctName, but you can map other LDAP attributes as needed.
    • Custom rule to define the claim type and transform instruction rule so that ADFS knows how to format the SAML Name Identifier (NameID) and includes the SPNameQualifier attribute that AM/OpenAM expects to be present in the SAML assertion. Create a custom rule that uses the sAmAcctName claim created in the previous rule as the NameID and add the SPNameQualifer attribute (which should match the name of the SP as defined in ADFS). For example, your claim rule may look similar to this:
      • c:[Type == "sAmAcctName"]
         => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", 
        Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, 
        Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "https://idp01.example.net/adfs/services/trust", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "https://sp.example.com:8443/openam");
        This example rule defines this claim with a Type (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) that ADFS knows how to format as a NameID element in a SAML Assertion. The other Properties are emitted by ADFS as XML attributes to the NameID element, and includes the necessary spnamequalifier attribute. It also indicates that the 'unspecified' NameID format is being used, which you need to know for SP initiated SSO.
Note

All users' browsers need to be configured to trust the AM/OpenAM server. For example, you would add https://sp.example.com to the Local Internet sites option in Internet Explorer® or Microsoft Edge to allow this example AM/OpenAM server.

Testing federation

To test your federation setup, you can attempt to log in per the flow detailed in the Overview section at the start of this article: 

  1. Navigate to the AM/OpenAM protected resource.
  2. You should then be redirected to ADFS where you can log in with your ADFS credentials.
  3. If successful, you should then be logged into the AM/OpenAM protected resource automatically.

You can use a URL such as the following for SP initiated SSO, where the NameIDFormat matches the one specified in the claim rule above:

https://sp.example.com:8443/openam/saml2/jsp/spSSOInit.jsp?metaAlias=/sp&idpEntityID=https://idp01.example.net/adfs/services/trust&NameIDFormat=urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

Troubleshooting

It is worth exporting your metadata (standard and extended) to check if a configuration issue is contributing to your issues. You can export this as described in  How do I export and import SAML metadata in AM/OpenAM (All versions)? Additionally, you should capture a SAML trace while reproducing the issue. You should follow this process:

  • Start a SAML trace in your browser. There are free third-party tools you can use, for example, in Firefox®, you can use SAML Tracer.
  • Reproduce the issue using your browser.
  • Stop the SAML trace.

See Also

Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x

How do I automate the creation of a SAML2 entity provider in AM/OpenAM (All versions)?

How do I export and import SAML2 metadata in AM/OpenAM (All versions)?

FAQ: SAML federation in AM/OpenAM

FAQ: SAML certificate management in AM/OpenAM

SAML Federation in AM/OpenAM

SAML v2.0 Guide

Active Directory Federation Services

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7185 (When Uploading metadata generated from ADFS v3 IDP, the user should not have to edit the metadata )



Copyright and TrademarksCopyright © 2019 ForgeRock, all rights reserved.
Loading...