layout: docs-default

用戶服務

用戶服務的例子充岛，請看這里

IdentityServer3 定義了一個 IUserService 接口來抽象下層的用戶身份管理系統(tǒng)，它為本地和第三方賬號的用戶驗證語義舌劳，它也提供了IdentityServer生成令牌需要的身份和聲明以及用戶信息endpoint.用戶服務更提供了登陸的工作流(比如接受用戶許可協(xié)議或者登陸額外需要的2fa)

用戶服務的方法分為認證相關方法和令牌聲明信息和用戶信息相關方法。

• 用戶試圖登陸時菊匿，IdentityServer調(diào)用認證方法來認證狭莱。這些方法的輸出或者是成功登陸奥裸，錯誤或部分登陸(本節(jié)后面會詳細介紹部分登陸)
• 當IdentityServer需要聲明信息或確認用戶還有權(quán)獲取令牌時，會調(diào)用用戶信息相關方法证杭。

IUserService

IUserService 定義了下面的方法:

• PreAuthenticateAsync
  • 這個方法在現(xiàn)實登陸頁面前調(diào)用田度，用來判斷用戶是否已經(jīng)被其它方式認證(比如客戶端證書或者可信HTTP 頭),如果已經(jīng)登陸，那么登陸頁面不會顯示解愤。
  • PreAuthenticationContext 有下面的屬性:
    • SignInMessage: 登陸的上下文信息
    • AuthenticateResult: 用戶服務判定如何顯示認證(如果是null則顯示正常的登陸界面镇饺。)
    • ShowLoginPageOnErrorResult (v2.4新增): 如果AuthenticateResult含有一個錯誤信息，我們希望它把錯誤信息顯示在登陸頁面(而不是一個通用錯誤信息）送讲。
• AuthenticateLocalAsync
  • 這個方法用于本地賬號登陸 (只要用戶使用用戶名密碼對話框登陸).
  • LocalAuthenticationContext 有下面的屬性:
    • Username: 用戶名.
    • Password: 密碼.
    • SignInMessage: 授權(quán)endpoint收到的上下文信息.
    • AuthenticateResult: 用戶服務判定如何顯示認證(如果是null表示無效的 Username或 Password).
• AuthenticateExternalAsync
  • 用戶使用第三方認證的時候奸笤，會調(diào)用這個方法來關聯(lián)第三方賬號和本地賬號。
  • ExternalAuthenticationContext 有下面的屬性:
    • ExternalIdentity: 第三方登陸提供的信息李茫，包括:
      • Provider: 第三方登陸的標識符.
      • ProviderId: 第三方登陸提供的用戶唯一標識揭保。
      • Claims: 第三方登陸提供的用戶聲明信息。
    • SignInMessage: 授權(quán)endpoint收到的上下文信息.
    • AuthenticateResult: 用戶服務判定如何顯示認證(如果是null表示沒有本地賬號能匹配上第三方提供的賬號).
• PostAuthenticateAsync
  • 這個方法在用戶登陸成功但是還沒有轉(zhuǎn)到客戶程序時調(diào)用魄宏。在所有其他認證結(jié)束后，用戶服務在這里確認自定義工作流
  • PostAuthenticationContext 帶有下面屬性:
    • SignInMessage: 授權(quán)endpoint收到的上下文信息.
    • AuthenticateResult: 當前的 AuthenticateResult. 用戶服務可以修改這個值來改變認證輸出存筏。
• SignOutAsync
  • 用戶登出時調(diào)用這個方法
  • SignOutContext 帶有下面屬性:
    • Subject: 登出用戶的標識
• GetProfileDataAsync
  • 當申請任何聲明時宠互，這個方法會被調(diào)用(如: 創(chuàng)建令牌時或者來自用戶信息endpoint).
  • ProfileDataRequestContext 帶有下面屬性:
    • Subject: 被請求的用戶信息的用戶標識
    • IssuedClaims: 用戶服務需要賦值給這個屬性來指定那些聲明可以下發(fā)。
    • RequestedClaimTypes: 請求的聲明類型椭坚。用戶服務只能返回這個屬性指定的聲明予跌。
    • AllClaimsRequested: 請求返回所有聲明(這個屬性會忽略RequestedClaimTypes).
    • Client: 那個客戶端發(fā)出的請求
    • Caller: IdentityServer 中那個方法調(diào)用了當前方法，可能的值包括:
      • "ClaimsProviderIdentityToken"
      • "ClaimsProviderAccessToken"
      • "UserInfoEndpoint"
• IsActiveAsync
  • 這個方法用于判斷用戶是否還是有效的善茎，活躍的券册。(比如：用戶登陸期間，賬號可能已經(jīng)被禁用啦).
  • IsActiveContext 帶有下面屬性:
    • Subject: 用戶標識.
    • Client: 那個客戶端發(fā)出的請求.
    • IsActive: 如果用戶已經(jīng)被禁用垂涯，用戶服務應該設置這個值為false烁焙。

SignInMessage

所有的認證方法都會收到SignInMessage上下文信息:

• ReturnUrl: 用戶從這個Url發(fā)起登陸請求，一般意味著耕赘，登陸成功后需要返回到這個頁面骄蝇。
• ClientId: 發(fā)出登陸請求的客戶端的標識
• IdP: 第三方登陸提供請求
• Tenant: 用戶來自哪個承租人。
• LoginHint: 登陸時期望的用戶名操骡，可以默認顯示登陸頁面用戶名輸入框九火。
• DisplayMode: 來自授權(quán)請求的顯示模式。
• UiLocales: UI本地化要求册招。
• AcrValues: 來自授權(quán)請求的acr值

AuthenticateResult

所有的認證方法都會返回AuthenticateResult岔激，它有很多可能的輸出結(jié)果。它有多個構(gòu)造函數(shù)來初始化不同的輸出:

// Full login
AuthenticateResult(string subject, string name, IEnumerable<Claim> claims = null, string identityProvider = Constants.BuiltInIdentityProvider, string authenticationMethod = null)

// Partial Login (where subject is known)
AuthenticateResult(string redirectPath, string subject, string name, IEnumerable<Claim> claims = null, string identityProvider = Constants.BuiltInIdentityProvider, string authenticationMethod = null)

// Partial Login (where subject is not known)
AuthenticateResult(string redirectPath, IEnumerable<Claim> claims)

// Partial Login (from external login)
AuthenticateResult(string redirectPath, ExternalIdentity externalId)

// Login error
AuthenticateResult(string errorMessage)

完整登陸

完整登陸必須提供用戶的subject和name是掰，subject是用戶服務使用的用戶唯一標識虑鼎，name用來顯示在用戶界面上。
聲明(Claim)也可能提供冀惭，用戶服務的有些方法可能需要這些附加的信息震叙。
如果是通過第三方登陸掀鹅，那么identityProvider參數(shù)也需要提供。這個參數(shù)可以通過身份令牌里的idp聲明提供或者用戶信息endpoint. 如果通過本地賬號登陸媒楼，這個參數(shù)不應該被使用(會使用默認的Constants.BuiltInIdentityProvider ).

可選參數(shù) authenticationMethod生成amr聲明乐尊，用來說明用戶該如何驗證，如:雙因子驗證還是客戶端證書驗證划址。如果沒有傳入扔嵌，那么本地賬號期望使用password，如果是第三方登陸夺颤，那么這個值會是external表示是第三方登陸痢缎。
所有這些聲明(subject, name, idp, amr 和其他Claim列表)會用來生成認證cookie。這個認證cookie會由katana cookie認證中間件來管理世澜。認證中間件會使用常量Constants.PrimaryAuthenticationType來設定AuthenticationType值独旷。

ClaimsPrincipal由完整登陸創(chuàng)建，IUserService其它API會通過Subject使用寥裂。(PostAuthenticateAsync, GetProfileDataAsync, IsActiveAsync, and SignOutAsync).

部分登陸

除了完整登陸嵌洼，認證API還可以執(zhí)行"部分登陸".部分登陸允許用戶服務中斷用戶的正常登陸過程，讓用戶到一個自定義的頁面去完成一些任務后才能繼續(xù)登陸封恰。（比如完成注冊麻养，接受用戶許可協(xié)議，執(zhí)行2fa）诺舔。鳖昌、

部分登陸會通過katana認證中間件發(fā)送一個"部分登陸的"cookie，認證中間件會使用常量Constants.PrimaryAuthenticationType來設定AuthenticationType值低飒。
部分登陸可以創(chuàng)建和完整登陸一樣的參數(shù)(subject, name, claims, amr, and idp)以及redirectPath. 部分登陸也可以只創(chuàng)建 claims集合和 redirectPath. 兩種方法的最大區(qū)別是用戶身份已經(jīng)確認许昨。

托管程序會提供redirectPath，用來重定向到自定義的網(wǎng)頁上逸嘀，在這個網(wǎng)頁上用戶聲明可以用來完成自定義的工作流车要。這個頁面可以通過GetIdentityServerPartialLoginAsync OWIN environment extension method來獲取聲明信息.

當用戶完成了自定義的任務(接受用戶許可協(xié)議，注冊或者2fa), 用戶會被重定向會登陸頁面完成完整的登陸過程崭倘。重定向用戶回來的URL可以通過GetPartialLoginResumeUrlAsync OWIN environment extension method方法得到.如果需要用戶重新登陸翼岁，則調(diào)用 GetPartialLoginRestartUrlAsync OWIN environment extension method .

在重定向回登陸頁面前，在部分登陸的聲明可以通過UpdatePartialLoginClaimsAsync OWIN environment extension method改變.如果需要移除或者清除部分登陸則可以使用RemovePartialLoginCookie OWIN environment extension method.

第三方部分登陸

如果用戶從第三方登陸并且沒有對應的本地賬號司光。自定義的用戶服務也可以重定向會客戶端琅坡，這需要通過創(chuàng)建一個帶有ExternalIdentity 的AuthenticateResult，并傳給AuthenticateExternalAsyncAPI残家。這會創(chuàng)建一個部分登陸(和上面一樣t通過PartialSignInAuthenticationType)榆俺，但是cookie里會用external_provider_user_id代替subject聲明（或者通過Constants.ClaimTypes.ExternalProviderUserId），聲明里的Issuer是第三方標識，這個標識可以用來創(chuàng)建本地賬號并和第三方賬號關聯(lián)茴晋。
一旦用戶完成了本地賬號注冊陪捷，他會被重定向會登陸頁面來完成完整登陸(和上面機制一樣).

登陸錯誤

最后，認證API可以提供錯誤信息顯示在登陸頁面上诺擅，這可以通過使用AuthenticateResult的接受字符串(錯誤信息)構(gòu)造函數(shù)來實現(xiàn)市袖。