# Device Identity Provider

`IDeviceIdentityProviderService` in assembly SanteDB.Core.Api version 3.0.1980.0

## Summary

Represents a service which retrieves [IDeviceIdentity](http://santesuite.org/assets/doc/net/html/T_SanteDB_Core_Security_Principal_IDeviceIdentity.htm) and can authenticate to an [IPrincipal](https://docs.microsoft.com/en-us/dotnet/api/system.security.principal.iprincipal) for devices.

### Description

In SanteDB, a security session is comprised of up to three security identities/principals:

* (Optional) User identity representing the human using the application
* (Optional) A [IDeviceIdentity](http://santesuite.org/assets/doc/net/html/T_SanteDB_Core_Security_Principal_IDeviceIdentity.htm) representing the device running the application, and
* An [IApplicationIdentity](http://santesuite.org/assets/doc/net/html/T_SanteDB_Core_Security_Principal_IApplicationIdentity.htm) representing the application

This service is what is used to authenticate the device identity from a central credential store of registered devices. This service may be called with a shared device id/secret (like a user name and password), or may be called with a device ID and x509 certificate (if used for authenticating sessions with a client certificate)

See: [SanteDB authentication architecture](https://help.santesuite.org/santedb/security-architecture#principals-and-identities)

## Events

| Event          | Type                                   | Description                                          |
| -------------- | -------------------------------------- | ---------------------------------------------------- |
| Authenticated  | EventHandler\<AuthenticatedEventArgs>  | Fired after an authentication request has been made. |
| Authenticating | EventHandler\<AuthenticatingEventArgs> | Fired prior to an authentication request being made. |

## Operations

| Operation      | Response/Return      | Input/Parameter                                                                                                                                                                                        | Description                                       |
| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| Authenticate   | IPrincipal           | <p><em>String</em> <strong>deviceName</strong><br><em>String</em> <strong>deviceSecret</strong><br><em>AuthenticationMethod</em> <strong>authMethod</strong></p>                                       | Authenticates the specified device identifier.    |
| CreateIdentity | IDeviceIdentity      | <p><em>String</em> <strong>deviceName</strong><br><em>String</em> <strong>secret</strong><br><em>IPrincipal</em> <strong>principal</strong><br><em>Nullable\<Guid></em> <strong>withSid</strong></p>   | Create a basic identity in the provider           |
| GetSid         | Guid                 | *String* **deviceName**                                                                                                                                                                                | Gets the SID for the specified identity           |
| GetIdentity    | IDeviceIdentity      | *String* **deviceName**                                                                                                                                                                                | Gets the specified identity for an device.        |
| GetIdentity    | IDeviceIdentity      | *Guid* **sid**                                                                                                                                                                                         | Gets the specified identity for an device.        |
| SetLockout     | void                 | <p><em>String</em> <strong>deviceName</strong><br><em>Boolean</em> <strong>lockoutState</strong><br><em>IPrincipal</em> <strong>principal</strong></p>                                                 | Set the lockout status                            |
| ChangeSecret   | void                 | <p><em>String</em> <strong>deviceName</strong><br><em>String</em> <strong>deviceSecret</strong><br><em>IPrincipal</em> <strong>principal</strong></p>                                                  | Change the device secret                          |
| AddClaim       | void                 | <p><em>String</em> <strong>deviceName</strong><br><em>IClaim</em> <strong>claim</strong><br><em>IPrincipal</em> <strong>principal</strong><br><em>Nullable\<TimeSpan></em> <strong>expiry</strong></p> | Add a to                                          |
| GetClaims      | IEnumerable\<IClaim> | *String* **deviceName**                                                                                                                                                                                | Get all active claims for the specified device    |
| RemoveClaim    | void                 | <p><em>String</em> <strong>deviceName</strong><br><em>String</em> <strong>claimType</strong><br><em>IPrincipal</em> <strong>principal</strong></p>                                                     | Removes a claim from the specified device account |

## Implementations

### UpstreamDeviceIdentityProvider - (SanteDB.Client)

Represents an identity provider that provides upstream device identities

#### Description

This is a partial implementation only for the resolution of identity objects

#### Service Registration

```markup
...
<section xsi:type="ApplicationServiceContextConfigurationSection" threadPoolSize="4">
	<serviceProviders>
		...
		<add type="SanteDB.Client.Upstream.Security.UpstreamDeviceIdentityProvider, SanteDB.Client, Version=3.0.1980.0, Culture=neutral, PublicKeyToken=null" />
		...
	</serviceProviders>
```

### AdoDeviceIdentityProvider - (SanteDB.Persistence.Data)

An implementation of the device identity provider

#### Service Registration

```markup
...
<section xsi:type="ApplicationServiceContextConfigurationSection" threadPoolSize="4">
	<serviceProviders>
		...
		<add type="SanteDB.Persistence.Data.Services.AdoDeviceIdentityProvider, SanteDB.Persistence.Data, Version=3.0.1980.0, Culture=neutral, PublicKeyToken=null" />
		...
	</serviceProviders>
```

## Example Implementation

```csharp
/// Example Implementation
using SanteDB.Core.Security.Services;
/// Other usings here
public class MyDeviceIdentityProviderService : SanteDB.Core.Security.Services.IDeviceIdentityProviderService { 
	public String ServiceName => "My own IDeviceIdentityProviderService service";
	/// <summary>
	/// Fired after an authentication request has been made.
	/// </summary>
	public event EventHandler<AuthenticatedEventArgs> Authenticated;
	/// <summary>
	/// Fired prior to an authentication request being made.
	/// </summary>
	public event EventHandler<AuthenticatingEventArgs> Authenticating;
	/// <summary>
	/// Authenticates the specified device identifier.
	/// </summary>
	public IPrincipal Authenticate(String deviceName,String deviceSecret,AuthenticationMethod authMethod){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Create a basic identity in the provider
	/// </summary>
	public IDeviceIdentity CreateIdentity(String deviceName,String secret,IPrincipal principal,Nullable<Guid> withSid){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Gets the SID for the specified identity
	/// </summary>
	public Guid GetSid(String deviceName){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Gets the specified identity for an device.
	/// </summary>
	public IDeviceIdentity GetIdentity(String deviceName){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Gets the specified identity for an device.
	/// </summary>
	public IDeviceIdentity GetIdentity(Guid sid){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Set the lockout status
	/// </summary>
	public void SetLockout(String deviceName,Boolean lockoutState,IPrincipal principal){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Change the device secret
	/// </summary>
	public void ChangeSecret(String deviceName,String deviceSecret,IPrincipal principal){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Add a  to
	/// </summary>
	public void AddClaim(String deviceName,IClaim claim,IPrincipal principal,Nullable<TimeSpan> expiry){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Get all active claims for the specified device
	/// </summary>
	public IEnumerable<IClaim> GetClaims(String deviceName){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Removes a claim from the specified device account
	/// </summary>
	public void RemoveClaim(String deviceName,String claimType,IPrincipal principal){
		throw new System.NotImplementedException();
	}
}
```

## References

* [IDeviceIdentityProviderService C# Documentation](http://santesuite.org/assets/doc/net/html/T_SanteDB_Core_Security_Services_IDeviceIdentityProviderService.htm)
* [UpstreamDeviceIdentityProvider C# Documentation](http://santesuite.org/assets/doc/net/html/T_SanteDB_Client_Upstream_Security_UpstreamDeviceIdentityProvider.htm)
* [AdoDeviceIdentityProvider C# Documentation](http://santesuite.org/assets/doc/net/html/T_SanteDB_Persistence_Data_Services_AdoDeviceIdentityProvider.htm)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.santesuite.org/developers/server-plugins/implementing-.net-features/service-definitions/device-identity-provider.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
