Package: pysafeguard
PySafeguardOne Identity Safeguard Python SDKCheck out oursample projectsto get started with your own custom integration to Safeguard!SupportOne Identity open source projects are supported throughOne Identity GitHub issuesand theOne Identity Community. This includes all scripts, plugins, SDKs, modules, code snippets or other solutions. For assistance with any One Identity GitHub project, please raise a new Issue on theOne Identity GitHub projectpage. You may also visit theOne Identity Communityto ask questions.  Requests for assistance made through official One Identity Support will be referred back to GitHub and the One Identity Community forums where those requests can benefit all users.IntroductionAll functionality in Safeguard is available via the Safeguard API. There is
nothing that can be done in the Safeguard UI that cannot also be performed
using the Safeguard API programmatically.PySafeguard is provided to facilitate calling the Safeguard API from Python.
It is meant to remove the complexity of dealing with authentication via
Safeguard's embedded secure token service (STS). The basic usage is to call
one of theconnect_*()methods to establish a connection to Safeguard, then
you can callinvoke()multiple times using the same authenticated connection.PySafeguard also provides an easy way to call Safeguard A2A from Python. The A2A service requires client certificate authentication for retrieving passwords for application integration. When Safeguard A2A is properly configured, specified passwords can be retrieved with a single method call without requiring access request workflow approvals. Safeguard A2A is protected by API keys and IP restrictions in addition to client certificate authentication.PySafeguard includes an SDK for listening to Safeguard's powerful, real-time event notification system. Safeguard provides role-based event notifications via SignalR to subscribed clients. If a Safeguard user is an Asset Administrator events related to the creation, modification, or deletion of Assets and Asset Accounts will be sent to that user. When used with a certificate user, this provides an opportunity for reacting programmatically to any data modification in Safeguard. Events are also supported for access request workflow and for A2A password changes.InstallationThis Python module is published to thePyPi registryto make it as easy as possible to install.>pipinstallpysafeguardDependenciespysafeguard uses the python requests module, which will need to be installed prior to using pysafeguard>pipinstallrequestsIn addition if you will be using the SignalR functionality you will need to install SignalR Core client module.  SignalR Core client is only required if using the SignalR functionality>pipinstallsignalrcoreCommunicating securely with Safeguard using the SDKWhen using the SDK to communicate with Safeguard, all communication will
be done using HTTPS.  To keep the communication secure, all certificates
used to secure Safeguard's API should be configured on the system where
the SDK is used.  How this is accomplished varies on each system,
however, here are some tips that can help get started.If the system is already properly configured, the SDK should work
without any errors.  If there are errors, consider using one of the
following methods to establish trust.Environment variable providing path to certificatesIn Bourne Shell:$exportWEBSOCKET_CLIENT_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
$exportREQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crtIn PowerShell:>$env:WEBSOCKET_CLIENT_CA_BUNDLE="c:\ssl\certs\ca-certificates.crt">$env:REQUESTS_CA_BUNDLE="c:ssl\certs\ca-certificates.crt"Use theverifyoption when creating thePySafeguardConnectionSee examples below for utilizing this method.  Whileverifycan be
used to disable security checking this is not recommended.NoteThe WEBSOCKET_CLIENT_CA_BUNDLE environment variable is only necessary
when working with SignalR.Getting StartedA simple code example for calling the Safeguard API with username and password authentication through the local Safeguard STS:frompysafeguardimport*connection=PySafeguardConnection('safeguard.sample.corp','ssl/pathtoca.pem')connection.connect_password('Admin','Admin123')me=connection.invoke(HttpMethods.GET,Services.CORE,'Me',query=dict(fields='DisplayName'))print('Connected to Safeguard as%s'%me.json()['DisplayName'])Password authentication to an external provider is as follows:
(Sample can be foundhere.)frompysafeguardimport*connection=PySafeguardConnection('safeguard.sample.corp','ssl/pathtoca.pem')connection.connect_password('Admin','Admin123','myexternalprovider')Client certificate authentication is also available. This can be done using PEM and KEY file.frompysafeguardimport*connection=PySafeguardConnection('safeguard.sample.corp','ssl/pathtoca.pem')connection.connect_certificate('ssl/pathtocertuser.pem','ssl/pathtocertuser.key')NotePassword protected certificates are not currently supported in PySafeguard.Client certificate authentication to an external provider is also available. This can be done using PEM and KEY file.frompysafeguardimport*connection=PySafeguardConnection('safeguard.sample.corp','ssl/pathtoca.pem')connection.connect_certificate('ssl/pathtocertuser.pem','ssl/pathtocertuser.key','myexternalprovider')A connection can also be made anonymously and without verifying the appliance certificate.frompysafeguardimport*connection=PySafeguardConnection('safeguard.sample.corp',False)system_time=connection.invoke(HttpMethods.GET,Services.APPLIANCE,'SystemTime')Authentication is also possible using an existing Safeguard API token:frompysafeguardimport*connection=PySafeguardConnection('safeguard.sample.corp','ssl/pathtoca.pem')connection.connect_token(myApiToken)NoteTwo-factor authentication is not currently supported in PySafeguard.Getting Started With A2AOnce you have configured your A2A registration in Safeguard you can retrieve an A2A password or private key using a certificate and api key.To retrieve a password via A2A:frompysafeguardimport*password=PySafeguardConnection.a2a_get_credential('safeguard.sample.corp','myapikey','ssl/pathtocertuser.pem','ssl/pathtocertuser.key','ssl/pathtoca.pem')To retrieve a private key in OpenSSH format via A2A:frompysafeguardimport*privatekey=PySafeguardConnection.a2a_get_credential('safeguard.sample.corp','myapikey','ssl/pathtocertuser.pem','ssl/pathtocertuser.key','ssl/pathtoca.pem',A2ATypes.PRIVATEKEY)About the Safeguard APIThe Safeguard API is a REST-based Web API. Safeguard API endpoints are called
using HTTP operators and JSON (or XML) requests and responses. The Safeguard API
is documented using Swagger. You may use Swagger UI to call the API directly or
to read the documentation about URLs, parameters, and payloads.To access the Swagger UI use a browser to navigate to:https://<address>/service/<service>/swagger<address>= Safeguard network address<service>= Safeguard service to useThe Safeguard API is made up of multiple services: core, appliance, notification,
and a2a.ServiceDescriptioncoreMost product functionality is found here. All cluster-wide operations: access request workflow, asset management, policy management, etc.applianceAppliance specific operations, such as setting IP address, maintenance, backups, support bundles, appliance managementnotificationAnonymous, unauthenticated operations. This service is available even when the appliance isn't fully onlinea2aApplication integration specific operations. Fetching passwords, making access requests on behalf of users, etc.Each of these services provides a separate Swagger endpoint.You may use theAuthorizebutton at the top of the screen to get an API token
to call the Safeguard API directly using Swagger.ExamplesMost functionality is in the core service as mentioned above.  The notification service
provides read-only information for status, etc.Anonymous Call for Safeguard StatusSample can be foundhere.frompysafeguardimport*connection=PySafeguardConnection('safeguard.sample.corp',False)result=connection.invoke(HttpMethods.GET,Services.NOTIFICATION,'Status')print(json.dumps(result.json(),indent=2,sort_keys=True))Get remaining access token lifetimeSample can be foundhere.frompysafeguardimport*connection=PySafeguardConnection('safeguard.sample.corp','ssl/pathtoca.pem')connection.connect_password('username','password')minutes_left=connection.get_remaining_token_lifetime()print(minutes_left)Register for SignalR eventsTo use the SignalR functionality, you will need to install the python SignalR Core client module>pipinstallsignalrcoreSample can be foundhere.frompysafeguardimport*connection=PySafeguardConnection(hostName,caFile)# SignalR callback function to handle the signalR messagesdefsignalrcallback(results):print("Received SignalR event:{0}".format(results[0]['Message']))print("Connecting to SignalR via username/password")connection.register_signalr_username(connection,signalrcallback,userName,password)print("Connecting to SignalR via certifacte")connection.register_signalr_certificate(connection,signalrcallback,userCertFile,userKeyFile)NotePassword protected certificates are not currently supported in PySafeguard.Create a New User and Set the PasswordSample can be foundhere.frompysafeguardimport*importjsonuser={'PrimaryAuthenticationProvider':{'Id':-1},'Name':'MyNewUser'}password='MyNewUser123'connection=PySafeguardConnection('safeguard.sample.corp','ssl/pathtoca.pem')connection.connect_password('username','password')result=connection.invoke(HttpMethods.POST,Services.CORE,'Users',body=user).json()userId=result.get('Id')connection.invoke(HttpMethods.PUT,Services.CORE,f'Users/{userId}/Password',body=password)