Dangl.Icons

Configuration

In development, ensure that the AppFilesRootPath setting is configured, ideally via user secrets.

Integrated Server Configuration

If you're using the Dangl.Icons.Server NuGet package to bundle the server side features directly in your backend, please see the following configuration example. Additionally, make sure that you configure your own Dangl.AspNetCore.FileHandling.IFileManager service. By default, the identicons are saved in a container named identicons. This constant is available in Dangl.Icons.Server.IconAppDefaults.IDENTICONS_CONTAINER_NAME.

// Adds the required services for dependency injection
services.AddDanglIconsServices();

// Adds the Dangl.Icons controllers to your app
services.AddMvc().AddDanglIconsControllers();

// If you want to be able to upload icons, you must configure a Policy. It's default name
// is 'IconManagerPolicy' (see Dangl.Icons.Server.IconAppDefaults.ICON_MANAGER_POLICY_NAME)
// For example, this could be a policy configuration in your app:
services.AddAuthorization(authConfig =>
{
    authConfig.AddPolicy(IconAppDefaults.ICON_MANAGER_POLICY_NAME,
        policyBuilder => policyBuilder
            .AddRequirements(new IconManagerRequirement(iconAppConfiguration.ApiKeys)));
});

Excluding Dangl.Icons.Server

By default, ASP.NET Core MVC will add controllers discovered in all loaded assemblies at startup. If the Dangl.Icons.Server package is included in your app but you do not want to automatically load the controllers, ensure the following service call:

services.AddMvc().EnsureDanglIconsControllersAreExcluded();

Authorization

Retrieving icons is not access restricted. Icons are saved by a Guid and are accessible via /api/identicons/{iconId}.png. Consuming apps may use anything as identifier. For example, apps can simply generate a Guid and assign this for an user to be used as identicon. This may be changed at any time.

Some features require authentication and authorization, for example icon uploads. This app uses Jwt Bearer authentication. Valid authorities and required scopes are configured in the app config, as well as the name of the claim that is required to access this functionality.

Config Value	Type	Description
IconManagerClaimName	string	The name of the claim that is evaluated for access
JwtBearerRequiredScope	string	The scope required in the Jwt tokens
JwtBearerAuthorities	List<string>	The list of valid authorities that may issue Jwt tokens

The IconManagerClaimName may be either set to true or specify an ISO 8601 timestamp to indicate until when it is valid.

Authorization via Api Keys

Additionally, it is possible to configure Api Keys to be used as authorization mechanism. To do this, simply supply an array of valid api keys in the ApiKeys configuration property. The keys must be sent with each request in a http header X-DANGL-ICONS-API-KEY, which is also available as a constant value in IconManagerRequirementHandler.API_KEY_HEADER_NAME.

PNG Extension

All requests for identicons must have the png extension: /api/identicons/{iconId}.png
This is to allow caching of the icons in some CDNs that only cache specific file extensions. Internally, uploaded icons are always converted to png.

Identicon Generation Options

The /api/identicons/{iconId}.png endpoint has the following parameters:

• size to set the rectangle dimensions in pixel for the generated icons
• useSingleColor to only use a single color for the whole identicon
• useMaterialColors to use Material colors, they are a bit more intensive and match better with Material design styles
• useExtendedBlockConfigurator to allow the generation of triangles and rotated rectangles instead of only blocks

.NET Client

The Dangl.Icons.Client package contains a DanglIconsServiceCollectionExtensions class which has extension methods to configure the clients for dependency injection. This will also attach api keys (if given) to all outgoing requests. It uses the HttpClientFactory and is therefore safe to use throughout the lifetime of the application.

Examples

?size=64
&useSingleColor=true
&useMaterialColors=true
&useExtendedBlockConfigurator=true

?size=64
&useSingleColor=false
&useMaterialColors=true
&useExtendedBlockConfigurator=true

?size=64
&useSingleColor=true
&useMaterialColors=true
&useExtendedBlockConfigurator=false

?size=64
&useSingleColor=false
&useMaterialColors=false
&useExtendedBlockConfigurator=true

Docker Build

To build a Docker image, run ./build.ps1 BuildDocker -Configuration Release in the root directory of the solution. A build tagged danglicons:dev will be created

Assembly Strong Naming & Usage in Signed Applications

This module produces strong named assemblies when compiled. When consumers of this package require strongly named assemblies, for example when they themselves are signed, the outputs should work as-is. The key file to create the strong name is adjacent to the csproj file in the root of the source project. Please note that this does not increase security or provide tamper-proof binaries, as the key is available in the source code per Microsoft guidelines