[MUSIC PLAYING] Welcome to this short video on Safeguard Custom Platforms. My name is Holger Weihe. And I'm working as a presets engineer at One Identity. Before we take a deeper look into custom platforms, let's have a look into the natively built-in platforms that are available in the Safeguard for Privileged Password product. At the time of recording of this video, we currently have around 50 plus supported native platforms in the Safeguard for Privileged Passwords product.
As mentioned, these are already built in. So they are integral part of the product. And of course they are officially supported by One Identity. The current list of available platforms is usually documented in the admin guide or the release notes. Of course, we are adding more and more built-in platforms from release to release. So please check out these types of documentation to see what is currently in your product.
So let's have a look into these Safeguard Custom Platforms. Safeguard Custom Platforms are also a built-in platform. But this is more or less a generic type that you can extend. And to extend this platform, or this custom platform type, you need to write some kind of JSON file.
In this JSON file, you're going to specify how to communicate with your target system, how to trigger various actions, and so on, and so on. And to describe these actions and functions and various things in your JSON file, you need to use some kind of programming language.
And the programming language we are using is something that is invented by One Identity. And it is a restricted set compared to fully blown programming languages. So it is just restricted to the things we need to communicate to end-systems, do a couple of actions, and so on, and so on.
To use these custom platforms, you simply load them after you have written them into the product. And then you can use it via the management interface or via the API. It doesn't matter. And of course, they need to communicate with your target system. So we offer various transports, like SSH, Telnet, or HTTP, HTTPS transports.
And the documentation, how to write these scripts-- or sometimes they are called modules as well. --and how to write them, and how to use them, and how they are structured, and what kind of functionality they offer, this is all documented in our GitHub site, github.com/oneidentity/safeguardcustomplatform.
And this is now the website we're going to have a look on. We now have used the browser to access that URL, https://github.com/oneidentity/safeguardcustomplatform. And that's how it looks like.
So you see this area of patent files, sample files, and a couple of information. But the important thing is a little bit in the middle of that screen that says, check out our wiki documentation to get started with your own custom integration to Safeguard. And that's exactly what we will do now.
So let's click on that link. And this will take you to the wiki page that contains the complete configuration documentation, how to write custom platform scripts or custom platform modules. The first thing you need to understand is about the structure of a custom platform script. This is essential, because this gives you the framework, and then once you have understood the framework, you simply need to fill it up with the required information.
So let's have a look on the structure. The first thing you're going to need is something that's called a script object. That is more or less something that is used to describe your file, especially for a couple of information that are used to represent that script in the user interface, and Safeguard, and various other things.
One of the things here is that, for instance, you have this ID. And the ID is just an identification tech that you give it. And the next thing that you need is the back end. The back end is currently only scriptable-- or the value of backend is scriptable. That's the only thing that's currently supported. There might be other things in the future. But at current time, this is only called scriptable.
Then you specify some meta date, like who's the author, what's the version, what's the latest update, and so on, and so on. And then there is the important part following now. It's about the operations. So a custom platform script needs to implement a couple of operations.
And the operations that are supported via this framework, they are listed here on that page. So you have obvious things like check system. That is used to check if you can connect to your remote system. There is checked password.
That's the usual thing you have in Safeguard for Privileged Passwords when you are clicking the appropriate entry in the user interface to trigger a password check or verify, so that you want to compare the value of the current internally stored password what is currently on your end system to see if this is all in sync.
Of course, you can trigger something like a changed password or a password change. You can handle and discover, for instance, SSH key. And you can have maybe something like account enabling and disabling functionality supported. That really depends on your end system if that's really an options that you can use in your scripts.
And of course, if you are connecting to some kind of end system, you may want to discover accounts. That might be a function that you want to implement in your custom system script or custom platform script too. And if you want to support special functionality like dependent systems, this might be implemented here in your script too.
And these are the functions that may or may not need to be filled with some kind of custom logic. It depends on your end system, on your target, what is required. Not all of these functions are required. OK. So that was the basic structure of it.
And now comes the tricky part. So let's click on that link and see this is the documentation or the guideline, how to write a script. And as I've just mentioned before, here is the list of functions of operations, to be more precise, that are usually in a script. It's the same list as more or less before.
When you want to implement such an operation-- because we are using some kind of programming language to define what is to be done and so on. We have a couple of things that you might need to as well. So if we are talking about parameters, or variables, or all these things in languages that you can use-- so you have, for instance, you can define a name.
The variable, or the parameter that this definition here talks about is the parameter needs to have a certain type, like a Boolean that's true or false. It may be an integer it may be a floating value.
It might be a string, an array, an object, a secret, an email, whatever here is supported in our language. So please check that out-- that how to define parameters, how to define variables, and how to handle this, what value they can contain, what type they have, and so on. OK.
So once this is done, Safeguard will, of course, work with these definitions. But there are a number of predefined parameters and they are managed usually by Safeguard itself. And here is the list of these predefined parameters. So there's an account DN, or an address, and asset name, change surveys, a dependent password, and so on, and so on-- so a long list of parameters that are predefined.
Of course, you cannot have the same name of the parameters in your own functions. So just keep in mind that they are predefined here, and that may or may not interfere with that. And here you have additional references to other parts of the documentation. So that you have, for instance, here the variable reference.
So if you click on that, you can simply see how this is then coded in the JSON style syntax file of your model. And what you will-- sorry-- and here you see, for instance, what is the Boolean. Then the definition here talks about scoping. Here is the naming convention, how you going to define all this, and how you resolve variables and reference these in your script later on, how you deal with strings substitutions, and so on, and so on.
There are always a little bit of examples following these various sections. So please take the time to browse to through all of these and gain some knowledge how this is really structured. You may not have to write it from scratch. You can always use some kind of existing examples that are stored here on the GitHub page as well. And then you can just simply modify and edit it to match your needs. That's easiest and maybe, of course, or the recommended way.
OK. So let's get back to our wiki. And you see there's the writing a custom script, and then we have this command reference as well. So that is the list of commands that you can use inside the module or the custom platform script. Every command that is available here, you can just simply click on it.
And then it will give you a detailed description-- how's the syntax, what are the parameters, what are the default values, are parameters required to use these commands, and so on. So that is a little bit of click and point and click and just browse through all the documentation when you are writing your first script. But once you're familiar, you may already know what to add or not to add to these types of statements there.
So after so much talking and reading on the website, let's have a look into a real script. The script you are seeing here on the screen is for the SPS, the Safeguard for Privileged Sessions, and it can be used to rotate the password of users configured inside the SPS.
So let's see how this is achieved, and how this file is structured, and how it is laid out. If we're going to see here on the screen-- you see that the first entry is on AD and back-end. That is the thing that we have just discussed when we were browsing through the structure document of the wiki article on the GitHub page of One Identity on the custom platform scripting.
So it is an ID, Safeguard for Privileged Sessions-- and the back end of course, the only one scriptable. And then you see check system, discover accounts, and a couple of more to come. These are the operations. And if you just recap this, if you go for the website again and look for the structure of the custom platform script page, you see that here are the operations.
And of course, operations is the thing that needs to be implemented, depending on your end systems capabilities. And here you have check system, and discover accounts, and everything that is here in the script as well.
So let's switch back to our script. And you see here is the check systems with the parameter blocks. Then there's the do statement. Here is discover accounts. And if we scroll down, we have the check passport operation, we have to change password operation, we have the discover host key, authorized keys, and SSH keys, and change SSH keys, and a couple of self configured functions that we are using here.
So one, for instance, here is named log in. So in log in functions, we simply set up an HTTP request that logs a user with a dedicated password into the SPS. And the method that is used is HTTP, HTTS requests. And you see there is something called get an authentication. And that will bring us into the system.
We have log in. We have log out. And we have something here like open transaction. This is, as I said, it's depending on the end system that you're talking to and however you want to write this. So open transactions usually is just initiating some kind of transactions. And the parameters that you use to call that function will give you a different transaction that is executed.
And there's a close transactions as well. And here is a function called create new password. That is just to create a new password for the password change that we want to execute. Here is something like get user ID that might be required to look for a dedicated user which password you want to change.
And a couple of SSH key handling functionality, which is in the script as well. And because the root account on the SPS is handled in a different way, there needs to be some metric here that is handling the root account in a different way. Again, this is highly specific to the end system. But it shows very nicely what you can achieve and what you may need to implement or just use standard basic functionality.
And if we further go on here, we have authorize key changes, we have fetching of SSH keys, we have update of SSH keys and settings, we have something like check response. This is just the function here in that script that is testing the response that's coming back from actions or transactions that have been executed to do some proper error handling.
And here you have an SSH log in and discovery functionality. And with that, the script is over. This is a very, very quick run through that script. And it will maybe leave more questions than answers.
But if you see these scripts that are published on our website, and you just simply go through it and try to understand what is really happening here, then you might get a very, very deep understanding how this is working, what you need to implement, and what are the required operations that you must implement to talk to the end-system of your choice.
I want to cover all this in detail, because this is a very simple thing. Once we have now discussed this script and see how the script is structured and what the logic is in it, the next question is how to implement this in Safeguard. And that's something we're going to do now.
So now we're going to implement our custom platform script into Safeguard. So let's log into Safeguard and do this little work. So log in with an administrative account. And after that, go to asset management, and Connect, and Platforms. You have two entries here-- registered connectors, that is a different kind. But we are now here interested in custom platforms.
Expand that entry. And I already have one installed in my demo system. This is just a custom platform script that is changing information in a file, maybe for configuration, settings, or something similar. That's a different story.
But with our example script that we have seen before, we simply click on Add, give it a name like SPS custom. And now we're going to browse for the platform script, our JSON file we have. I have it here.
And because this is only handled or used for password requests, and password changing, and all this kind of stuff-- it does not do any session stuff --we just leave the session requests unchecked. Simply click on OK. And now we have our new custom script or custom system defined here. Here it is.
So now we have the custom platform installed. How to go on-- The next thing we need is just to create some kind of asset of this with that custom type here. So we go to Asset. Simply click on New Asset. Give it a name. Now you have to specify the connection.
And now comes the tricky part here. The platform here is not the default one that is selected here, but it is our new SPS. So if you search for it, that is the name we gave it in our Safeguard. Version, architecture can be left blank-- no problem. And you need, of course, the address where you can reach that asset.
In my system, this is SPS dot-- because it is just in my DNS authentication type. When you remember the script, we are doing an authentication with a user and the password. The password here we're going to use for an account that is the standard admin account of the SPS. And the password we're going to use is the associated password.
And you see it is nothing special, nothing different as to create a standard asset in the usual way as any other asset type too. And now we're going to simply check on the Test Connection button.
And you see the Test Connection is succeeded. Then we simply click on OK. And now we have a new asset. We only have account here, currently. This account here is the admin account. That is the functional account. So we don't want to use that. So we need to create a new account that we can do some password rotation with.
So simply click on Plus here. That's the easiest way. You can do it via the account management as well. Let it be SPS custom user, or any other thing we'll do nicely. Go to Management. OK. SSH key is password request, whatever it is. And click on OK.
Now you have some kind of account created. The thing here is we have just created it in Safeguard SPP alone. We don't have it in SPS yet. So we now need to look into SPS to create that user. Here is my SPS.
And to create a user in SPS, go to User and Access Control. Go to Local Users. And I already have it created here. Otherwise, you simply have to create it by clicking on this plus. So I don't need to change anything here.
The password here I have doesn't care, because it is managed by Safeguard. So once this is done, I simply log out. Or maybe I'll just leave it in, just to show you something. So I'm still logged in here. So let me go back to the SPP. I now have my SPP custom user. That's the same as the one that is existing in SPS too. So I now can do something like check password.
And now you see you get an arrow. Is there something wrong with the script? Let's see. So if you click on it, it will give you the log file of that task. And if you simply check it here, it says, the current account password does not match the password on the asset. That's the one it is.
OK. So it's a different one-- nothing spectacular. Maybe I should have changed it in the past. So why not change it to a new value. So simply change the password. Ooh and another error. That's weird. OK. So let's have a look on this. And it says it has not changed. Why? Why is it here not changing the password?
So let's see what's the task log displays. OK, there's nothing special here that is displayed. But let's have a look on the operation. And you'll remember, operations are the things that are configured and implemented in this script.
And now you see a log of the operations that have been executed. So it says Change password handler, and so on, and so on. And we simply scroll down until we find maybe an error. So let's see what comes here.
And you see everything that is executed in the script is nicely logged here. So that is really good, if you implement your script, that you do some intense logging that you can see and track down errors. And you see there's an OK. And here's the transaction. Transaction was executed and created and whatever.
So let's now go down here. It takes a little time to scroll. And now you're going to see something here that says error. And it says web based or console configuration is in progress.
What does this mean? I'm already logged in with the same account of this functional account I'm using to rotate the password into the web interface in SPS. Oh, let's see. Yes, I am. I'm logged in as the admin. So I have to log out. Otherwise, the web interface will not allow that this user is logging in twice.
So let's log out. Now it's cleared. Let's go back to our SPP. Let's close that window and try to rotate the password again. OK. Change the password. And now you see it's working. Wasn't that easy? It is.
And that is how you implement custom platform scripts in Safeguard for Privileged Passwords, how you configure it in the system, and how to use it. So straightforward, very easy. Thanks for watching.
[MUSIC PLAYING]