getting_started.md

Getting Started

The scope of this library is to provide the support for the persistence of Users and Roles to the Microsoft Identity Core framework, and as such before you can enable it's functions you must configure it in that context.

Intall the Library

The library is available through NuGet, and can be installed and restored easily once configured in your projects.

At the moment (February 2022) this is developed within the .NET 5.0 framework, and thus compatible with all the profiles of the .NET framework greater or equal than that (.NET 6.0, .NET 7.0).

You can install the library through the dotnet tool command line

dotnet add package Deveel.Identity.MongoDb

Or by editing your .csproj file and adding a <PackageReference> entry.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
    ...

  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Deveel.Identity.MongoDb" Version="1.0.1-alpha1" />
    ...
  </ItemGroup>
</Project>

This provides to instrumentation to support the MongoDB storage in the scope of your application that uses the Microsoft Identity Framework.

Configuring the Framework

The configuration of the stroage system is fairly easy and it follows a standard pattern, attached to the builder functions already provided by the framework.

For example, assuming you are working on a traditional ASP.NET application model, you can enable these functions like this:

using System;

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

using Deveel.Security;

namespace Example {
    public class Startup {
        public Startup(IConfiguration config) {
            Configuration = config;
        }

        public IConfiguration Configuration { get; }

        public void Configure(IServiceCollection services) {
            // ... add any other service you need ...

            // this call adds the basic MongoDB storage layer
            // using the default configurations
            services.AddIdentityCore<MongoUser>()
                .AddMongoStores(Configuration, "Mongo:Identity");
        }
    }
}

The above sample is all you need to start, and it uses one of the overloads provided that injects the needed configurations and services, accessing the sub/section Mongo>Identity from the given IConfiguration instance.

You will find out that the library provides many options to configure your instance of the framework: the example above is the simplest one that registers both the Users and Roles stores and services, while more fine-grained calls can let you select what to use.

Using the Manager

Once the configurations are set, the environment makes available instances of UserManager<MongoUser> and RoleManager<MongoRole> that can be used for your operations

using System;

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Mvc

using Deveel.Security;

namespace Example {
    [Route("api/[controller]")]
    [ApiController]
    public class UserController : Controller {
        public UserController(UserManager<MongoUser> userManager) {
            // initialize a property and use its core functions
        }
    }
}