SAML 2.0 authentication

Transcript

So I want to quickly show you how to set up SAML authentication for AIM as a cloud service. And for this, I’ll be using a free Okta account as IDP. And my AIM as a cloud service dev environments publish service will be the service provider or SP. First up 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 AIM 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 AIM. So the first piece of this will be the AIM publish origin. And I can find this in cloud manager. And go to my environment, it gets 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 will go into further detail when we set up the SAML authentication AIM is the path that we’ll be posting to. So typically, you’ll want to post under the site’s path whose authentication will be managed by the IDP. So in this case, we’ll be managing authentication for the weekend sites, which reside under slash content weekend. And then we’ll want to make sure that we add a suffix of SAML underscore login. And this is just a special path segment that tells the SAML authentication handler in AIM 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 AIM 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 AIM publish service, we can leave the relay state blank, the name ID format, I like to change this as transient simply because this is the default expected format in AIM. 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 AIM. 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 first name, we’ll do the same for last name. And let’s throw one in name 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 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 Surfile 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 one item 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’s 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. Head back to tools, deployment, packages. I’m going to create a new package. I’ll just call this global trust store. However, you could 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 that 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 to add 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 source main content, JCI root, apps, our project name, OSGI config, 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 mode 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 weekend website, and we know that the weekend website resides under content weekend, 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 weekend 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 slash content slash weekend slash SAML login. So the reason that we picked slash content slash weekend as part of the single sign-on URL is because I knew that we would be configuring slash content slash weekend 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 slash content slash weekend, and then that well-known suffix slash SAML logging. 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, and we can 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 up 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 is named. If we leave this blank, it will by default use the SAML assertions 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 up is create user. You’ll most always want create user set to true, as this will automatically create any non-existent AEM users in a user upon successful authentication to the IDP. Next up is the intermediate path, and this is the intermediate path in AEM under slash home users. Any users created during the authentication SAML flow will reside under. So for instance, we could set this to weekend Okta if we wanted to clearly delineate which users in the JCR were created using the weekend Okta SAML integration. Next up is the synchronize 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 dot first name. And then we set equals to, and this is the relative property path from the user’s node that will 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 AEM profile’s 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 is logged in. So let’s do that. So let’s 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 weekend members AEM user group, so that once they authenticate, they’re able to access the members only area. And then we 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, and now we can make up a variable name, though, of course, you want to keep the semantic. 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 IDP 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 Referrer Filter OSGI config. So I’ll open mine up and this is located under our config.publish folder. This OSGI configuration was auto-generated when I created this project using the AM 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 HTTP or HTTPS prefix. If you do provide the scheme, you will 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 a 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 our cores. And I’ll also paste in the properties that we’ll need to fill out. And do note that since cores is a factory configuration, you can have multiple course policies defined for an AM environment. So for example, as you can see here, I’ve just created a new SAML course policy. But we’ve already had a weekend GraphQL policy as well. But that’s fine. I typically like to break out the course 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 AM 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 weekend 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 it dot star SAML login. And this will allow our IDP to make cross origin resource sharing requests to any path in AM that ends with slash 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 AM 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, source, comp dispatcher D, filters, and I’ll open the filters dot any file. And we can go ahead and make a new allow filter in our filters dot 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 cores 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 weekend 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 slash content slash weekend slash SAML login, we’re fine. If we were running our SAML login off the root of am and we were essentially a single tenant situation. This rule 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 get and push it up to cloud manager and deploy it to our AM as a cloud service environment. All right, with our updated configuration push up to cloud manager get let’s go ahead and deploy it to our dev environment. So go down find our dev deployment pipeline, which is hooked up to our development branch, which we put our configuration changes to, we’ll simply run this. Now that our SAML configuration is deployed to our AM as a cloud service environment, let’s try it out on our AM 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 AM publish and then take me to the members only page. So let’s try this out. I’ll click the button. We’re taking to our IDP, which is Okta. I’ll go ahead and sign into Okta. And upon successful authentication, I’m taken back to our weekend site running on AM publish and I’m logged in. You can see that I’m on the protected weekend 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 AM 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 AM publish.