Falcon.SugarApi/Falcon.SugarApi/ClaimTicket/Readme.md

客户凭据 Falcon.SugarApi.ClaimTicket.ClaimTicket

1、添加ClaimTicket支持。

是否使用ClaimTicket由插件自行决定。
如果插件需要使用ClaimTicket，按如下方式在插件服务配置中添加。

public class ServicePlugin:IServicePlugin
{
    IServiceCollection IServicePlugin.AddServices(IServiceCollection services,IConfiguration configuration) {
        //注入使用ClaimTicket的控制器
        services.AddPluginsController(this.GetType().Assembly);
        //添加ClaimTicket服务支持
        services.AddClaimTicket();
        return services;
    }
}

2、控制器注入

要完成用户的登录，认证和绑定工作需要注入ITicketBuilder接口，这个接口在上面的services.AddClaimTicket()中已经完成注入。
下面是在HomeController控制器中注入ITicketBuilder的示例。

public ITicketBuilder TicketBuilder { get; set; }

public HomeController(IServiceProvider service) : base(service) {
    this.TicketBuilder = service.GetRequiredService<ITicketBuilder>();
}

3、用户登录。

插件需要自行完成用户认证工作，示例代码如下。

[HttpGet]
public string Login(string username) {
    //验证用户有效性，自行调用数据库进行验证。

    //如果通过验证，生成用户票据
    var user = new UserTicket(
            //添加用户名
            new Claim("name",username),
            //添加其他必要的声明
            new Claim("role","admin")
    );
    var ticket = this.TicketBuilder.GetTicket(user);
    return ticket ?? "";
}

客户端在收到返回的票据后自行保管票据。

4、验证用户

实例代码如下：

[HttpGet]
public string ViewUser(string ticket) {
    //通过票据获取用户
    var cs = this.TicketBuilder.GetUser(ticket);
    if(cs == null) {
        return "TicketBuilder.GetUser 返回空";
    }
    StringBuilder sb = new();
    //轮训票据生成获取登录信息
    foreach(var i in cs.Claims) {
        sb.AppendLine($"type:{i.Type},Val:{i.Value}");
    }
    return sb.ToString();
}

5、绑定用户

示例代码如下:

[HttpGet]
public string Viewbind(string _authUserTicket,[FromHeader] UserTicket user) {
    StringBuilder sb = new();
    foreach(var i in user.Claims) {
        sb.AppendLine($"type:{i.Type},Val:{i.Value}");
    }
    return sb.ToString();
}

一般客户端通过HTTP头参数_authUserTicket提交用户凭据，这个例子中为了方便通过get参数提交票据，控制器可以自动将其绑定在UserTicket对象中。
因为action还通过httpbody获取了一个_authUserTicket参数，所以UserTicket需要加[FromHeader]特性。

6、自定义ClaimTicket配置

通过ClaimTicketOptions对象完成配置。完成配置的途径有两个。

1、在插件配置中优先注入自己的ClaimTicketOptions对象。

public class ServicePlugin:IServicePlugin
{
    IServiceCollection IServicePlugin.AddServices(IServiceCollection services,IConfiguration configuration) {
        //注入使用ClaimTicket的控制器
        services.AddPluginsController(this.GetType().Assembly);

        //优先添加自己的服务配置
        services.AddSingleton(new ClaimTicketOptions());

        //添加ClaimTicket服务支持
        services.AddClaimTicket();
        return services;
    }
}

2、在插件配置中优先注入自己的ClaimTicketOptions对象。

public class ServicePlugin:IServicePlugin
{
    IServiceCollection IServicePlugin.AddServices(IServiceCollection services,IConfiguration configuration) {
        //注入使用ClaimTicket的控制器
        services.AddPluginsController(this.GetType().Assembly);

        //优先添加自己的服务配置
        //services.AddSingleton(new ClaimTicketOptions());

        //添加ClaimTicket服务支持
        services.AddClaimTicket(optionsBuilder => {
            //客户端通过_headCalimTick属性提交凭据
            optionsBuilder.HttpHeaderKey = "_headCalimTick";
        });
        return services;
    }
}

7、扩展ITicketBuilder

插件可以自行扩展票据的生成方式，方法有两个，一个是继承TicketBuilder对象并重写方法，另一个就是自己实现ITicketBuilder接口。

/// <summary>
/// 自定义票据生成方式
/// </summary>
public class MyTicketBuilder:TicketBuilder, ITicketBuilder
{
    /// <summary>
    /// 使用票据参数构造生成器
    /// </summary>
    /// <param name="options">生成参数</param>
    public MyTicketBuilder(ClaimTicketOptions options) : base(options) { }

    /// <inheritdoc/>
    public override string? GetTicket(UserTicket userTicket) {
        //实现自己的票据生成方法
            
        //或使用基类提供的方法
        return base.GetTicket(userTicket);
    }

    /// <inheritdoc/>
    public override UserTicket? GetUser(string ticket) {
        //根据票据获取用户声明返回用户信息

        //或使用基类提供的方法
        return base.GetUser(ticket);
    }
}

然后在调用AddClaimTicket之前注入自己的ITicketBuilder

public class ServicePlugin:IServicePlugin
{
    IServiceCollection IServicePlugin.AddServices(IServiceCollection services,IConfiguration configuration) {
        //注入使用ClaimTicket的控制器
        services.AddPluginsController(this.GetType().Assembly);

        //优先添加自己的服务配置
        //services.AddSingleton(new ClaimTicketOptions());

        //注入扩展MyTicketBuilder
        services.TryAddSingleton<ITicketBuilder,MyTicketBuilder>();

        //添加ClaimTicket服务支持
        services.AddClaimTicket(optionsBuilder => {
            //客户端通过_headCalimTick属性提交凭据
            optionsBuilder.HttpHeaderKey = "_headCalimTick";
        });
        return services;
    }
}