# Application Identity Provider

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

## Summary

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

### 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) Device identity 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 application identity from a central credential store of registered applications.

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>applicationName</strong><br><em>String</em> <strong>applicationSecret</strong></p>                                                                                               | Authenticate the application identity.              |
| Authenticate   | IPrincipal           | <p><em>String</em> <strong>applicationName</strong><br><em>IPrincipal</em> <strong>authenticationContext</strong></p>                                                                                       | Authenticate the application identity.              |
| CreateIdentity | IApplicationIdentity | <p><em>String</em> <strong>applicationName</strong><br><em>String</em> <strong>password</strong><br><em>IPrincipal</em> <strong>principal</strong><br><em>Nullable\<Guid></em> <strong>withSid</strong></p> | Create a basic identity in the provider             |
| GetIdentity    | IApplicationIdentity | *String* **applicationName**                                                                                                                                                                                | Gets the specified identity for an application.     |
| GetIdentity    | IApplicationIdentity | *Guid* **sid**                                                                                                                                                                                              | Gets the specified identity for an application.     |
| GetSid         | Guid                 | *String* **name**                                                                                                                                                                                           | Gets the SID for the specified identity             |
| SetLockout     | void                 | <p><em>String</em> <strong>applicationName</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>applicationName</strong><br><em>String</em> <strong>secret</strong><br><em>IPrincipal</em> <strong>principal</strong></p>                                                        | Change the specified application identity's secret  |
| AddClaim       | void                 | <p><em>String</em> <strong>applicationName</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* **applicationName**                                                                                                                                                                                | Get all active claims for the specified application |
| RemoveClaim    | void                 | <p><em>String</em> <strong>applicationName</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

### BridgedApplicationIdentityProvider - (SanteDB.Client)

Application identity provider service that bridges between local and upstream

#### Service Registration

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

### UpstreamApplicationIdentityProvider - (SanteDB.Client)

Represents an implementation of a [IApplicationIdentityProviderService](http://santesuite.org/assets/doc/net/html/T_SanteDB_Core_Security_Services_IApplicationIdentityProviderService.htm) which uses OAUTH

#### Service Registration

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

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

Application identity provider that uses the database to authenticate applications

#### Service Registration

```markup
...
<section xsi:type="ApplicationServiceContextConfigurationSection" threadPoolSize="4">
	<serviceProviders>
		...
		<add type="SanteDB.Persistence.Data.Services.AdoApplicationIdentityProvider, 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 MyApplicationIdentityProviderService : SanteDB.Core.Security.Services.IApplicationIdentityProviderService { 
	public String ServiceName => "My own IApplicationIdentityProviderService 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>
	/// Authenticate the application identity.
	/// </summary>
	public IPrincipal Authenticate(String applicationName,String applicationSecret){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Authenticate the application identity.
	/// </summary>
	public IPrincipal Authenticate(String applicationName,IPrincipal authenticationContext){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Create a basic identity in the provider
	/// </summary>
	public IApplicationIdentity CreateIdentity(String applicationName,String password,IPrincipal principal,Nullable<Guid> withSid){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Gets the specified identity for an application.
	/// </summary>
	public IApplicationIdentity GetIdentity(String applicationName){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Gets the specified identity for an application.
	/// </summary>
	public IApplicationIdentity GetIdentity(Guid sid){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Gets the SID for the specified identity
	/// </summary>
	public Guid GetSid(String name){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Set the lockout status
	/// </summary>
	public void SetLockout(String applicationName,Boolean lockoutState,IPrincipal principal){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Change the specified application identity's secret
	/// </summary>
	public void ChangeSecret(String applicationName,String secret,IPrincipal principal){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Add a  to
	/// </summary>
	public void AddClaim(String applicationName,IClaim claim,IPrincipal principal,Nullable<TimeSpan> expiry){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Get all active claims for the specified application
	/// </summary>
	public IEnumerable<IClaim> GetClaims(String applicationName){
		throw new System.NotImplementedException();
	}
	/// <summary>
	/// Removes a claim from the specified device account
	/// </summary>
	public void RemoveClaim(String applicationName,String claimType,IPrincipal principal){
		throw new System.NotImplementedException();
	}
}
```

## References

* [IApplicationIdentityProviderService C# Documentation](http://santesuite.org/assets/doc/net/html/T_SanteDB_Core_Security_Services_IApplicationIdentityProviderService.htm)
* [BridgedApplicationIdentityProvider C# Documentation](http://santesuite.org/assets/doc/net/html/T_SanteDB_Client_Upstream_Security_BridgedApplicationIdentityProvider.htm)
* [UpstreamApplicationIdentityProvider C# Documentation](http://santesuite.org/assets/doc/net/html/T_SanteDB_Client_Upstream_Security_UpstreamApplicationIdentityProvider.htm)
* [AdoApplicationIdentityProvider C# Documentation](http://santesuite.org/assets/doc/net/html/T_SanteDB_Persistence_Data_Services_AdoApplicationIdentityProvider.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/application-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.