x
Wyn Enterprise 3.6 is now available! See what’s new Wyn Enterprise 3.6 is now available! See what’s new Wyn Enterprise 3.6!

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 Visual Studio project. Create a new project and name it 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 following interfaces:

    • ISecurityProviderFactory
    • ISecurityProvider
    • IExternalUserDescriptor
    • IExternalUserContext

    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

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

    to your local machine (for example, to C:\temp\pkg).

  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 ... 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.
  11. Add the following code to implement the ISecurityProviderFactory interface.

    Paste it to replace the default stub in the class

    public class MySecurityProviderFactory: ISecurityProviderFactory
    {
        public string ProviderName => Consts.ProviderName;
        public string Description => Consts.Description;
        public IEnumerable SupportedSettings => Enumerable.Empty();
        public Task<ISecurityProvider > CreateAsync(IEnumerable<ConfigurationItem> settings)
        {
            return Task.FromResult(new MySecurityProvider(settings));
        }
    }
    

    ISecurityProviderFactory Attributes and Methods

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.

  1. To implement the ISecurityProvider interface, add a new class file and name it MySecurityProvider.cs.
  2. Add the following code to implement the ISecurityProvider interface.

    Paste it to replace the default stub in the class

    public interface ISecurityProvider
    {
        string ProviderName { get; }
        Task DisposeTokenAsync(string token);
        Task GenerateTokenAsync(string username, string password, object customizedParam = null);
        Task GetUserContextAsync(string token);
        Task GetUserDescriptorAsync(string token);
        Task GetUserOrganizationsAsync(string token);
        Task GetUserRolesAsync(string token);
        Task ValidateTokenAsync(string token);
    }  
    

    ISecurityProvider Attributes and Methods

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 user name and password are valid and returns a unique token if valid; otherwise returns a null or empty string. Note that 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.
  1. To implement the IExternalUserDescriptor interface, add a new class and name it ExternalUserDescriptor.cs.
  2. Add the following code.

    public interface IExternalUserDescriptor
    {
        string ExternalUserId { get; }
        string ExternalUserName { get; }
        string ExternalProvider { get; }
    }
    

    IExternalUserDescriptor Attributes

Name Description
ExternalUserId The unique identifier of the user.
ExternalUserName The user name.
ExternalUserId The name of the security provider.
  1. To implement the IExternalUserContext interface, add a new class and name it ExternalUserContext.cs.
  2. Add the following code.

    public interface IExternalUserContext
    {
        IEnumerable Keys { get; }
        Task GetValueAsync(string key);
        Task> GetValuesAsync(string key);
    }
    

    IExternalUserContext Attributes and Methods

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.

  1. Press F6 to build the solution. After the custom security provider library is built, you can configure it in the Wyn Enterprise Admin Portal.