 All right. Hello and welcome to Federation with Key Cloak and free IPA. My name is Martin I'm a tech writer at Red Hat where I work on OpenStack documentation on neutron and keystone I'm joined today by John and Rodrigo. John tell us a bit about yourself My name is John Dennis. I also work at Red Hat. I have a background in authentication OpenStack Keystone and was a member of the IPA project for a number of years And Rodrigo. I'm Rodrigo. I work with these guys at Red Hat and I've been doing all kinds of stuff in Keystone for the last three years and Federation is one of them. All right. So I'll start us off by covering the agenda of this presentation. We're first going to describe the components involved. Those are the dashboard, Keystone, free IPA and Key Cloak. And then we're going to talk about how these components all work together to give us a federated design. And then we're going to go into the details of the manual configuration steps for each of these involved components. We're not going to describe actually every single step because that would be more than time we have available. But we are going to pull out certain chosen highlights that we need to emphasize that would require extra thought or explanation. And then Rodrigo will give us a demonstration of Federation from the user's perspective. And then also John will share with us some troubleshooting tips to give you an idea of what's going on under the hood. All right. So first thing, I need to set an important support note about this. So this presentation describes the manual configuration steps for Federation. So in other words, it's not dependent on you running a certain flavor of OpenStack using a certain distribution or installer. But even if you are using a certain automation tool, there's still a lot of value in understanding the manual configuration steps, especially if you need to do troubleshooting or such. And also in support of this presentation, we also put out a guide that covers all the manual steps in great detail. So you might even be able to think of this presentation as a supplement to that guide that's highlighted there under the manual steps bullet point. So these are the same steps that I follow when I build my own test lab. That's running free IPA and Key Cloak and Audio Ocarta, all of CentOS 7. I also need to mention that these manual steps are not in fact supported by Red Hat, but there is a supported guide available for director customers that are interested. That's linked there under the director-based steps bullet point. And John's also created a triple O based guide. That's also linked there. So I'm going to give a short overview of Horizon and highlight the features that are relevant to Federation. So you're already familiar with Horizon. It's the browser-based user interface for OpenStack, and it allows users to log in and interact with their projects. And in the screenshot there, I'm showing you a Federated Horizon page. And you can see in the drop-down list there, that's where users can choose to log in with their free IPA credentials or with their Key Cloak-based account. Well, their Key Cloak being their free IPA credentials. And so for Federation purposes, when a user arrives at this page and selects the Key Cloak option, that's where they'll then get forwarded through to the Key Cloak login page where they can then type in their free IPA username and password. Let's see. So next here is Rodrigo with an overview of Keystone. Yes, so thanks, Martin. And Keystone is the OpenStack identity service. It's responsible for authentication and authorization of OpenStack Clouds. And the way Keystone does authorization is by role assignments. That is how Keystone models are back in the back end. And that's exactly the way that Keystone tries to link a user that is Federated to come into the Cloud into a project in the OpenStack side. Keystone also works as a service provider in the Federation workflow. That means that Keystone is the component that provides the resources that our users are trying to access. And a requirement for the Federated workflow, the Federated feature, is that all the endpoints must be created so you need to have SSL enabled in your environment. Cool. Thanks, Rodrigo. And now, John, what can you tell us about FreeIPA? FreeIPA is an independent project from OpenStack. It's an open source project. It's an integrated user and host management system. It's primary features that are relevant to you are the fact that it provides a certificate authority for issuing certificates, host-based access control. It's backed by an LDAP server, which we're going to be using for user federation through the IDP. It includes Kerberos support, a KDC, as well as a user-friendly dashboard for managing this within your organization. It's a fundamental tool for enterprise and academic deployments where you can manage a large set of features through one integrated product. Cool. Thank you. All right, so I'll now give us an overview of Keycloak. Keycloak is a more recent project. It's the upstream of Red Hat Single Sign-On. In Federation language, it serves as the identity provider, the IDP. So then as the identity provider, it validates user credentials and then asserts back to Keystone that the credentials are in fact valid. So it's then the middleware component that sits between your OpenStack deployment and FreeIPA, thereby allowing you to use SAML2 to let them communicate with each other. It also works with other identity sources, such as Active Directory. So I guess in a way, you can think of Keycloak as your identity aggregator for all these various sources of identity within your organization. So you'd use the web-based console to configure Keycloak to query account information from FreeIPA. So as a result, it's actually Keycloak that's presenting the FreeIPA user information back through to OpenStack. Let's see what else. Oh yeah, there is also a Keycloak client available to automate some of the configuration, and I'll describe some more of that later. And now in the screenshot here, you can see the login screen that the user gets forwarded to from Horizon. So this is where they'll be entering their FreeIPA credentials before they then get forwarded back through to OpenStack. All right, so then now to tie this all together into that thing called Federation. Here's Rodrigo. Thanks, Martin. So as we discussed before, we have on the left side of this picture, the OpenStack dashboard, which is Horizon and Keystone. And in the right side, we have Keycloak and FreeIPA. And they are the two main components here in the Federation workflow. And you can see in the middle that we have Mellon, which is the SEMO speaker. This is our way to say it. Because Keystone itself doesn't know how to talk SEMO, so it needs someone to translate the SEMO protocol into something that Keystone can read and translate into OpenStack's attributes and kind of stuff that OpenStack understands. And we are going to talk more about this translation in the presentation. And basically, this is how it works. You access Horizon, and you select two login via Keycloak. You are redirected to the Keycloak front page, where you put your credentials that are going to be authenticated against FreeIPA. Then once you are authenticated, Keycloak redirects back to OpenStack and you have access to the cloud. This slide is the high-level overview of all the manual steps required, and we are going to describe them in detail next. John will talk about how you will configure and prepare your existing FreeIPA deployment for Federation. I will give you the abridged version of what you need to get up and running quickly with Keycloak and how to sync your user accounts over from FreeIPA. Rodrigo will cover the Horizon configuration, and also finally John will talk about all of the Keystone configuration, including coverage of Melon and the mapping files. So John, tell us about the FreeIPA configuration and how to get it prepared. Keycloak as an IDP is going to use IPA as its backend for user information. It is going to connect to it as an LDAP server. Not all LDAP attributes are released through an anonymous bind, so one of the first things you are going to have to do is set up an account for Keycloak to use so that all of the user attributes can be released. That can either be a standard user account or you can set up a service specific account to do that. There is a password associated with that account and that is going to be set into the Keycloak IDP later. You are going to also have to register the node that this is running on as a client of IPA. This is so you can get certificates to use. Step two is a quick overview of what you would do to register your node with IPA. It is very simple. Step three, we are going to ask IPA to give us a certificate and key for use by the server for SSL. Now I am going to describe the Keycloak configuration steps. There is already a lot of documentation out there already to tell you how to configure Keycloak. I am just going to describe the things I had to do to get Keycloak up and running quickly in my test lab. I use the standalone CentOS 7 server. Because Keycloak is a Java-based service, you will need to install the Java dependency. You see it there in step one. For step two, Keycloak is distributed as a single zip file. You need to download that from keycloak.org and then extract it to your OPT folder. Then for step three, strictly for testing purposes, I generated a self-sign certificate using Keytool. For step four, a lot of the Keycloak server service configuration is done within a file called standlearn.xml. That is where you have to do those three things. You have to set the key store path to use the certificate that you just generated using Keytool. You need to then configure the realm. There will be a master realm or it will be named accordingly to you might call it open stack. You will need to configure that realm to use HTTPS. Then there are also some other socket bindings required. These settings require you to manipulate a whole lot of XML. I haven't shown them here because that could take up pages of slides. But they are described in detail in the manual configuration guide. In step five, the Keycloak service itself is started using standlearn.sh script. You can configure that to run as a system D service. I also describe that in detail in the guide as well. I'll just point out real quick, Martin, that for Red Hat customers, Keycloak is available in an RPM distribution. You can also use IPA to get your certificate and put it into the Java Keystore as well. These are steps we can talk about later offline. All right. Thanks, John. Now, this slide has the interesting part. With Keycloak, they are now configured. You can now access the admin console. This is where you will set Keycloak to sync user accounts from free IPA. When you select the vendor from the drop-down list over there, it will pre-fill a lot of those values there. But in particular, you will need to think about the connection URL. In that example, we are using LDAPS over port 636. Then also, you need to enter the credentials of the free IPA user account that John described earlier. Then Keycloak needs to know where in your LDAP to find the user accounts. That base location is set using the user's DN value over there. To make sure that you've got the distinguished names right, you can also compare them with what you see inside your IPA config file in btcipadfault.conf. Also, another thing to highlight is that for compatibility with the free IPA schema, you need to use the UUD LDAP attribute of IPA unique ID over there. All right. With the Keycloak server, we'll configure U90 to configure your OpenStack environment to be aware of it. You do this using the Keycloak client and then running that registration utility. This also has the result of adding the client configuration to the Keycloak server and also generating the melon configuration file. That gets executed as part of your normal HTTPD processing. You'll need to restart your HTTPD service after you've done this. Oh, yes, sir. Rodrigo, there's some horizon configuration required. Why don't you tell us about that? Okay. For horizon, it needs to know two main things. The first one is how to talk to Keystone and the second one is what are the types of logging options that we are going to provide. To talk to Keystone, we need to set the Presta Keystone URL. It's usually the URL from the controller node, and we also add the Keystone port and version. For the logging options, you'll have the option WebSacialEnabled that we need to set it true, so Horizon knows that there are more options to log in the user besides the regular Presta credentials. For this WebSacialChoice, we set exactly the credentials as the type of logging, which is done by OpenStack directly, and MAPID, which is the protocol in OpenStack terms. MAPID here presents SAML, and John is going to say more details about this in the presentation as well. That's it. Basically, know how to talk to Keystone and set the logging options that we're going to use. Cool. Thanks, Rodriguez. Now, John, there's a whole lot of Keystone configuration required for this to work. Why don't you tell us about all of it? Okay. So really the most important thing we need to do in configuring Keystone is to tell it that we're going to utilize federation as an authentication method. So, inside your Keystone configuration file, the first thing we're going to do is add the MAPT authentication method. MAPT is referring to the SAML protocol. It used to be called SAML2 and a prior release of OpenStack. It's now called MAPT. And in the federation section, we need to set up a few things. The most important is letting Keystone know where to find data that's being brought in from Apache and being able to link it up. This information is communicated through environment variables in Apache. The most important one is the name of the remote IDP and where to find that. Because what Keystone is going to do is it's going to find this information and it's going to say, aha, I know that this is associated with this particular IDP. IDPs are named with something called an entity ID. And so what this variable is saying inside your configuration file is look at this variable. That variable will tell you the entity ID. And from that point forward, Keystone will be able to look up all of the information associated with that IDP. Another important security consideration is that Keystone needs to know that it's cooperating with a trusted dashboard. We don't want Keystone sending authentication information to another endpoint that's not trusted. So we configure the trusted dashboard as an option and that says this is a safe place for you to communicate this information. And finally, there's a couple of templates that are used, the ones that come standard with a distribution to handle redirections and so forth, are perfectly fine and can be used without modification. Everything that's done with authentication really needs to occur over a secure transport. SSL or TLS is always a requirement. So you must have that set up. We set up certs earlier in the presentation. You're going to have to communicate via SSL to your IDP as well. So Apache, which is acting as the front end for Keystone and also contains the SAML module, ModAuthMellon, is going to be using SSL. So we generated the key insert in an earlier step and we just need to set these as values in your Keystone configuration so that it'll utilize them. And finally, the important thing to really recognize here is that Mellon is a translation layer. It handles the SAML interactions. On the right side of your screen is Keycloak, that's your IDP. In the middle is Mellon. It's going to be talking directly to your IDP. And after it handles all the SAML attributes, it's going to stick environment variables into the Apache process where Keystone is running and it's going to read those environment variables. Much of this process occurs through something called mapping and we're going to take a look at that next. I'm going to make an assumption that most of you are in this room or probably administrators are going to deploy things. One of the things that seems to confuse most people is where attributes come from and how you control them. Maybe you want to pass along email or group information. In our example, we're going to depend on group information. In this illustration, there are three independent processes. On the very top left is your LDAP process. Next to it on the right is the Keycloak IDP and then below it is your Apache process that contains both Mott-off-Mellon and Keystone. An attribute begins its life in LDAP and your IDP is going to look up that attribute. Each one of these components has the opportunity to rename that attribute. That's an important thing for you to understand because you might have constraints within your organization on the names that are used or you might be debugging and wondering how one thing that was named something here ended up with a different name there. In this illustration, we're going to look at an attribute I'm just going to simply say is attribute A. It's going to be looked up in LDAP. It's going to be read by the IDP, which has a mapper associated with it. You can rename it. We're going to call it B when it lands in the IDP. The IDP is going to take that attribute named B and it's going to stuff it into a SAML assertion. That SAML assertion is going to flow back to Mellon. Mellon also can rename things. So now Mellon is going to name this C and it's going to stick that into an environment variable in the Apache process. Keystone is going to pick up that environment variable. It's going to see it as C. Keystone is going to map it into something OpenStack can understand and stuff it in a token. At that point, it might be called D. So that's the basic attribute pipeline for how data is going to flow through the entire system. Keystone mapping is a fairly flexible mechanism. I recommend that you read through the documentation on the Keystone area in OpenStack. Let's go through a mapping example real quickly. What we're going to do is try to set up something which says it's a very simple thing. If a user is a member of the OpenStack users group, we're going to unilaterally grant them authorization to use OpenStack. We're going to look at one rule here. The way mapping works is it's a list of rules. Keystone iterates through all the rules and sequence until it finds one that matches. And it's a requirement that all of the rules be satisfied. There's two parts of a mapping. There's the remote part, which is what the data is that arrived from the IDP. And the local part is how it gets translated into Keystone-specific data. In our example here, we're saying that when we look at the assertion that came to us, we require that it have an environment variable called melon name ID. That's the name that's associated with the user. And we're also going to say that there must also be a variable called melon groups, which is the group information that's associated with this user. Now we're going to apply one additional constraint on that group information. We're going to say that user must be a member of the OpenStack users group. If all those conditions are satisfied, we apply the local part of the rule. And the local part here is very simple. We're going to put two pieces of information in the token. The name of the user, the name of the user here is index zero, which is the first variable from the remote section. And that's the end of the data that we're pulling out of the assertion. We're just going to unilaterally say, since they passed the test that they're a member of the OpenStack users group, we're going to force that user into the federated users group in the federated domain. We can do this. The mapping is flexible. And so what we've done is just said, if you're a member of a group that has, you know, know anything about an OpenStack land, we're going to say, you are now a member of this group in OpenStack land called the federated users. You're going to create that mapping file as a text file. It has to be uploaded into Keystone. Step seven shows the command line for doing that. I'd also like to point out that Keystone Manage, which is a command line utility, has a tool available to you, which can be very, very useful. And it allows you to test your mapping rules. It's called the mapping engine facility. And it's a great thing to run as you're developing your mapping rules. It'll show you how the process is working. Step eight is simply creating a binding between these rules and the IDP that we created. And step nine is creating some objects in OpenStack that will be utilizing, such as projects, domains, and so forth. Thank you, John. Now, Rodrigo, now that all the components are configured, can you tell us about how it's all going to look now that it's all up and running? Okay. So I think the best way to see this is through a demonstration. So let's play it. Okay, let me... Okay, so here you can see the free IPA login page. We are going to show you the list of users that we have in this in free IPA, actually. So here we are logging in with the IDMine credentials in free IPA. And here you can see the complete list of users that are registered there. And we are going to use SAM, which is the one that we selected there, if you've not seen it, to login into OpenStack. So move forward. Here is the key clock IDMine login page. We are going to show you how the connection with free IPA is configured and also show you that key clock has access to the free IPA users that we just see. So there you can see the connection configuration to talk to free IPA. There you see the connection URL. And we can also test it if everything is working fine. So it seems to work. And we can, for example, see the list of users that free IPA provides. So we can see the same user that we are going to login into OpenStack there as well. So now, we move to Horizon. And we select key clock as the login option. So when we click on connect, Horizon is going to redirect to key clock. What just happened? This is a failure in a recording. Okay, it's going. Okay, so what it didn't show here was that we were redirected to key clock. We used the free IPA credentials to login. And once the user is authenticated, we were redirected back to Horizon. And we are logged in. So here you can see that the user has the capabilities of our regular OpenStack user. And it can create instances, for example, and so on. Cool. Thanks, Rodrigo. Let's see. It's in this. So now, John, you had some troubleshooting tips you wanted to share with us. Nazy Johns. Sure. I would like to tell you that this works out of the box very simply 100% of the time. It doesn't. I'm sorry. You're probably going to have to do some diagnostic work when you first set this up. Samo messages come in two forms. There's the request for the authentication. And then there's the response back, which is your assertion. So one of the best pieces of information you can gather if things aren't working as you expected is to look at the Samo messages that are flowing back and forth. Now, the good thing in our favor here is that this is all browser-based. So it's very easy to install browser-based tools that can decompose these Samo messages and present them to you in a human-readable form. The particular tool that you might use depends on your browser. If you're using Firefox, there's a tool called Samo Tracer. If you're using Chrome, I know of at least three different tools, plug-ins, add-ons that you can install that will decode these Samo messages. So you would be able to look at what Mod-Off Mellon is sending to your IDP in its authentication request. And you can see what's coming back from the IDP as well. Tremendous amounts of valuable information in both of those. The other place that you're likely to run into problems is your mapping may not work as you expect. That's certainly going to throw a monkey wrench into things. So why might your mapping not work correctly? Well, it could be that you're not seeing the data. The mapping engine is not seeing the data you expect. Remember that Mellon is going to communicate this data through environment variables. So a handy little trick that we can do is to temporarily install a different handler whose only job is to spit out the environment variables inside Apache. This slide shows you the script that you can install, and that'll show you what Keystone is actually seeing as a result of this Samo authentication. There's another way that you can tackle this as well. If you turn on debugging inside of Keystone, the mapping debug log messages will also show you everything that it saw, as well as how to apply its mapping rules. So turning that on can be a tremendous help as well. Also don't forget when I mentioned a moment ago about being able to run the mapping engine rules independently through the Keystone manage. It's a tremendous tool for helping you debug and analyze what the mapping engine is doing. But those three together, and you probably won't have too many problems. All right. Thank you, John. So we had a bit of a late start to this session, so we actually might not have time for questions as part of this. But we'll be standing outside to give this the folks time to prepare for the next one, so you can find us out there for the next bit. Thank you, everyone.