PowerShell Universal Project - Active Directory Tool - Part 1 : Creating the API Endpoints

hi and welcome to this Powershell Universal project Series this series we're going to be focusing on creating a cool little help desk application that's going to let users search for users in active directory they're going to be able to see some of the information from active directory whether the account is locked out enabled or disabled and also see their group membership and be able to reset their password now this is going to be a multi-art series where we're going to be learn using all the things that we've learned in the Powershell Universal series that we've just finished and we're going to be incorporating those so this video is going to really be focusing on creating those API endpoints that we need for our application now we are using API endpoints in our application doesn't mean that they're actually fully needed we could in fact make this whole application in the user interfaces and just add a lot more code into our user interfaces buttons and the onclick actions but the reason why we're creating API endpoints is the fact that it's going to be a bit more flexible in if we're actually going to be creating more user interfaces in Powershell Universal maybe we want to reuse some of those API endpoints because they can be useful in other applications but also maybe eventually we're going to be only using Powershell Universal as more of a backend and maybe we're going to be building a front end with HTML CSS and JavaScript and in that case we can just call the API endpoints to get that same data but we can make a different user interface and a different login method for our front end um so it's just the ability to really be able to reuse that code a lot more often or maybe you want to create a Powershell module and give it to your users and they could simp simply you can create commandlets that will just execute against the API endpoint and you can do it that way as well so they don't have to use the active directory Powershell module these are all different abilities that come with the API endpoints versus just coding it in the user interfaces so without further Ado this is going to be a multi-part series and this video might be a little bit on the longer side because we need create quite a few routes um so let's go ahead and let's actually get started here so basically what we're going to just do here is let's go to our Visual Studio screen here CU what I like to do is I like to just build out um what we're going to need in visual studio and then we're going to go ahead and we're going to move to actually building that those API endpoints in Powershell Universal let's go ahead let's just shrink this a little bit and Shrink this a little bit so you guys should be able to see the code nice and clearly so what we really need is based on our description of the application is we're going to need a route that's going to be able to get a user we want to be able to get the user's groups um so get User Group membership um and then we're also going to want to reset the password potentially as well uh we also said that we might be unlocking the account and we also said that we're going to be enabling or disabling the account let's do enable slash disable account we're going to do these in two separate things but we're going to put them on one line item so these are really the line items that we need to tackle for the API endpoint so let's go ahead and let's start with just just the get user command here that we're going to want to get for our API endpoint so what I really like to do is I like to do everything in Visual Studio code before I do it in Powershell Universal just to make sure that my code actually works and there's a little bit of better intellisense on Visual Studio code there is intellisense on Powershell Universal as we've seen um but this just makes it a little bit more straightforward and a little bit more familiar for people so so what we're going to first want to do is really get our user so we're going to create a variable called user we're going to make that equal to get 0 user and then we're going to do an identity now here uh since we are wanting to pass in a user we're going to do a dollar sign username here we're just going to create a dollar sign username equals a pair of empty brackets or empty pair of uh double quotes here and let's go ahead and Let's do let's get all the properties back and let's Supply the server here which for us is Jack doca and let's go ahead and let's get our test employee 3 here and let's see what we get back all right so we have our user object coming back we can see all the different properties I can go ahead and expand that there so you guys can see all the different properties that actually come back so now we need to determine really what we want to display to our end user in our application that's going to be really really helpful for that and what I want to do is I want to create a result since we're creating an API endpoint we know that an API usually not all the time but usually gives back a response and we want that response to be a fairly good response and in this case we want our response to actually be our user object so what we're going to do is PS custom object here and let's go ahead and let's create our object that we want here so we definitely want the user's name so we're going to do user do name and erase this bracket here uh the other thing that we might want to do is grab the username now I actually reference it as username in here in active directory it's going to be Sam account name but maybe the users that were targeting this application to might not necessarily know what a Sam account name is so that's why we want to call it a username and then we're going to say a user principal name now this might be another one where you might want to change this to email email a lot of users might understand email more really depends on the clientele that you're aiming this application to be for um so we're going to make that equal to user. user principle name and let's go ahead and let's do employee ID cuz we want to get that back so that's going to be user do employee ID and let's do title as well so we can see what kind of job they have and that's going to be user. tile and then of course if we want to be able to enable disable unlock the account um and reset the password we're definitely going to want the enabled field here uh enabled is going to be equal to user do enabled and then we're going to do password expired and we're going to make that equal to user dot password expired locked out so whether the account is locked out or not we're going to say user do locked out and then we want to grab the last bad password let attempt and that we're going to make that equal to user dot last bad password attempt now we have everything that we need and let's go ahead and let's look at what our result looks like here so it's result it's singular let's go ahead and let's launch this code here and there we have it so we have our employee ID which in this case is null and we have title which is null um so what we can actually go ahead and do just to make sure that we actually have data in there let's open up our active directory let's open this up real quick let's give this person a job title of programmer and let's hit apply here and I don't have the additional info so let me just go ahead and add the additional features here and let's go into attribute editor and let's find the employee ID and let's go ahead and let's set that to 0 12 all right hit apply and let's close out of it and let's rerun it now we have our employee ID and we have our title so we know that everything is working here so now what we can go ahead and do is we can go ahead and create our API route for this get user here so let's go ahead and let's go back into our Powershell universal window here and we are going to create a new endpoint now our URL is going to be get user and here's where it gets a little bit tricky so we're going to be doing it all through query strings now you can do it through with body um passing a body but we're going to be doing all these through query strings makes it a little bit easier especially since all of our API endpoints we are just going to be passing a single value which is going to be username um it makes it a little bit simpler so let's put in username here and our method is going to still be a get because we are just getting information here so let's go ahead and let's click on okay and we should see it pop up very soon let me just actually refresh here oh it probably need to recreate it because it looked like I got timed out here so let's create our endpoint let's do the get user slash colon username and the method is get let's click on okay and there is our endpoint right here so we can see our endpoint now let's go ahead and let's just edit the properties of this endpoint and I want to remove the authentication in my case and I want to make the default environment let's make it 7.4.1 and let's go ahead and let's click on okay and that should be working just fine let's go ahead and let's edit the details now so now we're going to be provided a spot where we can put in in our code and let's go ahead and as you can see here with the colon username that makes it so that we could pass in our query string which is going to be username and the awesome thing is is that is referenced just with dollar sign username so any uh parameter that you pass through a query string is just the dollar signed anything that you put in after the colon so let's go ahead and let's copy paste that code in here and the only thing that we need to add in front of the result is just return result and let's hit save and then the nice thing is we can actually go ahead and test our route here so let's go ahead and let's put in test employee PR and let's hit run and there we go we get our data back so if we actually just scroll through here we are able to see all of our information come back perfectly fine we see all of our data here so that is great all right so let's go ahead and let's hit save one last time just to be sure and let's go ahead and let's go back and let's go and move on to our next Endo which is going to be the user groups here so what I'm going to do since I are already know the code for these I don't really necessarily need them to do them in Visual Studio code we're going to go ahead and we're just going to go ahead and create a new endpoint here and we're going to make our URL get user groups and we're going to do a slash Colin username again once again this is just going to be a get because we're simply getting the different user groups and let's go ahead and let's make the exact same thing here so remove the authentication let's put our environment to 7.4.1 now you can leave this at default as well that will work just fine and let's click on okay and let's go ahead and let's edit our script here so let's go ahead just make this a little bit bigger for you guys and let's just zoom in and let's work on this code so what we want to do here is we want to get back all of the different groups that we belong to so what I want to do is I want to start off by initializing our result variable which is what we are going to be um giving back to the user and we're going to want to create that as an empty array here so we're just going to do dollar sign result equals an empty array and then what we're going to do is we're going to do a groups equals get- a principal group membership identity username and then the server once again for us is just going to be Jack doca now the main reason why you might be wondering well why can't we just pass back the groups um object often times Powershell Universal will not actually like passing back those objects because they are too big or they are just not a really good type to be opened back back up with Json you're going to encounter a lot of issues that's what happened to me when I was trying to get back a list of users it would work if I had a very limited subset of properties but as soon as I was pulling back too many users or too many properties Powershell Universal was just not really having it so I really like to kind of customize what I send back to the user as well I don't necessarily want everything of what the active directory command let's give back so we want to give a very very specific subset and we can keep that to exactly what we want to display to our users we want to give them just enough and not too much to where they don't really need all that extra information and that might just confuse them so you just give them just enough to where they can actually function and that's usually the best way to go about it um so what we want to do now is we want to do a for each group in groups so we want to Loop through all of our groups here and we're going to do a pair of curly brackets and let's go ahead and let's get the group details now so we're going to do a group details equals get ad group and see now we can get a lot more information on the group so we're going to be getting the ad group and we're going to be getting all the properties for this group we want to just specify the server again which is at.ca and then what we want to do is we want to create an object again so we're going to create an object called entry and we're going to make that equal to a PS custom object and let's go ahead and put name is going to be equal to group. name and then we're going to want a group category so that will tell us if the group is either a distribution list or a security group and then we want group dot group category and let's do a group scope this will tell us what the scope is for active directory on that group uh so that is going to be actually in group details do group scope and then we want the description so this is going to be the description that we have set in active directory so we're going to want to get that from group details dot description then all we're going to do after we create the entry object is we're going to add it to our result array and then all we want to do after that let me just go back here all we want to do after that is return the result here so return results and we can hit save let's shrink this down and we can go ahead once again test with our test employee 3 hit run here and we can actually see that it's part of domain users which is a group category one so that's a little odd we might have to change that we have group scope one and description all domain users you have domain admins group category is one so a really good way around that actually to avoid the ones there what we actually want to add is A2 string after the group category and after the group scope so if we do two string and then two string here let's hit save minimize that and let's just run that and we got an error here so this is where um running it in um Visual Studio code can definitely come in handy so let's go ahead and let's see why we have the problems here let's go into our Visual Studio let's put it in here and let's run this code here let me just run this up and if we hit run everything here looks good to me so let's go ahead and let's see why that might not be working let's hit save real quick and still nothing let's just make sure that everything is looks to be good I mean we copy pasted it in Visual Studio code and it was working just fine what we might also want to do is what I often do is I'll just go back into the properties change it to default here let's go back and let's run it again against test employee 3 there we have it so that is now working now and we can see that the group scope is now global so these are all things that you might want to take into account when you are manipulating some of your different routes and let's just go ahead and let's just change the the environment back to 7.4.1 and let's just see if we get the same error that we were getting earlier now and we aren't so sometimes you'll have some weird um issues with the preview of the code running if you copi it into Visual Studio code see that you're not having any issues just exit out of the API endpoint maybe change the environment um or just go back into it and rerun it and see if that really helps um I usually find that that usually solves the majority of the issues and we can now see that group category is shows Security Group scope shows Global so we can actually read them they're not just one which will make a lot more sense to our end users let's go ahead and let's just go back here so we have a few more routes to create what we're going to do is I'm actually going to create one more route in this video and we're going to call it there for this video and we're going to do um the other three routes in the next video and I'm going to tell you guys what the routes are you guys kind of already know what the routes are and see if you guys can figure them out by the next video um and if not I will be walking you guys through creating those routes so let's go ahead and let's create the reset password route here which is going to be our first route where it is not a get so we're going to do reset password slash colon username and we're actually going to make this as a uh we're going to make this as a patch now I would put it as a patch or a put um or a post that would usually be um probably My Method here we can even go look at um what they usually are here so we can actually say HTTP methods um in rest API um they might have some definitions on what would just make more sense so get we know um so post is usually sent from forms when you're posting or saving data or calculate a result salt um so put is to completely replace a resource um and then patch is going to be uh significantly so send a small pay payload where rather than a complete resource representation to the server so since we're only resetting the password this is where I would use patch because we aren't really modifying a whole user we're just resetting and changing a really small portion of the user so that's where I would use patch here and let's click on okay and let's go into the reset password let's go edit properties remove that authentication put to 7.4.1 and let's go ahead and let's actually just do the entire thing in Visual Studio code first and then we'll go into Powershell Universal just because it was a little weird last time so we're going to make sure that it actually fully works first and then go from there so what we want to actually do when we're resetting a password for a user through an interface what I actually like to do is I like to get the user's password policy first so we're going to know exactly how long the password needs to be so we can actually set it to that and give it the best possible chance of being a password that is going to match the password policy so what I want to do is I want to create a variable here called password policy and we're going to make that equal to get a user resultant password policy and then identity is going to be usern name all right and if we go ahead and we actually run this we're going to see that our password policy we actually get it and we see that the minimum password length is 12 um so we can see that we do have a password policy applied on test employee 3 which is perfect now what we need to do is we need to create our character set that we're going to want to use to reset that user's password so what I like to do is I like to create um a couple arrays a total of four arrays um of different character sets so what we're going to create is our first one which is going to be our uppercase set and we're going to make that equal to an array of numbers 65 through 90 and we're going to pipe that to a 4 each and we're going to do a curly bracket and then a square bracket with car for character and then dollar sign uncore here so what this actually does if I just run this little bit of code what you're going to see is if we go up here it generates me a list of all the letters a through Zed uppercase so what we're going to want to do is we're going to want to actually copy paste this line multiple times we're going to change it now to um lowercase set and then I name one uh numeric and then I also get a um special uh special set here so the lowercase is going to be 97 through to 122 the numeric set is going to be 48 through 57 and then the special set that we want I actually make a custom special set um just because I just want the exact ones um that are very easy for users to put in like percent sign um exclamation mark the at symbol I try to avoid ones that are a little bit more complicated um so that's 33 35 36 37 38 42 and 63 and you can simply go ahead and check out what it what it is so right now what we have is the exclamation mark pound sign dollar sign percent sign Ampersand star and question mark now you can add the at symbol if you guys want it as well um I decided to leave that one out um as in some keyboards sometimes the at symbol could be a little tricky um and then what we want to do is we want to create a variable called car set which is going to be equal to all the sets combined so we have the uppercase plus lowercase set plus numeric set plus the special set and then what we're going to want to do is we're going to want to create a um variable called password plain text Tex first and that's going to be equal to a dash join open parentheses get random and then the count that we're going to be getting the random on is going to be the password policy dot minimum password length so what this does is this will instantly get a random number now for the length of password policy and then the default I believe is 1 through 10 so you're going to see a bunch of different numbers here and what we're going to want to do is we're going to want to put the input object as the character set now what this is going to do this is going to take our character set and choose use a random number of those characters to make a password so as you can see our password is TI fq ersan Z lowercase o0 9 a uppercase E now what you could easily do is you can easily um remove the O's or the zeros if you don't want the confusion for the user I would totally understand that as well and then what we want to do is we want to create our password variable which is going to be equal to our password plain text and we're going to want to pipe that to a convert to secure string as plain text and we want to force that and then all we need to do now is set ad password identity is going to be the username the new password password is going to be password not the password plane text because it needs to be a secure string for it to work and then we want to do a reset here and then all I really like to do now this could be completely up to you in your environment what I like to do is I like to do a set ad user identity username change password at log on is going to be set to true now what we should be adding in here which I don't have is our server here we always want to make sure to add that in in case you have multiple uh domains here so we got our set ad user and our set ad account password and then all I like to do is create our result object as always we're going to make that equal to you probably guessed it by now a PS custom object and instead of name we want username and we also want new password as the other value here and then the new password we're going to put that as password plain text the username we're just going to pass in username here and then all we really want to do is do a return result here so let's go ahead and let's copy paste this code here into our Powershell Universal let's go ahead and let's edit the details here and let's copy paste all of this stuff in here and hit save and let's go ahead and let's enter in our username which is going to be test employee 3 and let's hit run there it is there's our new password which is PL C question mark capital n F RH QB we can run it again and again and again we just keep getting these new passwords um so it works very very well you never really have to worry too too much now you will get the odd error at times because of we haven't quite put in place yet that it requires the special Set uh um that is up to you if you want to put that in there all I literally do is I just hit run again and it creates a good password um so you can definitely add some extra intelligence in there to make sure that there is a special um set um the chances of it not containing one from what I've gathered is fairly low um it really depends on what type of password policies you have in place uh most of the times I've never really encountered too too many issues so all we want to do is hit save now and let's go back so we have three of our six routes here um the other six routes are actually fairly short so let's go ahead and let's tackle them and the nice thing about these next three um API routes that I actually just realized is that they're all fairly similar so they shouldn't take us that long actually so let's go ahead and let's just go back into our Visual Studio code and let's look for the unlock account so all this one actually is is it's fairly simple it's just going to actually be unlock dad account identity is going to be username server is going to be jack. a and we want to put the confirm as false because we won't have the ability to confirm it through this API end endpoint and then all we want to do to get again to pass back to the user to make sure that we've unlocked it is we're just going to do a get ad user identity is going to be username properties locked out cuz all we really want is just that and then our server is going to be jack.com object and we're going to have username is equal to dollar sign username and we're going to have locked out is going to be equal to us user dot dot locked out all right and we are just going to return the results here and we can actually go ahead and test this out as well so let's go ahead and let's just put this into our Powershell Universal so let's create our endpoint and we're going to name this unlock account slon usern name and once again the method that we're going to use is we're going to put in as patch here and we're going to click okay and let's go ahead and let's edit the properties remove the authentication put it a 7.4.1 make sure yeah okay there you go and let's go ahead and let's edit here and let's copy paste our code and let's hit hit save now our user isn't actually locked out currently CU if we go and test employee 3 we can tell that it's not locked out at all we can tell that we've reset the password because we have the user must change password at next log on and it's not locked so let's go ahead and let's trigger the account to actually lock out here so let's open up notepad as a different user here and let's launch it as test employee 3 a few times here all right so we have the referenced account is currently locked out and may not be logged into so everything there seems to be working great and let's go ahead and let's put in our test employee 3 and let's hit run we have our username locked out is now false so now if we actually go into active directory we could also just go into one of our other routes here um but we can see that the account is not locked out and we can actually just do one more test just so you guys can actually physically see the account locked out on um active directory let's go test employee 3 test employee 3 test employee 3 all right so says it's locked out let's go ahead open up test employee 3 we see unlock account this account is currently locked out on this active directory controller if we hit run we reopen the user here let's close let's reopen the user here we can see that the account is no longer locked out so our route is working correctly here so let's go ahead let's hit save and let's go back so we already have four of our routes the only two routes that are missing are going to be the enable and disable routes which are practically the same route just one little difference in a variable here so let's go ahead and let's write the code we're just going to write the code for one and then we're just going to paste it into the two other routes just changing the information that we need so to enable SL disable an account what we need to do is set ad user with the identity of username here and we want to set the enabled is so to disable the account what we want to do is set enabled to false we want the server to be jack.com and that is really it for disabling the user so let's go ahead and let's copy that code let's go back into our Powershell Universal create our new endpoint and let's call this disable account slon username once again we're going to put that as patch here click okay disable the account let's remove the Authentication put the environment and let's go ahead and let's edit the details paste that script in here everything there looks great and let's go ahead and let's disable the test employee Bri because we know before we actually run it we can actually see that the account is active if we hit run uh we didn't not get anything back here return results and let's just refresh and it is not set here so let's go ahead and let's just run this code in Visual Studio and that worked perfectly fine so let's go ahead let's reenable the account here CU we're not getting an error has occurred oh so something you always have to do that I just forgot is also which is a very good good tip always you need to hit save on the editor before your code is actually going to work in Powershell Universal there we are so um it's getting an error uh so let's see so let's just actually exit out here let's go back into the code let's go test employee 3 run that there you go it's working it's enabled as false so we can go ahead and just refresh so we see our user is disabled so if we go ahead and just reenable it real quick hit run once again it ran if we hit refresh once again we see that our user is disabled so our API endpoint is actually working correctly here so then all we really need to do is actually copy the code from our disable and create our new endpoint and call it enable account slon username change our method to patch here and click on okay and let's go ahead and let's just make sure that we removed the authentication put it to 7.4.1 edit the code paste it in here now the only thing that we want to change is the enabled instead of being set to false we're going to change that to true hit save and now let's go ahead and let's go into our active directory once again and I think it's actually still disabled because I haven't re-enabled it which is perfect and we saved our code so let's put in our test employee 3 and let's hit run and there it goes says enable is true now so let's go ahead and let's refresh and we see that it is enabled so we have all of our six API routes created so already when you already have all of these you are fully able to actually go ahead create a module with commandlets that use these API endpoints you can create your own custom HTML CSS and javascrip application you can create your own C application you can use any programming languages that let you interact with apis and use these apis to be able to manipulate your active directory users which is fantastic because some programming languages make it very hard to work with active directory users but in this case we're using Powershell as our backend exposing our API to where any programming languages can really interact with it and we're going to be using this in the next couple videos when we're building out our project for our help desk using these apis in the user user interfaces section of Powershell Universal to make it a lot simpler for us so you have all the API routes created we've created a bunch of different API routes bunch of different functions go ahead run those if you haven't checked out this series on Powershell Universal I highly recommend you check that out cuz it's going to give you a good base especially on creating the guey but also seeing a bit more of the API endpoints seeing how to add authentication to the endpoints if you wanted to add authentication to them as well um but also give you a way how to run them in Visual Studio code as well just to test it out just see how it actually works directly from code and be able to just see kind of what we're about to do cuz it has a lot of examples that we're going to be using if you want to add anything to this project please comment down below I'll try to add the features that you guys want us to add um into this or if you guys have another project idea that we can make with Powershell Universal maybe you yourself have created a tool in Powershell Universal and would like to share the idea out and maybe see what we create um for that same tool that could be easily something that we can do as well please be sure to also hit that subscribe button hit that like button also hit that notification Bell to be notified when that next video comes out cuz that next video will be the next part in this project series and I will see you guys on the next video

Channel: JackedProgrammer

Views: 1,050

Keywords: powershell basics, powershell, windows powershell, programming, scripting, powershell scripting, powershell scripting tutorial, powershell tutorial, powershell api responses, powershell automation, powershell beginners, powershell variables, learn powershell, powershell commands for beginners, automation, powershell ad, dashboard, powershell dashboard, powershell universal, ironman software, powershell script to install software, rest api, gui, powershell gui, powershell web app

Id: dSaUHV0tUT0

Length: 47min 33sec (2853 seconds)

Published: Mon Apr 15 2024