The typical flow of an AEM Publish SAML integration is as follows:

1. User makes a request to AEM Publish the indicates authentication is required.
   • User requests a CUGs/ACL protected resource.
   • User requests a resource that is subject to an Authentication Requirement.
   • User follows a link to AEM’s login endpoint (i.e. /system/sling/login) that explicitly requests the login action.
2. AEM makes an AuthnRequest to the IDP, requesting IDP to start authentication process.
3. User authenticates to IDP.
   • User is prompted by the IDP for credentials.
   • User is already authenticated with the IDP and does not have to provide further credentials.
4. IDP generates a SAML assertion containing the user’s data, and signs it using the IDP’s private certificate.
5. IDP sends the SAML assertion via HTTP POST, by way of the user’s web browser, to AEM Publish.
6. AEM Publish receives the SAML assertion, and validates the SAML assertion’s integrity and authenticity using the IDP public certificate.
7. AEM Publish manages the AEM user record based on the SAML 2.0 OSGi configuration, and the contents of the SAML Assertion.
   • Creates user
   • Synchronizes user attributes
   • Updates AEM user group membership
8. AEM Publish sets the AEM login-token cookie on the HTTP response, which is used to authenticate subsequent requests to AEM Publish.
9. AEM Publish redirects user to URL on AEM Publish as specified by the saml_request_path cookie.

So I want to quickly show you how to set up SAML authentication for AEM’s cloud service. And for this I’ll be using a free Okta account as a IDP And my AEM as a cloud service, dev environment’s publish service will be the service provider or SP. First step here is to set up the IDP itself. And I’m going to just run through this quickly. I’m not going to spend too much time on the Okta side since all IDPs are a little bit different. But I hope this should give you a good sense of what you might have to do in your IDP. So I’m going to create a new integration app. I’m going to make sure to pick SAML 2.0, as that’s the version of SAML that AEM as a cloud service supports.

Go ahead and name my app.

And the first thing I’ll need to do is provide a single sign in URL. And this is where the SAML assertion is posted back to in AEM. So the first piece of this will be the AEM Publish origin and I can find this in cloud manager, and go to my environment, get these details, and copy the Publish service link. And note that if you are doing this on production and have a custom domain, you would want to make sure that your custom domain that your users are accessing is here instead. The next piece that we’ll go into further detail when we set up the SAML authentication AEM, is the path that we’ll be posting to. So typically you’ll want to post under the Sites path, whose authentication will be managed by the IDP. So in this case we’ll be managing authentication for the WKND Site, which reside under “/content_wknd.” And then we’ll want to make sure that we add a suffix of “SAML_login.” And this is just a special path segment that tells the SAML authentication handler in AEM that it needs to be invoked. And we’ll go into the details of this a little bit later on, as I mentioned before. Next up is the audience URI, or service provider entity ID. And this is just a unique ID that tells the IDP what service provider should be accessing this specific IDP application or configuration. Typically a single AEM as a cloud service environment is mapped to an IDP integration or application. So it’s often most clear to simply use the origin of the AEM Publish service. We can leave the relay state blank, the name ID format. I would like to change this as transient, simply because this is the default expected format in AEM and this removes the need for us to configure that later.

And lastly, we can map some user attributes from our IDP into the SAML assertion, which will allow us to synchronize those into AEM. So over here we can see we have a couple of values available to us from Okta. So let’s map the first name, and we can call this anything we want, but let’s just keep it simple. Call it “first name.” and we’ll do the same for “last name.” And let’s throw one in named “UID” and map it to the email address in Okta. We’ll skip the group attribute statements for now and we can finish up our configuration here. So hit ‘Next.’ Since this is a free account I’m just going to click through this, and finish.

And the last thing I want to do, since this is a a brand new application in Okta is make sure that we assign users to it so we can actually log in using those users. So I’ll just go up to assignments and just assign a few of the sample accounts that I have set up in Okta.

All right, we should be set now. Now let’s head over to AEM and continue the setup. Do note that we’ll have to come back here to our IDP to collect some information and data that we’ll use to configure the SAML authentication piece in AEM itself.

With the IDP configured, our first step is to configure AEM’s Global Trust Store to include the IDP’s` public certificate. So for this, we’ll head over to the AEM environments Author service. And note that we’re initially configuring this on the Author service, even though we will ultimately push this to AEM Publish as that is the service tier that will interact with the IDP. So we need to make sure we’re an AEM administrator, head over to ‘Tools’, ‘Security’, and ‘Trust store.’ So you may already have an existing Global Trust store, if you do open it using its password. If not, we can create a new trust store, provide a password and make sure you record this in a safe place as this is going to be required to edit it in the future. So if you need to add or update a certificate you would need this password.

Once we’re here, under the ‘Add Certificate From CER file’ section, we can upload the public certificate provided to us by our IDP. So for this, we need to go back to our IDP and download it.

So back in the IDP I can grab the certificate, download it to my local computer, head back to AEM, and upload the public certificate from the IDP.

We don’t have to map it to a user, so leave that blank, and hit ‘Submit.’ We can see that the certificate was successfully loaded, and we can see the certificate details up above. And what in them that we’ll have to make note of is the certificate alias as we will need to reference this in our SAML configuration.

With the IDP as public certificate installed into AEM Authors Global Trust Store, we need to activate or replicate the Global Trust Store to AEM Publish. So there are a couple ways to do this, but I’d like to use the package approach. So let’s go ahead and do that. We head back to ‘Tools’, ‘Deployment’, ‘Packages.’ I’m going to create a new package. I’ll just call this “Global Trust Store,” however you can name this anything you want. I’ll give it a version.

I’ll give it a group.

And create the empty package.

Now let’s add the Global Trust Store. So for this, we’ll hit 'Edit, ‘Filters,’ ‘Add a filter’ and we will add the trust store folder location which is at ETC Trust Store.

And save.

Now we can build the package which will add the trust store to the actual package file.

Go to ‘More,’ and replicate. And this will push the package out to the AEM Publish and preview services.

Next, we’ll need an AEM developer tag configuration files to our AEM project, and then deploy them to AEM as a cloud service via cloud manager. The first set of configurations are OSGI configurations. So we’ll add those to the ‘ui.config’ project. We’ll drill down ‘src/main/content’, ‘jcr_root’, ‘apps,’ our project name, “osgiconfig.” And we’ll be putting ours in the config.publish folder, Since AEM’s SAML integration is only supported on the Publish service tier.

Note that we’ll also be using OSGI configuration variables to abstract out some of the values so we don’t need to recreate the same configurations and duplicate them across the more specific run world folders such as publish.dev, publish.prod, and publish.stage.

All right, so the first OSGI configuration we’ll create is for the SAML authentication handler. So let’s go ahead and create a new file and we’ll use the OSGI factory configuration PID, to name this file.

Note that this is a factory configuration so you can have multiple configurations for the SAML authentication handler deployed to AEM. And the unique identifier for each configuration is denoted after the tilde here. So I’m going to go ahead and change this from SAML to Okta, just to be a little bit more clear as to what this SAML authentication handler is configuring. But you can name this ID segment after the tilde anything you want I’ll go ahead and paste in some of the base properties that we’ll need to configure, and let’s go through these and fill them out. So the first is the paths that this authentication handler will be responsible for authenticating requests for. So keep in mind that this does not necessarily mean these paths require authentication. It simply means that if there are protected resources beneath these paths, that this authentication handler configuration will be invoked to try to authenticate the users. Since we’re adding this for the WKND website and we know that the WKND website resides under “/content/wknd,” let’s go ahead and add that as our first path. We can add other related paths. So for instance we could add “/content/dam/wknd” to make sure that if anyone directly requests an asset, that they’re also sent through this authentication flow. And before we move on I want to tie this back to something we configured in IDP. And you’ll remember that we specified the single sign-on URL. And we specified this as the Publish origin “/content/wknd/SAML” login. So the reason that we picked “/content/wknd” as part of the single sign on URL is because I knew that we would be configuring “/content/wknd” as one of the paths that the SAML authentication handler would be responsible for managing authentication for. So in order to ensure that this authentication handler was invoked, I set the sign in URL to be “/content/wknd,” and then that well known suffix “/saml_login.” Next up is the IDP cert alias and this is the cert alias in AEM’s Global Trust Store that contains the public cert provided by the IDP. So we can get this by going back to AEM, ‘Tools,’ ‘Security,’ opening the trust store, and simply copying the cert alias. The IDP identifier is optional, however most IDPs provide this and it’s a nice way to tie back any AEM user creation to specific IDPs. So let’s go ahead and add this. Head back to the IDP.

And in Okta we can view the setup instructions, and we have the identity provider issuer which acts essentially as a unique ID for this particular SAML integration. So we can use this.

Next is the IDP URL, and this is where AEM Publish will send the Author requests that will initiate the SAML authentication with the IDP. And this is provided right here in the IDP. So we can take that, paste it in. Next step is the service provider entity ID and this is what we configured in the audience field when we set up our IDP. So we can go back to the general tab, locate audience restriction, and we can simply copy this value.

We’ll keep using encryption set to false. Setting use encryption to true requires AEM to provide a public and private key. The public key will be installed on the IDP, and the private key installed on AEM. And this facilitates the signing of the Author request, as well as the encryption of the SAML assertion. Next step is the user ID attribute. This is the SAML attribute that contains the value that will be used as the AEM User ID. And if we look on our IDP, you can see that we have mapped UID attribute to the user email. So if we wanted to use the user’s email as it exists in Okta we could provide UID in this field, or whatever the SAML assertions attribute that contains that as named. If we leave this blank, it will by default use the SAML assertion’s subject name. And in the case of my IDP configuration, that happens to be the email address. So I’m going to leave this blank and it’ll actually just use the subject name.

Next step is create user. You almost always want ‘create user set to true,’ as this will automatically create any non-existent AEM users in AEM upon successful authentication, to the IDP. Next step is the intermediate path. And this is the intermediate path in AEM under /homeusers. Any users created during the authentication SAML flow will reside under it. So for instance, we could set this to “wknd/okta” if we wanted to clearly delineate which users in the JCR were created using the WKND Okta SAML integration.

Next up is the synchronized attributes, and this allows us to synchronize attributes from the IDP and persist them to the AEM user’s profile. So let’s go ahead and do this for some of the attributes that we set up in our IDP. So we have those listed under the attribute statements here. And the format is the SAML assertion attribute name. So in this case it’s “first name.” And don’t get this confused with what the SAML assertion attribute is mapped to in the IDP, which in this case is “user.first name.” And then we set equals to and this is the relative property path from the user’s node that we’ll store this value in. So typically these are stored under profile and then a property. So given name is the native property in AEM that stores the first name. Let’s do the same for the last name.

And lastly, let’s save the UID, which we’ve configured to contain the user’s email, and save it to the AEM Profiles email property. All right, almost done. The last two fields have to do with managing membership of the user in AEM after they logged in. “Add group membership” simply means that the user’s group membership will be managed during authentication, so they’ll be added or removed to any of the necessary groups as defined in the configuration. So we’ll leave this to true. And then we can set default groups that this user will be added to. So in this case, let’s just add them to our WKND members AEM user group, so that once they authenticate, they’re able to access the members only area. Note that this integration can also dynamically assign memberships based on group names sent down from the IDP via the SAML assertion. The last thing I want to do before we tackle the other OSGI configurations, is to abstract some of these values out using OSGI environment variables.

So what we can do is use a specific syntax, and so we’ll add a dollar sign, square bracket, ENV, colon, and now we can make up a variable name, though of course you want to keep the semantics. So I’m going to name this “SAML_IDP_Cert_Alias,” since this is for the SAML integration and it defines the cert alias for the IDPs public cert. And then I can put a semicolon, and I can even say “default equals” and then provide the value I pasted in as a default value. And then I want to make sure that I finish this up with another square bracket. So essentially what I’ve done here is I’ve abstracted the value that will be injected into this property using an OSGI environment variable named “SAML_IDP_CERT_ALIAS” that I can manage in cloud managers UI.

Let’s skip ahead to where I’ve done this for some of the other OSGI properties.

The nice thing about using OSGI environment variables is it allows us to create a single OSGI configuration that we can use across multiple service types or environment types. So for example, it’s likely that we would use a development IDP application on our development environment, and a production IDP application for our stage and production environments. We can update any of these OSGI configuration values in cloud managers UI without a new code deployment. We have two more OSGI configurations to go, so let’s keep moving. The second OSGI configuration is the sling refer filter OSG config. So I’ll open mine up, and this is located under our config.publish folder. This OSG configuration was autogenerated when I created this project using the AEM Maven project archetype. If you don’t have this OSGI configuration you can certainly add your own. So there are two properties we want to focus on in this OSGI configuration, and that’s the allowed hosts. So for this, we’ll put in the domain or host that the IDP runs on, and we can get this from the IDP. So we’ll head over and grab the domain name that the IDP runs on and will be accessed from, and place it in here. I recommend not providing the scheme, so the HDP or HDPS prefix. If you do provide the scheme, you’ll have to provide a port as well as part of the URL. So this would be 443 for HTTPs, or you could essentially whitelist it and put a zero.

But if we leave the scheme off and simply put the domain name, both HTTP and HTTPS referring requests from this domain will be allowed. I’ll go ahead and abstract this out as a OSGI environment variable as well, since this might be something we would want to change based on our environment types.

And we’ll just use this value as the default. Note that you could also use the “allow host regular expression” property above, if you know that you’ll be using a variety of IDP URLs across your environments that match a specific pattern. But we’ll keep ours simple and use the exact domain. The last thing we need to do is make sure that the filter.methods includes the post method. And this is because the IDP will orchestrate an HTTP post back to AEM containing the SAML assertion, and we want to make sure that that request comes through. Okay, the last OSGI configuration we need is a cross origin resource sharing config. So just like before, we’ll make a new OSGI config under config.publish, and I’ll paste in the factory PID for CORS.

And I’ll also paste in the properties that we’ll need to fill out. And do note that since CORS is a factory configuration you can have multiple CORS policies defined for an AEM environment. So for example, as you can see here, I’ve just created a new SAML CORS policy, but we’ve already had a WKND GraphQL policy, as well. But that’s fine. I typically like to break out the CORS policies for whatever use case that they’re supporting, and that’s why we have a brand new one for SAML.

Back to the OSGI configuration, we have to fill out these properties here. So ‘allowed origin’ will be similar to the refer filter where we need to put in the IDP’s origin. In this case we’ll want to provide the HTTPS prefix as well. So let’s go ahead and pop that in. And just like before, let’s abstract this out into an OSGI configuration environment variable in case we need to change it per environment later.

Next up are the ‘allowed paths.’ These are the AEM repository paths that will support cross origin resource sharing requests from the allowed origin defined here. So in our case, our IDP will be making an HTTP post to “/content/wknd/saml_login” So we could put this path here. The other thing we could do is make this a little bit more flexible and replace this with a regular expression and do “.*/saml_login,” And this will allow our IDP to make cross origin resource sharing requests to any path in AEM that ends with “/saml_login.” So let’s keep this, since it’s just a little bit more flexible. Lastly, we have ‘supported methods,’ and just like the refer filter we need to make sure that post is enumerated here since the IDP will be orchestrating that HTTP post back to AEM with our SAML assertion. All right, so I think that should do it for our OSGI configs. The last thing we need to do is set up our dispatcher. So let’s head over and do that. I’ll head over to our dispatcher project ‘src,’ ‘conf_dispatcherd,’ ‘filters,’ and I’ll open the ‘filters.any’ file.

And we can go ahead and make a new allow filter in our ‘filters.any’ file The method is post, since the IDP is orchestrating that HTTP post containing the SAML assertion. And we can set the URL to be anything that ends with “saml_login,” just like our CORS OSGI configuration.

I’ll add a quick comment so we don’t forget what this is for, and we should be about ready to go. The last thing I just want to call out is if you’re doing any sort of rewriting at the Apache web server level, just make sure that any of these HTTP posts to the “/content/wknd/saml_login” endpoint are not being mangled. And we can double check this by going to ‘conf,’ ‘rewrites,’ ‘rewrite_rules.’ And as we can see here our SAML login will be caught by this rule. Since we’re posting to “/content/wknd/saml_login,” we’re fine. If we were running our SAML login off the root of AEM and we were essentially a single tenant situation, this role here would prevent any sort of mangling of that URL. So it looks like we’re good to go.

The last thing we need to do is commit our changes to GIT, and push it up to cloud manager and deploy it to our AEM as a cloud service environment.

All right, with our updated configuration, push up to cloud manager GIT. Let’s go ahead and deploy it to our dev environment.

So we’ll go down, find our dev deployment pipeline, which is hooked up to our development branch, which we pushed our configuration changes to. We’ll simply run this.

Now that our SAML configuration is deployed to our AEM as a cloud service environment, let’s try it out on our AEM Publish service. So I have the weekend site up, and I’m going to navigate to the magazine page. And I’ve added a new button to the ‘Members Only’ section that prompts us to sign in to access our members only articles.

Clicking this button will initiate the authentication with the IDP, which will create a user for me and authenticate me to AEM Publish, and then take me to the ‘Members Only’ page. So let’s try this out. I’ll click the button. We’re taken to our IDP, which is Okta. I’ll go ahead and sign into Okta.

And upon successful authentication, I’m taken back to our WKND site running on AEM Publish, and I’m logged in. You can see that I’m on the protected WKND members page so I can navigate into the various protected members only articles. And you can also see up here at the top, that as part of my authentication, I was able to sync in my first name and last name from the IDP to my AEM profile, so I can now display these attributes as part of the web experience. I know this video was a little long, but I hope this will help you set up SAML authentication with AEM Publish. -

1. User authenticates to IDP.
2. IDP generates a SAML assertion containing the user’s data.
3. IDP signs the SAML assertion using the IDP’s private certificate.
4. IDP initiates a client-side HTTP POST to AEM Publish’s SAML endpoint (.../saml_login) that includes the signed SAML assertion.
5. AEM Publish receives the HTTP POST containing the signed SAML assertion, can validate the signature using the IDP public certificate.

The AuthnRequest (the request to the IDP from AEM Publish that initiates the login process) can be signed by AEM Publish. To do this, AEM Publish signs the AuthnRequest using the private key, that the IDP then validates the signature using the public key. This guarantees to the IDP that AuthnRequest was initiated, and requested by AEM Publish, and not a malicious third party.

1. User makes an HTTP request to AEM Publish that results in an SAML authentication request to the IDP.
2. AEM Publish generates the SAML request to send to the IDP.
3. AEM Publish signs the SAML request using AEM’s private key.
4. AEM Publish initiates the AuthnRequest, an HTTP client-side redirect to the IDP that contains the signed SAML request.
5. IDP receives the AuthnRequest, and validates the signature using AEM’s public key, guaranteeing AEM Publish initiated the AuthnRequest.
6. AEM Publish then validates the decrypted SAML assertion’s integrity and authenticity using the IDP public certificate.

All HTTP communication between IDP and AEM Publish should be over HTTPS, and thus secure by default. However, as required, SAML assertions can be encrypted in the event extra confidentiality is required on top of that provided by HTTPS. To do this, the IDP encrypts the SAML Assertion data using the private key, and AEM Publish decrypts the SAML assertion using the private key.

1. User authenticates to IDP.
2. IDP generates a SAML assertion containing the user’s data, and signs it using the IDP’s private certificate.
3. IDP then encrypts the SAML assertion with AEM’s public key, which requires the AEM private key to decrypt.
4. The encrypted SAML assertion is sent, by way of the user’s web browser to AEM Publish.
5. AEM Publish receives the SAML assertion, and decrypts it using AEM’s private key.
6. IDP prompts user to authenticate.

Adobe Granite SAML 2.0 Authentication Handler OSGi configuration

AEM user attributes

AEM uses the following user attributes, which can be populated via the synchronizeAttributes property in the Adobe Granite SAML 2.0 Authentication Handler OSGi configuration. Any IDP attributes can be synchronized to any AEM user property, however mapping to AEM use attribute properties (listed below) allows AEM to naturally use them.

1. Open /ui.config/src/main/content/jcr_root/wknd-examples/osgiconfig/config.publish/com.adobe.granite.auth.saml.SamlAuthenticationHandler~saml.cfg.json in your IDE.

2. Add the three properties useEncryption, spPrivateKeyAlias, and keyStorePassword as shown below.

   {
   "path": [ "/content/wknd", "/content/dam/wknd" ],
   "idpCertAlias": "$[env:SAML_IDP_CERT_ALIAS;default=certalias___1234567890]",
   "idpIdentifier": "$[env:SAML_IDP_ID;default=http://www.okta.com/abcdef1235678]",
   "idpUrl": "$[env:SAML_IDP_URL;default=https://dev-5511372.okta.com/app/dev-123567890_aemasacloudservice_1/abcdef1235678/sso/saml]",
   "serviceProviderEntityId": "$[env:SAML_AEM_ID;default=https://publish-p123-e456.adobeaemcloud.com]",
   "useEncryption": true,
   "spPrivateKeyAlias": "$[env:SAML_AEM_KEYSTORE_ALIAS;default=aem-saml-encryption]",
   "keyStorePassword": "$[secret:SAML_AEM_KEYSTORE_PASSWORD]",
   "createUser": true,
   "userIntermediatePath": "wknd/idp"
   "synchronizeAttributes":[
       "firstName=profile/givenName"
   ],
   "addGroupMemberships": true,
   "defaultGroups": [
       "wknd-users"
   ]
   }
   

3. The three OSGi configuration properties required for encryption are:

• useEncryption set to true
• spPrivateKeyAlias contains the keystore entry alias for the private key used by the SAML integration.
• keyStorePassword contains an OSGi secret configuration variable containing the authentication-service user keystore’s password.