¶ Authing - CSharp SDK

更新时间: 2024-07-24 08:50:33

Authing CSharp SDK 由两部分组成：用户认证模块（AuthenticationClient）和管理模块（ManagementClient）。

用户认证模块（AuthenticationClient）以终端用户（End User）的身份进行请求，提供了登录、注册、登出、管理用户资料、获取授权资源等所有用户自助完成的操作；此模块还提供了各种身份协议的 SDK，如 OpenID Connect (opens new window), OAuth 2.0 (opens new window), SAML (opens new window) 和 CAS (opens new window)。

管理模块（ManagementClient）以管理员（Administrator）的身份进行请求，用于管理用户池资源和执行管理任务，提供了管理用户、角色、应用、资源等方法；一般来说，你在 Authing 控制台 (opens new window) 中能做的所有操作，都能用此模块完成。

在一个项目中，ManagementClient 应该只应该被初始化一次，而 AuthenticationClient 一个实例对应一个终端用户，应该在每次请求中初始化一次。

¶ GitHub / Maven 地址

条目	说明
支持版本	netstandard2.0 net40 net45
GitHub 地址	Authing/authing-csharp-sdk: Authing CSharp SDK (opens new window)
Nuget 仓库地址	Authing.CSharp.SDK (https://www.nuget.org/packages/Authing.CSharp.SDK)

¶ 安装

¶ Nuget

Install-Package Authing.CSharp.SDK
 
        复制成功

¶ packages

<packages>
  <package id="Authing.CSharp.SDK" targetFramework="net462" />
</packages>
 
        复制成功

具体的版本号请前往 https://www.nuget.org/packages/Authing.CSharp.SDK 查看。

¶ 使用用户认证模块

¶ 初始化

¶ 获取应用信息

初始化用户认证模块（AuthenticationClient）需要获取 Authing 应用的相关配置信息，如应用 ID、应用密钥和应用域名等。

点此展开详情

首先你需要在 Authing 控制台 (opens new window) 创建一个 标准 Web 应用 或者 后端应用：

创建完成之后，你可以在此应用的应用详情页面中获取到相关信息。下面是你会经常使用到的几个配置项：

应用 ID（App ID）：应用的唯一标志。可以在应用详情中的应用设置 - 端点信息 中获取。
应用密钥（App Secret）：用于验证客户端请求的合法性。可以在应用详情的应用设置 - 端点信息 中获取。
应用域名（App Host）：应用域名，如 https://example.authing.cn 。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以应用详情中应用配置 - 认证配置 中的 认证地址 字段为准。
登录回调 URL（Redirect Uri）：当用户使用 Authing 的托管登录页进行认证，认证完成之后，会通过浏览器 302 重定向回调到此地址。可以配置多个地址，发起登录时可以选择任意一个。
退出登录回调 URL（Logout Redirect Uri）：当用户在浏览器端退出登录时，可以通过浏览器 302 重定向回调到此地址。可以配置多个地址，发起退出登录时可以选择任意一个。
换取 token 身份验证方式（Token Endpoint Auth Method）：调用 OIDC 获取 Token 接口或者 Signin 接口时客户端需要提供的校验方式。
检验 token 身份验证方式（Introspection Endpoint Auth Method）：调用 OIDC 校验 Token 合法性时客户端需要提供的校验方式。
撤回 token 身份验证方式（Revoke Endpoint Auth Method）：调用 OIDC 校验 Token 合法性时客户端需要提供的校验方式。

¶ 初始化

初始化示例代码如下所示：

using Authing.CSharp.SDK.Models.Authentication;
using Authing.CSharp.SDK.Services;

namespace ConsoleApplication
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            AuthenticationClientInitOptions clientOptions = new AuthenticationClientInitOptions
            {
                AppId = "AUTHING_APP_ID",// Authing 应用 ID
                AppSecret = "AUTHING_APP_SECRET",// Authing 应用密钥
                AppHost = "AUTHING_APP_HOST", // Authing 应用域名，如 https://example.authing.cn。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以 自建应用->应用配置->认证配置 下 `认证地址 `字段为准。
                RedirectUri = "AUTHING_APP_REDIRECT_URI"// Authing 应用配置的登录回调地址
            };

            // 初始化 AuthenticationClient
            AuthenticationClient authenticationClient = new AuthenticationClient(clientOptions);
        }
    }
}
 
        复制成功

点此展开 AuthenticationClient 的完整参数及释义

appId: Authing 应用 ID，必填。
appSecret: Authing 应用密钥，必填。
appHost: Authing 应用域名，如 https://example.authing.cn，必填。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以自建应用->应用配置->认证配置下 认证地址字段为准。
redirectUri: 认证完成后的重定向目标 URL，可选。Authing 服务器会对此链接进行校验，需要和控制台的设置保持一致。
logoutRedirectUri: 登出完成后的重定向目标 URL，可选。Authing 服务器会对此链接进行校验，需要和控制台的设置保持一致。
scope: 应用侧向 Authing 请求的权限，以空格分隔，可选。默认为 'openid profile'，成功获取的权限项会出现在 access_token 的 scope 字段中。一些示例：
- openid: OIDC 标准规定的权限，必须包含。
- profile: 获取用户的基本身份信息。
- offline_access: 认证时获取 refresh_token，可以通过 refresh_token 请求新的 access_token。
protocol: 应用协议类型，默认为 oidc。可选值为 oidc、oauth、cas、saml。
tokenEndPointAuthMethod: 获取 token 端点认证方式，默认为 client_secret_post。可选值为 client_secret_post, client_secret_basic 和 none。需要和你在 Authing 控制台 (opens new window) 的应用 - 自建应用 - 应用详情 - 应用配置 - 其他设置 - 授权配置中的换取 token 身份验证方式 配置保持一致。
introspectionEndPointAuthMethod: 校验 token 状态端点认证方式，默认为 client_secret_post。可选值为 client_secret_post, client_secret_basic 和 none。需要和你在 Authing 控制台 (opens new window) 的应用 - 自建应用 - 应用详情 - 应用配置 - 其他设置 - 授权配置中的检验 token 身份验证方式 配置保持一致。
revocationEndPointAuthMethod: 撤回 token 端点认证方式，默认为 client_secret_post。可选值为 client_secret_post, client_secret_basic 和 none。需要和你在 Authing 控制台 (opens new window) 的应用 - 自建应用 - 应用详情 - 应用配置 - 其他设置 - 授权配置中的撤回 token 身份验证方式 配置保持一致。
timeout: 请求超时时间，可选，单位为毫秒，默认为 10000（10 秒）。
lang: 接口 Message 返回语言格式（可选），可选值为 zh-CN、en-US、ja-JP 和 zh-TW，默认为 zh-CN。

¶ 快速开始

初始化完成用户认证模块（AuthenticationClient）之后，你可以获取 AuthenticationClient 的实例，然后调用此实例上的方法。

¶ 使用在线托管登录页登录

Authing 为所有开发者提供了开箱即用的在线托管登录页，CSharp SDK 提供了自动生成登录链接、处理登录回调等方法。

点此展开 Authing 托管登录页的详细介绍

Authing 托管登录页是最简单，最安全的集成方式。这是因为登录流程由 Authing 维护，并由 Authing 保持安全。对于大多数集成，建议使用 Authing 托管的登录流程。你的业务系统将用户重定向到 Authing，在此用户进行身份验证，然后重定向回在控制台配置的应用回调连接。此设计被认为是安全性最佳实践。在自定义配置方面，托管模式提供了中等程度的登录注册表单自定义配置，可通过控制台配置和 CSS 进行界面自定义。点此在线体验 (opens new window)。

使用这种方式，CSharp SDK 生成了登录地址之后，可以引导用户在浏览器访问此链接。终端用户点击此链接之，会通过浏览器 302 重定向跳转到你在 Authing 托管的在线登录页进行认证，认证完成之后回调到你的应用系统。Authing 托管登录页支持 Authing 现支持所有的认证能力，包含密码认证、社会化登录认证、扫码登录等，这也是我们最推荐的认证方式。

¶ 生成一次性登录链接

生成用于登录的一次性地址，并引导用户访问此链接。

using Authing.CSharp.SDK.Models.Authentication;
using Authing.CSharp.SDK.Services;

namespace ConsoleApplication
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            AuthenticationClientInitOptions clientOptions = new AuthenticationClientInitOptions
            {
                AppId = "AUTHING_APP_ID",// Authing 应用 ID
                AppSecret = "AUTHING_APP_SECRET",// Authing 应用密钥
                AppHost = "AUTHING_APP_HOST", // Authing 应用域名，如 https://example.authing.cn。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以 自建应用->应用配置->认证配置 下 `认证地址 `字段为准。
                RedirectUri = "AUTHING_APP_REDIRECT_URI"// Authing 应用配置的登录回调地址
            };

            // 初始化 AuthenticationClient
            AuthenticationClient authenticationClient = new AuthenticationClient(clientOptions);

            AuthUrlResult url = authenticationClient.BuildAuthUrl();
            Console.WriteLine(url.Url);
        }
    }
}

 
        复制成功

¶ 处理登录回调

当用户在 Authing 的托管登录页完成登录之后，将会回调到你配置的登录回调地址（及初始化 AuthenticationClient 时传入的 redirectUri），并且会在 URL 的 Query 参数中携带一次性临时凭证 code，你可以使用此 code 换取 access_token。

using Authing.CSharp.SDK.Models.Authentication;
using Authing.CSharp.SDK.Services;

namespace ConsoleApplication
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            AuthenticationClientInitOptions clientOptions = new AuthenticationClientInitOptions
            {
                AppId = "AUTHING_APP_ID",// Authing 应用 ID
                AppSecret = "AUTHING_APP_SECRET",// Authing 应用密钥
                AppHost = "AUTHING_APP_HOST", // Authing 应用域名，如 https://example.authing.cn。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以 自建应用->应用配置->认证配置 下 `认证地址 `字段为准。
                RedirectUri = "AUTHING_APP_REDIRECT_URI"// Authing 应用配置的登录回调地址
            };

            // 初始化 AuthenticationClient
            AuthenticationClient authenticationClient = new AuthenticationClient(clientOptions);

            // 生成用于登录的一次性地址，之前可以引导用户访问此地址
            string code = "REPLACE_ME_WITH_REAL_CODE";
            // 使用 code 换取 access_token

            CodeToTokenResponse resp = await authenticationClient.GetAccessTokenByCode(code);

            Console.Write(resp);
        }
    }
}

 
        复制成功

¶ 邮箱 + 密码登录

除了上述使用托管登录页的认证方式，如果你需要自建登录页面，Authing 也提供接口形式的认证方法，如果认证成功，也可以拿到用户的 access_token。拿到 access_token 之后，就可以调用修改用户信息等方法了。

using Authing.CSharp.SDK.Models.Authentication;
using Authing.CSharp.SDK.Services;
using System;
using System.Threading.Tasks;
using Authing.CSharp.SDK.Models;

namespace ConsoleApplication
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            AuthenticationClientInitOptions clientOptions = new AuthenticationClientInitOptions
            {
                AppId = "AUTHING_APP_ID",// Authing 应用 ID
                AppSecret = "AUTHING_APP_SECRET",// Authing 应用密钥
                AppHost = "AUTHING_APP_HOST", // Authing 应用域名，如 https://example.authing.cn。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以 自建应用->应用配置->认证配置 下 `认证地址 `字段为准。
                RedirectUri = "AUTHING_APP_REDIRECT_URI"// Authing 应用配置的登录回调地址
            };

            // 初始化 AuthenticationClient
            AuthenticationClient authenticationClient = new AuthenticationClient(clientOptions);

            // 调用 AuthenticationClient 的方法，如 signInByEmailPassword
            LoginTokenRespDto signInresp = await authenticationClient.SignInByEmailPassword(
                "test@example.com",
                "passw0rd",
                new SignInOptionsDto()
            );

            // 你可以从 LoginTokenRespDto 中得到用户的 access_token，此 access_token 代表了用户访问接口的凭证
            string accessToken = signInresp.Data.Access_token;
            // 之后使用此 accessToken 调用 AuthenticationClient 的 setAccessToken 方法，AuthenticationClient 便可以调用获取用户资料、修改用户资料、获取角色列表等要求登录才能访问的接口了。
            authenticationClient.setAccessToken(accessToken);

            // 调用其他需要登录才能访问的接口，如修改用户资料
            UpdateUserProfileDto updateProfileDto = new UpdateUserProfileDto();
            updateProfileDto.Nickname = "张三"; // 修改昵称为张三
            UserSingleRespDto resp = await authenticationClient.UpdateProfile(updateProfileDto);
            Console.WriteLine(resp);
        }
    }
}
 
        复制成功

¶ 使用管理模块

¶ 初始化

¶ 获取 AK/SK

Authing CSharp SDK 使用 AK/SK 本地对请求数据的摘要进行签名的鉴权机制，客户端在调用 API 时，SDK 使用 AK/SK 对请求数据的摘要进行签名计算，并将签名结果传输给服务器端进行签名验证。

在 Authing 中，目前有两种类型的 AK/SK：

用户池全局 AK/SK：具备用户池内所有资源的全局操作权限。你可以在 Authing 控制台 (opens new window) 的设置 - 基础设置 - 密钥管理 获取到用户池 ID 和用户池密钥，其中用户池 ID为 AK（Access Key ID）,用户池密钥为 SK（Access Key Secret）。
协作管理员 AK/SK：可针对用户池内的资源进行细粒度授权，协作管理员的 AK/SK 只能调用其被授权的 API。（正在开发中，尽情期待）

你可以根据自己的需求选择合适的 AK/SK。

点此展开如何获取用户池 ID 和用户池密钥

在 Authing 控制台 (opens new window)的设置 -> 基础设置 -> 密钥管理页面，可以获取到用户池 ID（UserPool Id）和用户池密钥（UserPool Secret），如下图所示：

¶ 初始化

初始化示例代码如下所示：

using Authing.CSharp.SDK.Services;
using System;
using System.Threading.Tasks;
using Authing.CSharp.SDK.Models;

namespace ConsoleManagement
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            ManagementClientOptions clientOptions = new ManagementClientOptions
            {
                AccessKeyId = "AUTHING_ACCESS_KEY_ID",// Authing 应用密钥
                AccessKeySecret = "AUTHING_ACCESS_KEY_SECRET", // Authing 应用域名，如 https://example.authing.cn。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以 自建应用->应用配置->认证配置 下 `认证地址 `字段为准。
            };

            // 初始化 ManagementClient
            ManagementClient managementClient = new ManagementClient(clientOptions);
        }
    }
}
 
        复制成功

点此展开 ManagementClient 的完整参数及释义

accessKeyId: Authing 用户池 ID;
accessKeySecret: Authing 用户池密钥;
timeout: 超时时间，单位为 ms，默认为 10000 ms;
host: Authing 服务器地址，默认为 https://api.authing.cn。如果你使用的是 Authing 公有云版本，请忽略此参数。如果你使用的是私有化部署的版本，此参数必填，格式如下: https://authing-api.my-authing-service.com（最后不带斜杠 /）。
lang: 接口 Message 返回语言格式（可选），可选值为 zh-CN、en-US、ja-JP 和 zh-TW，默认为 zh-CN。

¶ 快速开始

初始化完成 ManagementClient 之后，你可以获取 ManagementClient 的实例，然后调用此实例上的方法。

¶ 获取用户列表

using Authing.CSharp.SDK.Services;
using System;
using System.Threading.Tasks;
using Authing.CSharp.SDK.Models;

namespace ConsoleManagement
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            ManagementClientOptions clientOptions = new ManagementClientOptions
            {
                AccessKeyId = "AUTHING_ACCESS_KEY_ID",// Authing 应用密钥
                AccessKeySecret = "AUTHING_ACCESS_KEY_SECRET", // Authing 应用域名，如 https://example.authing.cn。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以 自建应用->应用配置->认证配置 下 `认证地址 `字段为准。
            };

            // 初始化 ManagementClient
            ManagementClient managementClient = new ManagementClient(clientOptions);

            // 获取用户列表
            ListUsersRequestDto dto = new ListUsersRequestDto();
            UserPaginatedRespDto resp =await managementClient.ListUsers(dto);
            Console.WriteLine(resp);
        }
    }
}
 
        复制成功

¶ 创建角色

using Authing.CSharp.SDK.Services;
using System;
using System.Threading.Tasks;
using Authing.CSharp.SDK.Models;

namespace ConsoleManagement
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            ManagementClientOptions clientOptions = new ManagementClientOptions
            {
                AccessKeyId = "AUTHING_ACCESS_KEY_ID",// Authing 应用密钥
                AccessKeySecret = "AUTHING_ACCESS_KEY_SECRET", // Authing 应用域名，如 			https://example.authing.cn
            };

            // 初始化 ManagementClient
            ManagementClient managementClient = new ManagementClient(clientOptions);

            // 创建角色
            CreateRoleDto dto = new CreateRoleDto();
            dto.Code="admin";
            dto.Description="管理员";
            RoleSingleRespDto resp =await managementClient.CreateRole(dto);
            Console.WriteLine(resp);
        }
    }
}
 
        复制成功

¶ 错误处理

Authing CSharp SDK 方法在请求接口时，不会抛出 Exception（网络错误除外），除非特殊说明，所有的方法返回值都会包含两个状态码：statusCode 和 apiCode：

statusCode: statusCode 为请求状态码，不包含具体的业务错误信息。当且仅当 statusCode 为 200 时，表示接口请求成功，此时不会带有 apiCode。statusCode 不为 200 的情况下，表示接口请求失败或者需要进行额外操作（比如登录接口需要进行 MFA 二次验证），你需要对此进行关注，进行必要的错误处理。每个 statusCode 对应一个类型的错误，具体的错误分类请见下文。在大多数情况下，除非你需要对某些特定的异常做出响应，否则你只需要关注 statusCode，不需要关注 apiCode。
apiCode: apiCode 为业务状态码，每个 apiCode 具备特定的错误含义，具体的 apiCode 列表见下文。apiCode 只会在 statusCode 非 200 且错误原因具备业务含义时才会返回。
requestId: 请求 ID，当请求失败时会返回。如果你在使用 Node SDK 的过程中遇到了错误，可以使用此 requestId 咨询 Authing 开发人员。

详细的 statusCode 列表和 apiCode 请见错误码。

using Authing.CSharp.SDK.Services;
using System;
using System.Threading.Tasks;
using Authing.CSharp.SDK.Models;
namespace ConsoleManagement
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            ManagementClientOptions clientOptions = new ManagementClientOptions
            {
                AccessKeyId = "AUTHING_ACCESS_KEY_ID",// Authing 应用密钥
                AccessKeySecret = "AUTHING_ACCESS_KEY_SECRET", // Authing 应用域名，如 https://example.authing.cn。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以 自建应用->应用配置->认证配置 下 `认证地址 `字段为准。
            };

            // 初始化 ManagementClient
            ManagementClient managementClient = new ManagementClient(clientOptions);

            // 创建角色
            CreateRoleDto dto = new CreateRoleDto();
            dto.Code="admin";
            dto.Description="管理员";
            RoleSingleRespDto resp =await managementClient.CreateRole(dto);

            if (resp.StatusCode != 200)
            {
                throw new Exception(resp.Message); // 抛出异常，由全局异常捕捉中间件进行异常捕捉
            }

            // 继续你的业务逻辑 ...
        }
    }
}
 
        复制成功

¶ 私有化部署

如果你使用的是私有化部署的 Authing IDaaS 服务，需要在初始化时指定 Authing 私有化实例的 API 地址，如下所示：

using Authing.CSharp.SDK.Services;
using System;
using System.Threading.Tasks;
using Authing.CSharp.SDK.Models;

namespace ConsoleManagement
{
    public class Program
    {
        static void Main(string[] args)
        {
            MainAsync().GetAwaiter().GetResult();
        }

        private static async Task MainAsync()
        {
            // 设置初始化参数
            ManagementClientOptions clientOptions = new ManagementClientOptions
            {
                AccessKeyId = "AUTHING_ACCESS_KEY_ID",// Authing 应用密钥
                AccessKeySecret = "AUTHING_ACCESS_KEY_SECRET", // Authing 应用域名，如 https://example.authing.cn。注意：Host 地址为示例样式，不同版本用户池的应用 Host 地址样式有所差异，实际地址以 自建应用->应用配置->认证配置 下 `认证地址 `字段为准。
                Host= "https://api.your-authing-service.com"
            };

            // 初始化 ManagementClient
            ManagementClient managementClient = new ManagementClient(clientOptions);

        }
    }
}
 
        复制成功

如果你不清楚如何获取，可以联系 Authing IDaaS 服务管理员。

¶ 获取帮助

有任何建议或者问题反馈，欢迎在 Authing 论坛 (opens new window)中提出。

评价此篇文档

有帮助

无帮助

有建议或错误，可直接在 Github 上反馈

若你已对系统有基本了解，并且感兴趣的话，点击跳转 Authing 控制台，来开启你的 Authing 之旅！

进入 Authing