Transcript
My presentation today is going to be an overview and a demo of my custom tenant documentation tool. I'm a Cloud IGA consultant for Integral Partners and an expert ambassador in the dev community. So we've wasted enough time, so let's go ahead and get started. So quick rundown. We're going to go ahead and I'll do a little bit more introduction. We're going to talk about the real practical problem that we have to deal with. We're going to dive into the APIs, how we use them to solve our problem. And then we'll go ahead and do a demo. We'll review the output. And if we still have some time after our delay, we'll go over some of the code really quick that I can show. I'll show you guys a little bit of what it looks like. So a little bit about me. I got my computer science degree back in 2010. I thought I wanted to be a sysadmin, network admin, you know, traditional IT role. Instead here I am. I ended up pivoting to identity and I kind of never looked back and it's been great for me and my family. It's awesome. I started working with identity now back in 2019. I was a customer. We migrated away from OIM. Got my CISSP back in 2021. And again, here we are today. I've got three kids, two six-year-old twins and then our one-year-old son. One fun thing about me is I'm a Dolphins fan. Just been that way my whole life. Don't hold it against me. I was born into it. All right. So let's go ahead and dive in. There we go. Okay. Sorry about that. So the big problem we're facing here is, you know, it's all around documentation, right? It's time intensive. You either have to sit there and type everything out, do your screenshots, copy, paste. And the way that we did all this previously was in a Word document and as you can imagine that takes a lot of time and effort and manual labor. So you know, it requires manual change tracking. So anybody that's, you know, an architect, a consultant on the project, or even a client, if anybody makes any changes, then you have to keep track of all that. It's a lot of coordination and again, time and effort. So that as-built document, which is what we called it, is also quickly out of date. So anytime you build a new source, change the identity profile, anything like that, that document's now automatically out of date. So that makes it, you know, problematic, right? And the other issue we kind of run into is it's not very flexible. You know, we all know Microsoft Word. It is what it is. It's got decent formatting options, but when you're trying to do things like show your rules and your transforms and other code bits, you know, the formatting options are not great, let's be honest. Sometimes things flow onto a new page and they, and you know, the object splits up and it breaks and it's just sometimes can make things hard to read. You know, we all know documentation sucks. Let's call it what it is, but it's kind of a necessary evil, right? So that's where the APIs come into the rescue. You know, we all know that the SailPoint APIs for IdentityNow, you know, are kind of a first class citizen. IdentityNow is just a client of the API itself on the back end. So anything that we can see in the tenant in the configuration, you know, we can just pull it via API. So I said, hey, let's just take those APIs and we're going to leverage them to make my life easier. Because if I can spend more time automating what I can do, that leaves more time for the important stuff like addressing client needs and, you know, being more responsive to things that could potentially come up. So because I'm kind of Microsoft native PowerShell is what I kind of cut my teeth on and us integral partners and most of our clients are kind of Windows and Microsoft natives, that just kind of made the most sense as far as language is concerned to just keep everything in PowerShell so that, you know, it just makes sense for everybody. You know, and most of our IGA team is also on Windows. So I can hand this PS1 file to anybody on our team and they can just run it and it makes life a lot easier for everybody. And even if you have a Mac, you can run PowerShell on Mac and you can still use it. It's really cool. In what I kind of call, you know, what I kind of call the great API deprecation, I took the opportunity to kind of modularize things. I built out a lot more functions and, you know, made more code snippets and commandlets so that, you know, everything is more modular. It's easier to update and maintain and frankly actually reduce the number of lines that I use which was great. The actual PowerShell code takes the JSON output from the API response, makes it a PowerShell object and then I can take that and manipulate it just like you would with anything else. So I take it and just take that data and convert it into an HTML output so it's a really cool folder structure. We'll get into that here in a few minutes. What that kind of looks like. And so the approach that I took was excuse me. My approach was to tackle things in order of how they're listed in the tenant. So you go through the identities menu, access menu, connections, et cetera and just go in order kind of made the most sense for me in the way that I chose to approach it. So the first thing is our sources. That's kind of our elephant in the room, right? There's a lot of them. As of the time that I wrote this, there was 98 VA based direct connect sources. And there's an additional 26, again, as of this writing, there are more now, SAS based connector sources. And then this doesn't even include anything that was written custom by SailPoint professional services. Everything's there within the sources API, but then what do we do with it? How do we format it? The path that we kind of chose was to follow the flow of the user interface. Apologies, sorry. So we go through the connection settings, aggregation settings, et cetera. So we pull in the JSON, add a little pinch of CSS, a dash of HTML, and then we take the report and output it to a file. So because each sourcing connector type is unique, each one has its own custom PowerShell function, get workday, get active directory, et cetera. We chose to prioritize them based on how often we kind of see things implemented. So we see a lot of workday, we see a lot of active directory, Okta, et cetera. So we kind of took priority to the ones that made the most sense. After about 20 or so, we declared it MVP and went ahead and shipped it. It covered about 95% of our use cases. We also built out what I call an unknown source type function. So it'll output basic information like the name, the description, the source ID, et cetera, just so that we have a note of it that it exists. But then that's also a trigger to the architect on the project so that they know to open a JIRA ticket so that they can tell me or one of my peers, hey, you need to build a connector for this. All right. And so then beyond the sources, we have other module types. Everything else that is available via the API is queried. And we do that same kind of magic. So we pull in the JSON, we format it just like the sources, and then we go ahead and export the HTML-based report. Or access profiles, roles, password policies, rules, transformers, et cetera, you name it, we output it. There are some things, unfortunately, that are internal to the client network that we can't get. So we do have a few things that we manually prompt for, stuff like VA details, like do you use an internal NTP server, et cetera. One thing that we ran into while we were writing this was that some data is only available via the web browser. Those APIs aren't documented. So, again, we have to kind of prompt for a few of those things. So as a result, we found version 1 of the tooling, several endpoints, you know, ended up being deprecated. And so, again, we're kind of, you know, we're stuck prompting for a few things. It's kind of a necessary evil, right? The first benefit is all the time that we save. The script itself takes about five minutes to run. The initial draft of this thing could take a consultant, you know, six to eight hours, depending on how much work's been done. So naturally, that's kind of a lot. It's more modular, too. So it's actually designed, the original version was with a command line parameter. So you would say, you know, dash config file, and then declare your config file of where your tenant information is. This new version 2 actually implements, and I'll show this on the screen in a little bit, it's a file picker. So that I can just say, give me this JSON file, and it just runs, and it makes it a little bit more user friendly. So also, because we can, you know, iterate on this thing, it only takes a few minutes, the data's never out of date. So you can run it. It's still a point in time, right? Just like a Word document would be. But you can run it as many times as you want. So you can always have these point in time snapshots, and you can reference them. And it's sort of a diet version of code control. My kind of joke, while it's not true code control and versioning, it does give you a little bit of that snapshot, right? So you can say, okay, what did this look like a week ago when we ran this, versus what does it look like now? The other big benefit is that it's more consistent. So every single person that runs this script, you're always going to get an identical style of output every single time. It takes the human element of it out, so that you don't, you don't have any missing elements or things like that. It just makes it so that the client always gets the same information every time. Okay, as far as what's next, we're just going to keep adding source types. As the need comes up, if somebody says, hey, we have pager duty, or we have, you know, we already have service now, so that's not a good example. But DocuSign, you know, we'll add a connector type for it so that, you know, we can capture all of the information. We're also going to implement changelogs so that we can, you know, see, okay, these are what changed between the two, you know, the two versions. So that that way we can say, okay, if something changed, and it was a regression, or something broke, we can highlight what those changes are, so that we can, we could, you know, do a rollback of those changes. And the other thing that we're looking into is doing JSON exports, so that you could do true code control and store all of those objects in, say, GitHub, or GitLab, or what have you, and do actual code control and versioning and such on it. Okay. All right. So let's go ahead and take a look at it, then. We'll go ahead and open up a terminal window, and we're going to launch my backup launcher. And we're going to grab this partner config right here. So one thing that we did with this, too, is we added the option to add a session token from the browser, so that that way during the pre-sales process, we could get a snapshot, so that that way we can, you know, have a temporary credential, so that we could do this to get a snapshot of what a client environment looks like as well, without actually having to have credentials established in the tenant. All right. So as you can see here, so it's kind of running through everything. It gives you kind of a status as to what it's doing. We have the identity profiles. We're getting roles. And so now what it's doing is it's going to iterate through our v3 sources API and list everything out and start running through, and you can see that it's grabbing everything. And perfect example here, so we don't have the intra-SaaS connector type set up yet. So you can see here, so it says, intra-ID not yet fully supported, launching undefined source documenter. So again, you know, we'll take a look at that one in the report structure. So it's just, again, it's a flag to the consultant to say, hey, go build a, you know, a connector for this one. All right. There we go. So we are almost done with our sources here, and you can see that we're pulling transforms and rules. I'll show you what those look like here too. So the rules is a little bit unique. In the old CC API, you used to be able to get your cloud-executed rules through that endpoint. Since that was deprecated, we have to use SP config to get those, so that one does take a little bit longer to process, unfortunately. So we'll pull down all of our tenant settings, our security settings. So this is what I was alluding to earlier, manual input. You know, we can't pull the API what the service account name is for the VA if you changed it. We left this one as the default, so we'll just hit enter to accept that. Are we using an internal NTP server, yes or no? Is this using a secure tunnel or a proxy, yes or no? So we'll leave that as the default. Is file upload utility, again, that's an internal item, so we have to kind of, you know, input all of that by hand, unfortunately. So we're going to skip past that. We don't have IQ service details available right now, so we're going to just skip past that too. Then we're going to pull down everything else. We're going to build a table of contents, and there we go. So go ahead and pull this up, and you can see we have our nice little folder structure here with all of our data. So we'll grab our homepage, and there we go. So that's what this looks like. So you get your table of contents here, so we'll pick on Active Directory. So this would be then everything that you need to take this source and set it back up from scratch should you not have an SP config export or something to that regard. But you can also hand this over to, say, like your management types or somebody like that that wants to do a manual review of all of your settings, that they want to see all of this, including even a human-readable copy of your aggregation schedules. So we have the account schema. This one doesn't have a create profile set up, so we don't have that, but if a source did have a create profile configured, then it would pull that in as well. If we look at, let's say, our roles, so we have all of that information, too. We can see the approvers. Where's one with our criteria? I thought I had one with criteria. So the role criteria would be in here, too, if we had any that were not an identity list. So let's go access profiles. Again, you can see all of that, too, so you can see your reviewers and such. So everything's there that you would need to hand this over at the end of a project. All right, so that is everything I've got. Thank you, everybody, for coming. Have a great rest of the day.
