AEM Infrastructure Series: A Guide to SAML2 SSO on AEM 6.x

Why the Guide?
The Adobe documentation is a great reference for SAML2 setup. However, it lacks background information and certain implementation details and tips that can be critical to implementing SAML2 on AEM 6.x. Hopefully this guide will help!
https://docs.adobe.com/docs/en/aem/6-2/administer/security/saml-2-0-authenticationhandler.html
What is SAML2?
Security Assertion Markup Language 2.0 (SAML 2.0) is a version of the SAML standard for exchanging authentication and authorization data between security domains. SAML 2.0 is an XML-based protocol that uses security tokens containing assertions to pass information about a principal (usually an end user) between a SAML authority, named an Identity Provider, and a SAML consumer, named a Service Provider. SAML 2.0 enables web-based authentication and authorization scenarios including cross-domain single sign-on (SSO), which helps reduce the administrative overhead of distributing multiple authentication tokens to the user. (SAML 2.0, https://en.wikipedia.org/w/index.php?title=SAML_2.0&oldid=771005959 (last visited Apr. 18, 2017).)
Important Definitions

• Identity Provider (IdP): The site that is providing the SAML2 login, e.g. Oracle Access Manager, Salesforce, Azure, Okta. The Identify Provider in the back end is usually connected to a directory service like Active Directory or LDAP to authenticate the user and retrieve user attributes.
• Service Provider (SP): Adobe Experience Manager
• SAML2 Assertion: XML that is posted back to the SP containing the users’ login information, e.g. user id, attributes (configurable—e.g. first name, last name, email), and group membership (if applicable and configured).

AEM / SAML2 Flow Diagram
This diagram shows how AEM (the SP) interacts with an IdP. It’s important to note that the External SAML Login Procedure step, AEM is actually redirecting the users’ browser to the IdP. Once the user logs in at the IdP, the IdP redirects the user back to the SP along with the XML assertion (via a POST) that AEM reads and logs in the user.
SAML2 login is most commonly setup on the AEM Author server, but can also be setup on the Publish server where the customer is using a publically available IdP for external visitors.

LDAP Login
For comparison purposes only, below is a diagram that illustrates how LDAP login works in AEM. Configuration of LDAP is not required when using SAML2. With a SAML2 setup, all the users’ attributes are contained within the SAML2 XML assertion.

Process for Setting up SAML2 on AEM
Note: This setup may differ slightly between Identity Providers. If you feel like this list needs to be updated to meet your needs, please do so.
SAML2 setup is not complicated, but can be finicky, especially if this is your first setup. Pay special attention to the variable names; use cut-paste instead of typing the variables into AEM as even a <space> at the end of a variable may cause the SAML2 integration not to work.

Go Forward Recommendations
IF your pilot results indicate	THEN you might consider
80% or higher agree that Teams can be easily utilized alongside Skype for Business -and- Less than 80% user agreement that Teams can replace Skype for Business based on current use cases and scenarios -and- Satisfactory network health	Deploying Teams and Skype for Business side-by-side for some/all available scenarios. To facilitate the learning curve, we strongly encourage rolling out features over time, in lieu of an all-at-once approach. Learn more about the Upgrade journey and coexistence of Skype for Business and Teams. Download user readiness templates to facilitate communication with your end-users about their new side-by-side experience.
80% or higher user agreement that Teams can replace Skype for Business based on current use cases and scenarios -and- Satisfactory network health	Deploying Teams and Skype for Business side-by-side for all scenarios, encouraging users to lead with Teams where feasible. In addition, reach out to your account team or Microsoft Support to let them know your organization may be ready to go to Teams. Learn more about the Upgrade journey and coexistence of Skype for Business and Teams. Download user readiness templates to facilitate communication with your users about their new side-by-side experience.
Less than 80% agree that Teams can be easily utilized alongside Skype for Business -and- Less than 80% user agreement that Teams can replace Skype for Business based on current use cases and scenarios	Continuing with Skype for Business for communication (e.g. IM, Meetings, Calling) while utilizing the modern collaboration functionality (e.g., Teams/Channels) of Teams. Revisit a Teams pilot to verify communications functionality as new features are released per roadmap.

AEM Setup Example
Below is an example setup in the Adobe Granite SAML 2.0 Authentication Handler. Note this is from an older 5.6 installation; AEM 6.x includes additional options (see table below).

AEM / SAML Variables
Use the table below to configure the variables needed for a SAML2 setup. Not all variables are required for SAML2 to work properly. The required variables (or ones that are typically configured) are in bold.

Poll Results for What industry are you in?
Start Time: April 3, 2018 12:13:22 PM MDT
Total Responses: 222 of 428 (52%)
Results Summary
Answer	Total Number	Total %
Automotive	7	0.03
Energy and Utilities	14	0.06
Financial Services and Insurance	47	0.21
Healthcare and Life Sciences	60	0.27
Manufacturing	14	0.06
Retail	22	0.1
Other	58	0.26

Group Membership Options
If you choose to not synchronize groups from the IdP, but manage group membership directly in AEM (which is a common setup), you have a couple of options to manage the first-time login experience:
Option 1: Add the user manually in AEM via User Manager, and then assign permissions. (Use a fake, not guessable password.) /libs/granite/security/content/useradmin.html

Autocreate CRX Users = <unchecked>

Option 2: Allow the user to login, but with no permissions. Once the user is logged in, you’ll need to assign AEM groups. This can be a poor experience for the user as by default they will get an error message. You can probably create a read only group with basic permissions and auto assign them in the SAML setup.

Autocreate CRX Users = <checked>
Default Groups = <name of group to add>

Keep in mind with this approach is that any user that can login to the IdP, and can get to the AEM URL, can attempt to login. This could end up creating bogus accounts in AEM that might be tough to reconcile later.
Handling Logout Idiosyncrasies
AEM supports calling a logout URL (specified in the OSGi configuration), however, there is a small issue. When logging out, the browser fires a request for /favicon.ico before the IdP logout URL is posted. This causes the browser to redirect to the IdP and attempt to login again. To get around this, you’ll need to configure Apache Dispatcher in front the Author to “eat” the favicon.ico request. Add this to the virtual host entry:

# Eat favicon requests
RewriteRule ^/favicon\.ico$ - [F]

Extending the SAML2 Authentication Handler
There are cases where the IdP will not be capable of sending the attributes or groups that to meet the customer requirements. This will happen when 3rd party systems are involved to determine group membership (e.g. a commerce engine), custom implementations where there may have been previous design decisions, a simplified IdP where the necessary attributes are not stored in LDAP, or where there might be additional cleanup/actions needed after a user logs in.
Unfortunately, the AEM 6.x implementation removes the ability to extend the SAML2 framework and you’ll instead need to write a custom authentication handler. For more information see:
http://sling.apache.org/documentation/the-sling-engine/authentication/authentication-authenticationhandler.html
https://docs.adobe.com/docs/en/aem/6-2/develop/ref/javadoc/com/adobe/granite/auth/saml/util/package-summary.html