Using the Restful API to manage Active Roles

Hello, my name is Wayne Smiley. I'm the Principal Architect for the Active Roles product by One Identity. In this session, we're going to cover probably what I think is the most exciting new feature around Active Roles, and probably the most useful for a lot of customers, and that is the Rest API. It's something that's been requested many, many times and forever with our product, and we've gone ahead and added it now. And as a matter of fact, it's really going to be the cornerstone of how the product works over the next 12 to 24 to 36 months. But let's go ahead and spend a little bit of time talking about it. Specifically, we're going to talk about how it works, how to make it work. And then we're going to go through some examples. And lastly, I'm going to show you how to actually do something specific in Service Now to have Service Now call Active Roles and do something that you want to do. And we'll dig deep into this. This will be a little bit techy if you will, in terms of how we're going to go about doing everything that we do. So hang tight and let's get started. Though there are many ways of doing authentication to a Rest API, really probably the easiest one to do is use a bearer token. And so that's what we're going to do today, and that's what Active Roles supports at this time. Now that may change in the future, but for right now, we're just going to go ahead and use that. So what I've done here is, in order to make all this work, the first thing you have to do is you have to set the RSTS. If you haven't already done this, you're going to find this on your Active Roles server in Program Files. We're in Identity, Active Roles, your version. And incidentally, I'm using this right now with version 7.43, so you don't actually have to have the 7.44 and after that. This is backwards compatible, this is a separate downloadable installation. So the very first thing you need to do is, if you haven't already done this, and in this case I already have, you need to run the RSTS which will actually install the application and set everything up. But since I've already done that, I can just run this. I need to run the administrative console. And here you go. You can see pretty simple stuff. Since I'm not really setting anything in particular here, I don't have to do a whole lot. As matter of fact, you don't really have to do sort of anything here to get this kind of running. I just had to give it a username and password and log in. But in any case, I don't actually have to go through and do much and do much configuration for this. Normally if I were doing this with and using the RSTS to say configure Azure AD authentication or something like that, I need to go much farther into all this. But we don't have to do that today. It just basically has to be running. So here I'm just using Postman, which is just a very simple Rest client I guess, program, whatever you want to call it. All I'm doing here is, in order to get the token, I'm just running it here. And I need to just go ahead and run that really quick. And what you're going to see is that the response that I got back was a token. And all I need to do is cut and paste that token I need, and I'll save it somewhere else. We'll just do that real quick. Incidentally, before I forget, you do need to add a few things in here to make this work. So I needed to tell it the grant type, that's how I'm going to log in. And I'm logging with password. Here's my username. There's my password. And here's the scope. This is the one thing I did have to grab, so you'll need to know what that is right there. And then once I do that again, I can hit send. And we can go ahead and get this bearer token that we have right here. Fairly simple, straightforward, easy to handle. So once we have that, then we can actually do something useful with Active Roles. Couple of test cases that I did here. So again, I'm doing some stuff with Postman here just to make my life a little bit easier. The one thing that we have here is that you can see that I'm using the external URL here. And then I'm using the rest of the URL that's required to actually call the Rest API. Now notice this is a different URL, because I'm actually calling a different portion of the server with a different port. It's actually port 5,000, but because of the way I'm doing this, I need to use a particular port here that's different. So yours will say 5,000, while mine says this 2,505. The next thing I want to show you is really how we've made your lives a lot easier. We've gone ahead and we've used a Swagger API. And this will be public, although it isn't public right this second. But here's all my information. So I can use this to basically do anything that I want. So for example, here we're looking at a particular object and a particular name, the name attribute here. So if I look over here at Swagger, you can see that I use slash object, slash object GUID, slash attributes, and then attribute name. And obviously I have a get or a put or a patch or delete or whatever. In this case, I'm we're just going to do a get, which is simple. So basically, what I'm telling it here is, I want you to go grab this user. And again, I can hover over this. I'm using a variable to make my life a little bit easier. And I'll need to grab this GUID, and I want to grab the name. So this should be super, super simple. Just grabbing that real quick. And I just rebooted the server, so it may take a second for the first one to go through. The rest of them should go very, very quickly. OK. And you can see here that we got the name of that user, that particular user's name or CN is defender user 1. So again, a pretty simple call that we've made here. We just want to do some pretty basic stuff. What if we want to do something a little more complicated? What if I want to create a user? No problem. So here, what I've done again is just to make my life a little bit easier, I've gone ahead and used a variable for the URL. And I just need to tell it it's in the objects container. I need to do a post, but I do actually need to tell it what I want to do. So we'll go over here to the body. And instead of using just form data, I've gone ahead and just done this because I could easily cut and paste it from Swagger. As you can see if we go and take a look right here. And we go to Users, and Post and Create a User. You can see I pretty much just stole this from right here. Just to make my life just a tiny bit easier. So all I'm going to do is I have an OU again using a variable. This is just the GUID of a particular OU in Active Roles, which is actually the GUID from Active Directory, technically. And I want to create a user. And I just want this name. Now, the first thing you're going to think is, wait a second, I can't create a user with just a name and nothing else. No, we can. And the reason we can is fairly simple. And I'll show you why in a second, but let's go ahead and actually create this. OK, so we can see here is that we've got a to have status 200 OK. And we can see that we created the user. And here is the GUID of that particular user. So let's go over two Active Roles real quick, and let's see if we can find. So we'll go back into there, and I conveniently just created an OU called Rest to my life easier. And there's my user that I created right there. Now, back to the other question of how does this actually work, and how do we do anything useful with it when I gave it just a user name. Now obviously, I could give it a lot more, but I don't need to. Why? Because I'm just going to use Active Roles policies. I mean this is what's great about combining these two things. So I've just got a basic provisioning policy here somewhere. So here, I'm just going to go into my policies like I said. And I have a default user provisioning policy. And this policy will do all the things it should. Generate a login name, generate a password, create an exchange mailbox, provision them as a Linux user using authentication services. Basically validate all this information, set up everything that I want. Even create an account. In this particular case, I believe it's creating it in Workday maybe. I forget where I'm doing it. But something through our Starling Connect product. All those things are just happening automatically. I'm not going to go into the details of how that works. You guys should already know that. And if you don't, then that's a different class. But my point is that now all I did was which is use Rest to just do some very basic stuff, and that was able to actually setup and create an account for me. And I can do other things as well. So for example, I can call workflow. Again, here's my URL objects. This happens to be the GUID of the workflow. I can go ahead and send this. In this case, I'm just going to do a get, but I could just as easily do something to call it. And what you'll see here is you can see that's the display name. You can see the last time it was changed. All that stuff is right here. So this is incredibly useful when it comes to just doing some very basic things. I can now use all these other systems that I'll call rest, and have them actually do something useful for me. So now let's put this all to the test and do something kind of interesting with it. I'm not much of a Service Now developer, I've kind of had to learn on the fly. But I have a basic sense of how this works. And so I thought we could use Service Now to actually do something useful with Active Roles. Few things first we need to keep in mind about how Service Now operates. So basically, there are a few components we're going to have to do in Service Now to actually make us do what we want. The first is a business rule. And a business rule is basically, think about it like their equivalent of an Active Roles workflow. If this, then that. So if I want to do something, I need to tell the business rule to do it. The next thing I need to do is use their Rest interface to actually build the Rest API to have it do what we want to do. So let's actually start there. If I go over here, I've got my own little world. One of the things I did is I created a set, and you can see those right here under my WS Active Roles. And what I did is I actually put my token writing here so that actually I don't have to use it. I have multiple Rest calls here, and I only have to put it in there once. And keep in mind, by the way, I've set this token to work for 24 hours, so it won't do any good if you take a copy of it. Again, you can see the URL. I already have it set here. And I'm just leaving my stuff in here. And I have two different ones. So one I have a check name of user. And again, this is pretty much exactly the same one we just saw before. And just so we can see what's going on. What I basically have is I've got to tell it I want to do a get command, and here it's pretty much the same thing. Now, one thing that makes this not terribly useful, but just a good thing to play with, is that everything in here is static. I'm just telling it, hey, make a Rest call and go find out the name of this user. That's not terribly useful. But just so we can see what that looks like. We can do that, I can click Test. And you can see I got a response here, and that response is exactly what I would expect it to be, which is defender user 1. Let's go back in. But I did create a second one, and this one's a lot more interesting. And the reason for that is, this one's all variable based. So what you're going to see here when we take a look, is that I'm just going to the objects and I'm using a post. So that will create a user. But in the request, I'm basically telling it uses this variable, which is dollar sign ID. And what that is is that is the name of the object that I want to have it create. Now, I've hardcoded the parent OU I want to create it. But the name here is set over here. What we're going to do is we're going to use something that actually fires that and uses the real name. And here's the trick thing. And it's funny, you just got to see how this actually works. It's really, really cool what they've done here. Since everything in Service Now in the back end is actually using code, here's the code. So all I have to do is take this, cut and paste it, and put it into my business rule. And it will do what I want. So let's go do that. Let's take a look. So what I've done here is I'm going to go into my business rules. And you can see that I've created a one business rule here. And for some reason, it always takes a little while to come up in Service Now. I have no idea why. If I hit a couple times, it'll pop up a little thing saying, hey, I'm waiting. And see, there we go. The thing I find so odd is I don't know why this particular thing in Service Now takes a while. And again, I'm not a Service Now guy, so I may not be the right person to know why that is so complicated for Service Now. All right, and eventually it came up. So what I've told it here is, this is my name. I'm telling it to use the user table, which is basically where all users exist in Service Now. And then I'm telling it when I want to run. And I'm telling it before, and the order usually doesn't matter. Before I do an update to an object. And in here, it's when I changed the title to IT technician. So why is that important? Because conceptually, what I'm actually going to try to do here is go ahead and have it create an administrative user in my environment each time somebody is created or changed to a title of IT technician. So pretty cool. So let's dig a little deeper. Here, I'm telling it what to do. I want to do two things. Number one, I want to set their department to IT, so it's nice and clean in Service Now. And then also, and the most important part here is, I want to run that script. Now, this is an exact copy of the script that I just showed you a second ago. The only difference here is that I've gone ahead and I've told it to set the ID of ID to ADM dash plus the current name, which is the name of the user who's being changed. And again, this is just some googling around. I learned this in Service Now. I assure you I am no Service Now guru. I figured this out pretty much on my own. So basically, what's going to happen is I'm going to change the name of that user to ADM dash user name. That way, I've now created an administrative account for all my IT technicians. So pretty simple and pretty straightforward. And now, we know exactly how it works. Let's go give it a shot. Let's go to Users, and let's go find my lovely friend here call AA Test. Let's open them up. And they are ready in IT Technician. So let's change them to something else, because I've already done this test before. So we'll change them to Administrative Assistant today. So you can see that. Let's go ahead and do a save. And that will update those changes. Now, I want to change them to my IT Technician. So let's go ahead and click Save. Few things that you notice will happen. Number one is a couple of things we don't particularly care too much about, that was just me messing with the business rules. But you can see I changed my department to IT. It also put this name up here when I was messing around with something that really we don't need anymore. But let's go look at what we actually do care about. And that is that we created a user account. And assuming we did all this correctly, there it is. I have a brand new user account. And again, I didn't have to give it a lot of parameters, because Active Roles is going ahead and taking care of all those parameters for me. So what we've done here. Let's kind of recap everything that's happened here. We've talked about how the Rest API works. What you need to do, how to setup authentication, some examples, how to get to Swagger. Which, by the way, you can just go here's the URL right here. If you just go to swaggerhub.com and search for Active Roles, you'll find it. That's the easiest way to get there. We went over some examples. And then I showed you guys a real practical example in Service Now to have Service Now do something. A lot of customers have asked about, hey, can Service Now call a workflow when something needs to happen. And the answer is yes. You can have Service Now actually action the items. So some customers like to do their workflows, like approvals and whatnot, inside Service Now and then have Active Roles actually do that work on the backend. And you're absolutely easily going to be able to do that with the Rest API. And incidentally, as we all know, the Rest API also has PowerShell. So we could call the Rest API outbound using a script or whatever very easily, and use that to call to Service Now well. Lastly, and I didn't show you guys this in Service Now, but because I made a complete call with the REST API, it actually pulled back the response into Service Now. So Service Now could use that to update a ticket. So if there was a request that went in, and Service Now approved their Quest and whatnot, but then Service Now to action that request inside of Active Roles, Active Roles could tell Service Now yes, I correctly did that. Here's the information, stick it in the ticket, off you go. All is done and well with the world. And I know a lot of you guys use Service Now, and that's why I use this as a particular example, because I think it's probably the most useful. But just about everything out there uses Rest. So really the sky's the limit in terms of what you guys can do with this. So we're pretty excited about the Rest API and what it means for Active Roles going forward. And just very briefly, I want to mention that as we move forward with the product, the Rest API will actually be the glue that glues everything from the web interface to the Azure components to the on prem AD components. It's going to glue all those together so that you don't really have to have these complicated interactions that we have today. So it's going to be faster and better and easier to understand everything that's going on. So the Rest API that you're seeing is just the beginning. And incidentally, one other thing that we've done with it is we've use the same Rest API to connect our own safeguard tool, which is our pillage account management tool. And using that to call into Active Roles to have it do things like create an account on the fly, as opposed to turning on and off an account when somebody needs to check an account out. And adding and removing users from an AD group on the fly again, so that you'll be able to do all those things at a much easier way. And because that particular product also is completely Rest API based, as Active Roles is starting to become, we can just interact with those two tools in a very fluid manner. So you'll see that again with all of our products. And I hope this has been really helpful. And incidentally, there is another session specifically on Service Now. And they've done a lot of other things. So one question that you might have is what's the difference between what I did here and what they did. They were using Soap, and I'm not. I did this all through Rest. So really the concepts and what they did were the same in this as what was done in that, but I'm using a simpler way to actually make it happen. So going forward, this will be an easier way to do it. And with that, thank you very much for your time.