[]
        
(Showing Draft Content)

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

  1. Start Visual Studio 2019.

  2. In the Create a New Project dialog, choose Class Library (.NET Standard) template and then select Next.


    Create a New Project Dialog

  3. In the Configure your new project dialog that appears, enter the project name and its location, and then click Create.


    Configure your new project dialog

  4. Right-click the Dependencies node under the Solution Explorer and select Manage Nuget Packages.


    Manage Nuget Package


    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

  5. Browse the above package dependencies in the Nuget Package Manager dialog, and then select Install.


    Installing Package Dependenices

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

  7. 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));
    }
  8. 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.

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