Create a Custom Security Provider
A custom security provider is a compiled DLL file that implements the interfaces specified by Wyn Enterprise. It provides access to your users so that they can log in with their existing user names and passwords and so that you can use existing groups to provide access to specific data.
To create a custom security provider
Start Visual Studio 2019.
In the Create a New Project dialog, choose Class Library (.NET Standard) template and then select Next.
In the Configure your new project dialog that appears, enter the project name and its location, and then click Create.
Right-click the Dependencies node under the Solution Explorer and select Manage Nuget Packages.
The interface implemented by the custom security provider is defined by several packages, so you need to add the following package dependencies in the project.
GrapeCity.Enterprise.Identity.SecurityProvider
GrapeCity.Enterprise.Identity.ExternalIdentityProvider
Browse the above package dependencies in the Nuget Package Manager dialog, and then select Install.
To implement the ISecurityProviderFactory, add a new class file and name it MySecurityProviderFactory.cs. This interface specifies two properties and one method:
Public string Description // Description string of this security provider.
Public string ProviderName // Name of this security provider
Public IEnumerable SupportedSettings // User configuration items supported by this security provider.
Implement the following function to create your security provider instance.
public Task<ISecurityProvider> CreateAsync(IEnumerable<ConfigurationItem> settings, ILogger logger) { return Task.FromResult<ISecurityProvider>(new MySecurityProvider(settings)); }
Implement the ISecurityProvider interface. There are interfaces such as IExternalUserDescriptor and IExternalUserContext. These interfaces only specify the attributes of the entity class, and these interfaces can be implemented using a custom class. For a detailed description of the interface, please refer ISecurityProvider Interface.
Note : In the implementation function of each interface, you must use the try-catch exception handling, where the exception handling part of catch must return the Task object. For example:return Task.FromResult<T>(null );
where T is a type, specified by the interface function.
Press F6 to build the solution. After the custom security provider library is built, you can configure the provider in the Wyn Enterprise Admin Portal. For more information about Security Providers, visit this topic.
Find the complete custom provider sample with SQL database on GitHub.
Interface Introduction
For a detailed description of the interfaces, refer to the tables below that lists the attributes and methods of an interface along with its description.
ISecurityProviderFactory Interface
Interface Definition
public interface ISecurityProviderFactory
{
string ProviderName { get; }
string Description { get; }
IEnumerable<ConfigurationItem> SupportedSettings { get; }
Task<ISecurityProvider> CreateAsync(IEnumerable<ConfigurationItem> settings);
}
Interface Description
Name | Description |
---|---|
ProviderName | The name of the security provider cannot be empty and cannot duplicate other security providers. |
Description | The description of the provider, it can be empty. |
SupportedSettings | The configuration items necessary for the security provider to load and run. For example, if the security provider needs to access the database, then the database connection string is a required configuration item, which must be configured by the administrator on the security provider management page for the security provider to work properly. You can return an empty list without any necessary configuration items. |
CreateAsync | Create an instance of a security provider. The parameter settings is a list of configuration items that the administrator has configured. The user can pass the configuration item list to the constructed security provider instance through the constructor. |
Note : These configuration items are displayed in the Admin portal, allowing the system administrator to do some configurations. A typical configuration item is the connection string to the user information database. By providing such configuration item, you avoid hard-coding in your security provider.
ISecurityProvider Interface
Interface Definition
public interface ISecurityProvider
{
string ProviderName { get; }
Task DisposeTokenAsync(string token);
Task<string> GenerateTokenAsync(string username, string password, object customizedParam = null);
Task<IExternalUserContext> GetUserContextAsync(string token);
Task<IExternalUserDescriptor> GetUserDescriptorAsync(string token);
Task<string[]> GetUserOrganizationsAsync(string token);
Task<string[]> GetUserRolesAsync(string token);
Task<bool> ValidateTokenAsync(string token);
}
Interface Description
Name | Description |
---|---|
ProviderName | The name of the security provider cannot be empty and cannot duplicate other security providers. |
DisposeTokenAsync | Make the given token invalid. |
GenerateTokenAsync | Determines whether the given username and password are valid, and will return a unique token if valid; otherwise will returns a null or an empty string. The token can be in any form, such as the user's id, or the encrypted string of the user information, as long as the security provider can correctly return the relevant information of the user based on the token. |
GetUserContextAsync | Get the user's context information using the given token. |
GetUserDescriptor | Get the basic information of the user with the given token. The basic information, including the user's id, user name, and security provider name, cannot be empty. |
GetUserOrganizationsAsync | Use the given token to get the user's department information. |
GetUserRolesAsync | Get the user's role information using the given token. Returns the name of the user's role. The names of these roles need to match the role names listed in the admin portal, otherwise they will be ignored. |
ValidateTokenAsync | Verify that the given token is valid and provided by the security provider. |
IExternalUserDescriptor Interface
Interface Definition
public interface IExternalUserDescriptor
{
string ExternalUserId { get; }
string ExternalUserName { get; }
string ExternalProvider { get; }
}
Interface Description
Name | Description |
---|---|
ExternalUserId | The unique identifier of the user. |
ExternalUserName | The user name. |
ExternalProvider | The name of the security provider. |
IExternalUserContext Interface
Interface Definition
public interface IExternalUserContext
{
IEnumerable<string> Keys { get; }
Task<string> GetValueAsync(string key);
Task<IEnumerable<string>> GetValuesAsync(string key);
}
Interface Description
Name | Description |
---|---|
Keys | The item contained in the user context information. |
GetValueAsync | Gets a corresponding user information for a given key. |
GetValuesAsync | Gets a corresponding user information for a given key in multi-value situations. |
Note : Do not use the following string for the user context key: sub, name, auth_time, idp, userid, email.