SafeguardDotNet

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

SafeguardDotNet

(★ 14)

One Identity Safeguard Web API C# SDK

SafeguardDotNet Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Build status](https://ci.appveyor.com/api/projects/status/wgd68b7qrwhc7oc3?svg=true)](https://ci.appveyor.com/project/petrsnd/safeguarddotnet)
[![nuget](https://img.shields.io/nuget/v/OneIdentity.SafeguardDotNet.svg)](https://www.nuget.org/packages/OneIdentity.SafeguardDotNet/)
[![GitHub](https://img.shields.io/github/license/OneIdentity/SafeguardDotNet.svg)](https://github.com/OneIdentity/SafeguardDotNet/blob/master/LICENSE)

# SafeguardDotNet

One Identity Safeguard Web API C# SDK

-----------

<p align="center">
<i>Check out our <a href="Samples">sample projects</a> to get started with your own custom integration to Safeguard!</i>
</p>

-----------

## Support

One Identity open source projects are supported through [One Identity GitHub issues](https://github.com/OneIdentity/SafeguardDotNet/issues) and the [One Identity Community](https://www.oneidentity.com/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 the [One Identity GitHub project](https://github.com/OneIdentity/SafeguardDotNet/issues) page. You may also visit the [One Identity Community](https://www.oneidentity.com/community/) to 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.

## Known Issues

SafeguardDotNet 7.3

- In some cases, SignalR does not respect the certificate validation callback function or the IgnoreSsl parameter when getting a persistent or non-persistent A2A event listener.
  - When calling ```GetPersistentA2AEventListener()``` or ```GetA2AEventListener()``` with a certificate validation callback or the ```IgnoreSsl``` parameter set to 'true', SignalR fails to validate the client certificate.
  - **Workaround** - Make sure that the Safeguard for Privileged Passwords appliance SSL/TLS Certificate has been properly configured with a valid certificate and that the certificate is trusted by the client. <https://support.oneidentity.com/technical-documents/one-identity-safeguard-for-privileged-passwords/7.3/administration-guide/33#TOPIC-2015719>

## Default API Update

SafeguardDotNet will use v4 API by default starting with version 7.0. It is
possible to continue using the v3 API by passing in the apiVersion parameter
when creating a connection or A2A context.

Safeguard for Privileged Passwords 7.X hosts both the v3 and v4 APIs. New coding
projects should target the v4 API, and existing projects can be migrated over time.
Notification will be given to customers many releases in advance of any plans to
remove the v3 API. There are currently no plans to remove the v3 API.

```C#
// Use v3 instead of v4
var connection = Safeguard.Connect("safeguard.sample.corp", "local", "Admin", password, 3);
var a2aContext = Safeguard.A2A.GetContext("safeguard.sample.corp", thumbprint, 3);
```

## Introduction

All 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.

SafeguardDotNet is provided to facilitate calling the Safeguard API from .NET.
It is meant to remove the complexity of dealing with authentication via
Safeguard's embedded secure token service (STS). It also facilitates
authentication using client certificates, which is the recommended
authentication mechanism for automated processes. The basic usage is to call
`Connect()` to establish a connection to Safeguard, then you can call
`InvokeMethod()` multiple times using the same authenticated connection.

SafeguardDotNet also provides an easy way to call Safeguard A2A from .NET. 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.

SafeguardDotNet 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.

SafeguardDotNet uses `HttpClient` and `System.Text.Json` (with source-generated
serializers for trim/AOT friendliness) to call the Safeguard API. It includes
calls to Serilog, and if your calling application provides a sink you will get
log information automatically.

## Logging & diagnostics

SafeguardDotNet emits diagnostic logs through Serilog, and surfaces appliance
errors as `SafeguardDotNetException`. The exception carries an `HttpStatusCode`
and a `Response` body string that contains **whatever the Safeguard appliance
returned for the failing call** — this is intentional so that operators can
diagnose appliance-side failures without re-running the request.

Because Safeguard is a credential-management product, the SDK does **not**
inspect, filter, or redact response bodies — they may legitimately contain
fields named `Password`, `ApiKey`, `PrivateKey`, `SshHostKey`, `Token`,
`AccountPassword`, and similar, and the SDK has no safe way to distinguish
"product output the caller requested" from "metadata that happens to share a
name". In rare authentication-failure shapes the response body can also echo
submitted credentials (for example, the Resource Owner Password Credentials
grant may return the submitted username, and some appliance versions echo other
form fields in error envelopes).

**If you forward `SafeguardDotNetException.Message`,
`SafeguardDotNetException.Response`, or the rendered exception (`ex.ToString()`)
to a log sink that is less trusted than the appliance — for example a shared
SIEM, a cloud log aggregator, a support bundle, or a customer-visible error
page — redact at the log layer.** Suggested patterns:

- Log only `ex.HttpStatusCode` and `ex.ErrorCode` for production telemetry;
  keep `ex.Response` in a privileged channel (local file, restricted sink) for
  on-call diagnosis.
- If you must forward the full response, run it through your organization's
  log scrubber first (Serilog `Destructure.ByTransforming<>`, an
  `IEnumerable<ILogEventEnricher>`, or a sink-side filter) with rules tuned to
  *your* schema, not a generic substring blacklist.
- Avoid `Log.Error(ex, "...")` patterns that capture the full exception object
  when the sink is not under your control; prefer
  `Log.Error("Safeguard request failed: {Status} {Code}", ex.HttpStatusCode, ex.ErrorCode)`.

The SDK will not be changed to redact response bodies because substring
matching on field names would corrupt legitimate Safeguard fields such as
`PasswordRulesPolicyId`, `ApiKeyName`, `NewPasswordValidUntil`, etc., and
would not actually help in the cases where redaction is needed.

## Resource Owner Password Grant Deprecation

The OAuth2 Resource Owner Password Credential (ROPC) grant type — where
usernames and passwords are sent directly to the API — is disabled by default
in Safeguard and **should not be used for new integrations**. ROPC does not
support federated identity providers, multi-factor authentication, or modern
security best practices.

The `Safeguard.Connect(appliance, provider, username, password)` overload
relies on the Resource Owner grant. If the appliance has not explicitly
enabled this grant type, calls using this method will fail.

**Instead, use one of the PKCE-based authentication packages:**

All three packages use the OAuth2 Authorization Code flow with PKCE
(RFC 7636), which is the recommended approach for authenticating users.

Client certificate authentication and pre-existing API tokens are **not
affected** by this change and remain fully supported.

## Getting Started

### Browser Login (Recommended for Interactive Apps)

The simplest way to authenticate a user without relying on the Resource Owner
grant is the browser-based PKCE flow. Install the `BrowserLogin` package:

```PowerShell
PS> dotnet add package OneIdentity.SafeguardDotNet.BrowserLogin
```

```C#
using OneIdentity.SafeguardDotNet;
using OneIdentity.SafeguardDotNet.BrowserLogin;

// Opens the default browser to the Safeguard login page
var connection = DefaultBrowserLogin.Connect("safeguard.sample.corp");
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

#### Async with CancellationToken

```C#
using OneIdentity.SafeguardDotNet;
using OneIdentity.SafeguardDotNet.BrowserLogin;

// Ctrl+C cancels the login flow without terminating the process
using var cts = Safeguard.AgentBasedLoginUtils.CreateConsoleCancellationToken();
var connection = await DefaultBrowserLogin.ConnectAsync(
    "safeguard.sample.corp", ignoreSsl: true, cancellationToken: cts.Token);
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

### Device Code Login (Recommended for Headless/Remote Devices)

When there is no browser on the local machine (SSH sessions, containers, IoT
devices), use the Device Code flow. The user authenticates on a separate device:

```PowerShell
PS> dotnet add package OneIdentity.SafeguardDotNet.DeviceCodeLogin
```

```C#
using OneIdentity.SafeguardDotNet;
using OneIdentity.SafeguardDotNet.DeviceCodeLogin;

### PKCE Non-Interactive Login (Recommended for Automation)

When you need programmatic authentication without a browser (e.g. automated
tests, CI/CD pipelines, or headless environments), use the PKCE
non-interactive package:

```PowerShell
PS> dotnet add package OneIdentity.SafeguardDotNet.PkceNoninteractiveLogin
```

```C#
using OneIdentity.SafeguardDotNet;
using OneIdentity.SafeguardDotNet.PkceNoninteractiveLogin;

SecureString password = GetPasswordSomehow();
var connection = PkceNoninteractiveLogin.Connect(
    "safeguard.sample.corp", "local", "Admin", password);
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

If the identity provider requires multi-factor authentication, pass the
one-time code as a secondary password:

```C#
SecureString password = GetPasswordSomehow();
SecureString totp = GetOneTimeCodeSomehow();
var connection = PkceNoninteractiveLogin.Connect(
    "safeguard.sample.corp", "local", "Admin", password, totp);
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

#### Async with CancellationToken

```C#
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(60));
SecureString password = GetPasswordSomehow();
var connection = await PkceNoninteractiveLogin.ConnectAsync(
    "safeguard.sample.corp", "local", "Admin", password,
    ignoreSsl: true, cancellationToken: cts.Token);
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

### Username / Password (Resource Owner Grant — Legacy)

The following method relies on the Resource Owner grant, which is disabled by
default. See the [deprecation note](#resource-owner-password-grant-deprecation)
above for recommended alternatives.

```C#
SecureString password = GetPasswordSomehow(); // default password is "Admin123"
var connection = Safeguard.Connect("safeguard.sample.corp", "local", "Admin", password);
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

### Client Certificate Authentication

Certificates may be used in two different ways, either via a PFX (PKCS12) file
or using a SHA-1 thumbprint identifying a certificate in the User or Computer
personal store. Certificate authentication is **not affected** by the Resource
Owner grant deprecation.

```C#
SecureString certificatePassword = GetPasswordSomehow();
var connection = Safeguard.Connect("safeguard.sample.corp", "C:\cert.pfx", certificatePassword);
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

```C#
var connection = Safeguard.Connect("safeguard.sample.corp", "756766BB590D7FA9CA9E1971A4AE41BB9CEC82F1");
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

### Existing API Token

A final authentication method that is available is using an existing Safeguard API token.

```C#
SecureString apiToken = GetTokenSomehow();
var connection = Safeguard.Connect("safeguard.sample.corp", apiToken);
Console.WriteLine(connection.InvokeMethod(Service.Core, Method.Get, "Me"));
```

Calling the simple 'Me' endpoint provides information about the currently logged
on user.

### Visual Studio 2017

A three minute video demonstrating how to get started calling the Safeguard API from a Visual Studio 2017 project.

[Visual Studio 2017 video](https://www.youtube.com/watch?v=kK90UyOeZac)

[![Visual Studio 2017 video](https://img.youtube.com/vi/kK90UyOeZac/0.jpg)](https://www.youtube.com/watch?v=kK90UyOeZac)

### Visual Studio Code

A four minute video demonstrating how to get started calling the Safeguard API from a Visual Studio Code project.

[Visual Studio Code video](https://www.youtube.com/watch?v=gV7iHUun9kA)

[![Visual Studio Code video](https://img.youtube.com/vi/gV7iHUun9kA/0.jpg)](https://www.youtube.com/watch?v=gV7iHUun9kA)

## Migrating to Async Login (ConnectAsync)

`DefaultBrowserLogin`, `PkceNoninteractiveLogin`, and `DeviceCodeLogin` now
offer `ConnectAsync` methods with `CancellationToken` support.

**What changed in `Connect()` (sync):**

- `DefaultBrowserLogin.Connect()` no longer registers a `Console.CancelKeyPress`
  handler. The previous handler did not suppress process termination
  (`e.Cancel` was not set to `true`), so Ctrl+C already terminated the process.
  This change removes a non-functional side effect — behavior is unchanged for
  callers.

**New capability — `ConnectAsync`:**

```C#
// Option 1: Ctrl+C cancellation that suppresses process termination
using var cts = Safeguard.AgentBasedLoginUtils.CreateConsoleCancellationToken();
var connection = await DefaultBrowserLogin.ConnectAsync(
    "safeguard.example.com", ignoreSsl: true, cancellationToken: cts.Token);

// Option 2: Custom timeout
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(60));
var connection = await PkceNoninteractiveLogin.ConnectAsync(
    "safeguard.example.com", "local", "Admin", password,
    ignoreSsl: true, cancellationToken: cts.Token);
```

**Bug fix — `ignoreSsl` now honored everywhere:**

Previously, internal HTTP calls during token exchange always bypassed SSL
validation regardless of the `ignoreSsl` parameter. This is now fixed — if you
pass `ignoreSsl: false`, certificate validation is enforced for all calls.
Environments using self-signed certificates should pass `ignoreSsl: true`
explicitly.

## About the Safeguard API

The 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 use

The Safeguard API is made up of multiple services: core, appliance, notification,
and a2a.

|Service|Description|
|-|-|
|core|Most product functionality is found here. All cluster-wide operations: access request workflow, asset management, policy management, etc.|
|appliance|Appliance specific operations, such as setting IP address, maintenance, backups, support bundles, appliance management|
|notification|Anonymous, unauthenticated operations. This service is available even when the appliance isn't fully online|
|a2a|Application 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 the `Authorize` button at the top of the screen to get an API token
to call the Safeguard API directly using Swagger.

To call the a2a service you should begin by using `Safeguard.A2A.GetContext()` rather than
`Safeguard.Connect()`.

### Examples

Most functionality is in the core service as mentioned above.  The notification service
provides read-only information for status, etc.

#### Anonymous Call for Safeguard Status

```C#
var connection = Safeguard.Connect("safeguard.sample.corp");
Console.WriteLine(connection.InvokeMethod(Service.Notification, Method.Get, "Status"));
```

#### Create a New Linux Asset

```C#
using System.Text.Json;

// Assume connection is already made
var json = connection.InvokeMethod(Service.Core, Method.Post, "Assets",
    JsonSerializer.Serialize(new {
        Name = "linux.blue.vas",
        NetworkAddress = "linux.blue.vas",
        Description = "A new linux asset",
        PlatformId = 188, // Ubuntu Other
        AssetPartitionId = -1
    }));
Console.WriteLine(json);
```

#### Create a New User and Set the Password

```C#
using System.Text.Json;

// Assume connection is already made
var userJson = connection.InvokeMethod(Service.Core, Method.Post, "Users",
    JsonSerializer.Serialize(new {
        PrimaryAuthenticationProviderId = -1,
        UserName = "MyNewUser"
    }));
using var userDoc = JsonDocument.Parse(userJson);
var userId = userDoc.RootElement.GetProperty("Id").GetInt32();
connection.InvokeMethod(Service.Core, Method.Put, $"Users/{userId}/Password",
    JsonSerializer.Serialize("MyNewUser123"));
```

## Using SafeguardDotNet from a New Visual Studio Code Project

First, create a directory with the name you want to give your project and change directory into it.

Run:
```PowerShell
PS> dotnet new console
```

This will create a `console` project.  You can see other project types by running `dotnet new`.

Run:
```PowerShell
PS> dotnet add package OneIdentity.SafeguardDotNet
```

This will add the latest OneIdentity.SafeguardDotNet NuGet package into your project.

If you encounter this error:
![Visual Studio Code](https://raw.githubusercontent.com/OneIdentity/SafeguardDotNet/main/data/error401.png)

Add this file ([nuget.config](data/nuget.config)) under your project root directory and rerun the previous command.

Run:
```PowerShell
PS> dotnet restore
```

This will restore NuGet packages into your project so you can get code completion in the editor

Finally, run:
```PowerShell
PS> code .
```

This will open the Visual Studio Code editor so you can begin adding code to your project.

Add the using directive at the top of your file to call SafeguardDotNet:
```C#
using OneIdentity.SafeguardDotNet;
```

SafeguardDotNet

SafeguardDotNet Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

SafeguardDotNet

SafeguardDotNet Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README