Wyn Enterprise: 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. Create a new Class Library project in Microsoft Visual Studio 2017 and name it as MySecurityProvider.
  2. Add package dependencies. The interface implemented by the custom security provider is defined by several packages, and you need to add package dependencies. So, first you should download the following two files to your local machine (for example, to C:\temp\pkg):

    • GrapeCity.Enterprise.Identity.ExternalIdentityProvider.1.0.2.nupkg
    • GrapeCity.Enterprise.Identity.SecurityProvider.1.0.2.nupkg
  3. Implement the following interfaces:

    • ISecurityProviderFactory
    • ISecurityProvider

      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.

The above steps are elaborated as follows:

  1. Create a new Visual Studio 2017 project. Under Visual C# > .NET Standard, select Class Library (.NET Standard) and enter the project name, for example, MySecurityProvider.

  2. The interface implemented by the custom security provider is defined by several packages, and you need to add package dependencies.
    So, first, download the following two files to your local machine (for example, to C:\temp\pkg).

    • GrapeCity.Enterprise.Identity.ExternalIdentityProvider.1.0.2.nupkg

    • GrapeCity.Enterprise.Identity.SecurityProvider.1.0.2.nupkg

  3. In Visual Studio 2017, go to Tools and click NuGet Package Manager > Package Manager Settings.

  4. Under NuGet Package Manager, select Package Source and click the plus button on top of the dialog.

  5. Click the ellipses button and specify the path to the folder where the .nupkg files are located (for example, C:\temp\pkg).

  6. Click OK to save the settings.

  7. In Solution Explorer, right-click Dependencies, click Manage NuGet Packages, and then click Browse.

  8. Select the newly added package source, it will list two dependent dependencies.

  9. Select the package one by one and click Install and then OK (in the Preview Changes dialog) to add the project's dependencies on the two packages.

  10. 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 IEnumerable SupportedSettings // User configuration items supported by this security provider.

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

  1. 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.
    See Security Providers for more information.

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.