RCS.Carbon.Licensing.Example
3.1.6
See the version list below for details.
dotnet add package RCS.Carbon.Licensing.Example --version 3.1.6
NuGet\Install-Package RCS.Carbon.Licensing.Example -Version 3.1.6
<PackageReference Include="RCS.Carbon.Licensing.Example" Version="3.1.6" />
paket add RCS.Carbon.Licensing.Example --version 3.1.6
#r "nuget: RCS.Carbon.Licensing.Example, 3.1.6"
// Install RCS.Carbon.Licensing.Example as a Cake Addin #addin nuget:?package=RCS.Carbon.Licensing.Example&version=3.1.6 // Install RCS.Carbon.Licensing.Example as a Cake Tool #tool nuget:?package=RCS.Carbon.Licensing.Example&version=3.1.6
Licensing Overview
The Carbon cross-tabulation engine depends upon a licensing system to define rules for authenticating access to data.
Red Centre Software uses a proprietary licensing system when Carbon accesses jobs in Azure storage accounts hosted by Red Centre Software. A company that wishes to sever ties with Red Centre Software hosting and use Carbon to access jobs in their own Azure subscription must provide their own licensing system to the Carbon engine. A .NET class that acts as a licensing provider must implement the ILicensingProvider
interface. The full interface contains about 30 members, but a minimal working provider only needs to implement the following:
public interface ILicensingProvider : IDisposable
{
string Name { get; }
string Description { get; }
Task<LicenceFull> LoginId(string userId, string password, bool skipCache = false);
Task<LicenceFull> LoginName(string userName, string password);
Task<LicenceFull> GetFreeLicence(string clientIdentifier = null, bool skipCache = false);
Task<int> ReturnId(string userId);
Task<int> LogoutId(string userId);
}
Other unused interface members can be implemented like this:
public Task<NavData> GetNavigationData() => throw new NotImplementedException();
// etc
The other interface members are only needed if the provider wishes to be a general-purpose licensing database management plug-in to the DNA Licensing Management Tool, which will be described in an upcoming Wiki page.
Carbon recognises the following fundamental definitions of parts of a licensing provider:
User Name
A traditional sign-in (or login) name credential. The value is normally a readable string such as a person's full or partial name. The value may also be a unique readable value such as an email address.
User Id
Many licensing providers can use a database identifier (or key) as a credential. The value may often be a string of computer generated characters that are not particularly memorable. Individual licensing systems may choose to support Name or Id credentials, or both, and choose the behaviour of each one.
Password
If a licensing provider requires secure authentication then it can support assigning passwords to user Name or Id credentials. Each licensing provider will implement its own internal way of storing credentials.
Customer
Carbon equates an Azure storage account to a customer. The licensing provider must define which storage accounts represent customers.
Job
Carbon equates an Azure container to a job. The licensing provider must define which containers represent jobs.
Caching
A licensing provider may wish to support caching of licensing responses to improve performance. How this could be done is an internal detail for each licensing provider. Some of the licensing interface methods take a skipCache flag which can diasble caching if it is active by default.
Example Licence Provider
Overview
As described in the previous section, the Carbon cross-tabulation engine supports the familiar security concepts of authentication which specifies which accounts can use the engine, and authorization which specifies which features of the engine are available to them.
The Carbon engine does not internally contain any logic to perform security functions, it delegates such functions to an external library called a licensing provider. Red Centre Software uses a proprietary provider when Carbon-based applications are hosted in their Azure subscription. Developers can create a custom provider for their own applications.
This project contains a class named ExampleLicensingProvider
which uses a SQL Server database as the backing storage for account information and security permissions. The class implements a minimal fully working example of a custom licensing provider.
The following sections contain instructions on how to deploy and use the example provider. Because hosting environments and tool preferences are hard to predict accurately, the instructions are somewhat general, but should be sufficient guidance for an experienced developer to adjust to their needs.
Create Database
The SQL Server database used by the example licensing provider can be hosted in a local server instance or in an Azure hosted server. The choice is dictated by where the calling application is running and which connection is most convenient and has acceptable performance.
Local
To create a local database, the simplest option is to use SSMS (SQL Server Management Studio) to connect to a local server and create a new database using defult values and a suitable folder. Run the script in the file ExampleDatabase-Create.sql
to create the database schema and insert sample rows.
Azure
Use the Azure subscription web portal to create a SQL Server, if a suitable one doesn't exist. Create a SQL Server database named CarbonLicensingExample
in the server.
Use SSMS to connect to the Azure database and run the script in ExampleDatabase-Create.sql
to create the database schema and insert sample rows. The SSMS Server value will be in the format:
tcp:{SERVERNAME}.database.windows.net,1433
The SQL Server Authentication User Name and Password credentials are created when the Azure server is created in the portal. The connections strings are displayed in the Connection Strings blade for the database.
Developer Notes
The following sections are technical notes about how the example provider project and files were created. The commands prefixed with ▶ are run in the "Open in Terminal" window for the example provider project.
Install packages:
Microsoft.EntityFrameworkCore.SqlServer 7.0.9
Microsoft.EntityFrameworkCore.Tools 7.0.9
The installed Tools might not be the latest. Use the following command to ensure the latest is installed:
▶ dotnet tool update --global dotnet-ef
Scaffold the classes from the database:
▶ dotnet ef DbContext Scaffold "Server=tcp:{SERVERNAME}.database.windows.net,1433;Database={DATABASE};Persist Security Info=False;User ID={USER};Password={PASSWORD};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=True;Connection Timeout=30;" Microsoft.EntityFrameworkCore.SqlServer --output-dir EFCore --data-annotations --context ExampleContext --no-onconfiguring --force
The generated classes will need adjusting to have all of the recommended Data Annotation attributes. This has been done in the example project and the completed classes are in the EFCore folder of the example project.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- Azure.Storage.Blobs (>= 12.23.0)
- Microsoft.EntityFrameworkCore (>= 7.0.13)
- Microsoft.EntityFrameworkCore.SqlServer (>= 7.0.13)
- RCS.Carbon.Licensing.Shared (>= 9.1.6)
- System.Linq.Async (>= 6.0.1)
-
net8.0
- Azure.Storage.Blobs (>= 12.23.0)
- Microsoft.EntityFrameworkCore (>= 7.0.13)
- Microsoft.EntityFrameworkCore.SqlServer (>= 7.0.13)
- RCS.Carbon.Licensing.Shared (>= 9.1.6)
- System.Linq.Async (>= 6.0.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Example code by Red Centre Software https://github.com/redcentre/Carbon.Examples.Licensing.Provider/