The use case in this article for integrating ADFS with AM using SAML2 federation, describes how to configure AM 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.
The expected access flow in a federated environment is as follows:
- The user tries to access a resource on AM. Assuming they don't already have a valid session, AM starts the SAML flow by redirecting to the ADFS login page with a SAML AuthN request.
- 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.
- The authentication response is returned; for NTLM/Kerberos this is an automated process via the SPNEGO protocol.
- ADFS receives the authentication response and if successful, it generates a SAML response.
- The client browser is redirected back to AM, which decodes the SAML response and issues a session token.
This article is specific to implementing SSO Federation between AM 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.
This article makes the following assumptions:
- You already have a working AM environment installed and configured.
- The AM web container is configured to connect over SSL (HTTPS).
- You are using DS for your user store.
- You have installed ADFS on your Microsoft Windows server.
- You have configured AM to trust the signing certificate by importing it into the keystore or truststore used for SAML. If AM does not trust this certificate, metadata imports will fail. See FAQ: SAML certificate management in AM 5.x and 6.x (Q. Do I have to import a certificate into the keystore for XML signing or will AM use the certificate provided in the MetaData?) for further information.
Before you start integrating, you should ensure that either the same users exist in both the AM and ADFS user stores, or alternatively you have set the User Profile option to Dynamic; see Core Authentication Attributes (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 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 and does not include the extended metadata files, you can remove the invalid parts from the standard metadata file and use the AM 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 for integration with ADFS as follows:
- Generate the hosted AM service provider template files using the ssoadm
create-metadata-templ command, for example:
- AM 7 and later: $ ./ssoadm create-metadata-templ -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -y https://sp.example.com:8443/openam -c saml2 -m sp.xml -x sp-extend.xml -s /sp
- Pre-AM 7: $ ./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
- Edit the sp.xml file and ensure all the values match your AM 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"
- Edit the sp-extend.xml file and ensure all the values match your AM 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>
- Generate the remote ADFS identity provider template files using the
create-metadata-templ command, for example:
- AM 7 and later: $ ./ssoadm create-metadata-templ -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -y https://idp01.example.net/adfs/services/trust -c saml2 -m idp.xml -x idp-extend.xml -i /adfs
- Pre-AM 7: $ ./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
- 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.
- Edit the idp.xml file and remove the following sections: This leaves just
the IDPSSODescriptor section. Be careful editing this file, as ADFS generates the XML all on
- ds: Signature
- 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"
- Create the Circle of Trust (COT) on the SP using ssoadm, for example, ADFS: $ ./ssoadm create-cot -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] replacing [adminID], [passwordfile], [realmname], [entityCOT] with appropriate values.
- Create the IdP and SP entity providers using ssoadm. You can use a command such as the following to create each provider: $ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile] replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values.
You can verify this has all been created correctly in the console; your COT and entity providers setup should now look like this:
- 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/
- Export the SP metadata as described in How do I export and import SAML2 metadata in AM (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. Typically this will include the following
- 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 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.
All users' browsers need to be configured to trust the AM server. For example, you would add https://sp.example.com to the Local Internet sites option in Microsoft Edge to allow this example AM server.
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:
- Navigate to the AM protected resource.
- You should then be redirected to ADFS where you can log in with your ADFS credentials.
- If successful, you should then be logged into the AM 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
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 (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.