Trabalhar com identidades baseadas em afirmaçõesWork with claims-based identities

Código de exemplo do GitHubGitHub Sample code

Afirmações no Azure ADClaims in Azure AD

Quando um utilizador inicia sessão, o Azure AD envia um token de ID que contém um conjunto de afirmações sobre o utilizador.When a user signs in, Azure AD sends an ID token that contains a set of claims about the user. Uma declaração é simplesmente uma informação, expressado como um par chave/valor.A claim is simply a piece of information, expressed as a key/value pair. Por exemplo, email=bob@contoso.com.For example, email=bob@contoso.com. Afirmações têm um emissor — neste caso, o Azure AD — que é a entidade que autentica o utilizador e cria as afirmações.Claims have an issuer — in this case, Azure AD — which is the entity that authenticates the user and creates the claims. Confiará nas declarações que uma vez que confia que o emissor.You trust the claims because you trust the issuer. (Por outro lado, se não confia o emissor, não confiará nas declarações!)(Conversely, if you don't trust the issuer, don't trust the claims!)

Num alto nível:At a high level:

  1. O utilizador é autenticado.The user authenticates.
  2. O IDP envia um conjunto de declarações.The IDP sends a set of claims.
  3. A aplicação normaliza ou aumenta as declarações (opcionais).The app normalizes or augments the claims (optional).
  4. A aplicação utiliza as afirmações para tomar decisões de autorização.The app uses the claims to make authorization decisions.

No OpenID Connect, o conjunto de declarações que obtém é controlado pelos parâmetro de âmbito do pedido de autenticação.In OpenID Connect, the set of claims that you get is controlled by the scope parameter of the authentication request. No entanto, o Azure AD emite um conjunto limitado de afirmações com OpenID Connect; ver Tipos de Token e de Afirmações Suportados.However, Azure AD issues a limited set of claims through OpenID Connect; see Supported Token and Claim Types. Se quiser obter mais informações sobre o utilizador, terá de utilizar o Azure AD Graph API.If you want more information about the user, you'll need to use the Azure AD Graph API.

Aqui estão algumas das declarações do Azure AD que uma aplicação, normalmente, podem ser importantes sobre:Here are some of the claims from Azure AD that an app might typically care about:

Tipo de afirmação no token de IDClaim type in ID token DescriçãoDescription
audaud Que o token foi emitido para.Who the token was issued for. Este será o ID de cliente. da aplicaçãoThis will be the application's client ID. Em geral, não deve tem de se preocupar sobre essa declaração, porque o middleware o valida automaticamente.Generally, you shouldn't need to worry about this claim, because the middleware automatically validates it. Exemplo: "91464657-d17a-4327-91f3-2ed99386406f"Example: "91464657-d17a-4327-91f3-2ed99386406f"
Gruposgroups Uma lista de grupos do Azure AD de que o utilizador é membro.A list of Azure AD groups of which the user is a member. Exemplo: ["93e8f556-8661-4955-87b6-890bc043c30f", "fc781505-18ef-4a31-a7d5-7d931d7b857e"]Example: ["93e8f556-8661-4955-87b6-890bc043c30f", "fc781505-18ef-4a31-a7d5-7d931d7b857e"]
ISSiss O emissor do OIDC token.The issuer of the OIDC token. Exemplo: https://sts.windows.net/b9bd2162-77ac-4fb2-8254-5c36e9c0a9c4/Example: https://sts.windows.net/b9bd2162-77ac-4fb2-8254-5c36e9c0a9c4/
namename Nome a apresentar do utilizador.The user's display name. Exemplo: "Alice A."Example: "Alice A."
OIDoid O identificador de objeto para o utilizador no Azure AD.The object identifier for the user in Azure AD. Este valor é o identificador de imutável e não reutilizável do utilizador.This value is the immutable and non-reusable identifier of the user. Utilize este valor, e-mail, como um identificador exclusivo para os utilizadores. podem alterar os endereços de e-mail.Use this value, not email, as a unique identifier for users; email addresses can change. Se utilizar o Azure AD Graph API na sua aplicação, o ID de objeto é esse valor usado para consultar as informações de perfil.If you use the Azure AD Graph API in your app, object ID is that value used to query profile information. Exemplo: "59f9d2dc-995a-4ddf-915e-b3bb314a7fa4"Example: "59f9d2dc-995a-4ddf-915e-b3bb314a7fa4"
funçõesroles Uma lista de funções de aplicação para o utilizador.A list of app roles for the user. Exemplo: ["SurveyCreator"]Example: ["SurveyCreator"]
NIFtid ID do inquilino.Tenant ID. Este valor é um identificador exclusivo para o inquilino no Azure AD.This value is a unique identifier for the tenant in Azure AD. Exemplo: "b9bd2162-77ac-4fb2-8254-5c36e9c0a9c4"Example: "b9bd2162-77ac-4fb2-8254-5c36e9c0a9c4"
unique_nameunique_name Um nome de exibição legíveis humana do utilizador.A human readable display name of the user. Exemplo: "alice@contoso.com"Example: "alice@contoso.com"
upnupn Nome principal de utilizador.User principal name. Exemplo: "alice@contoso.com"Example: "alice@contoso.com"

Esta tabela lista os tipos de afirmações, tal como aparecem no token de ID.This table lists the claim types as they appear in the ID token. No núcleo do ASP.NET, o middleware de OpenID Connect converte alguns dos tipos de afirmação quando ela preenche a coleção de declarações para o principal de utilizador:In ASP.NET Core, the OpenID Connect middleware converts some of the claim types when it populates the Claims collection for the user principal:

  • oid > http://schemas.microsoft.com/identity/claims/objectidentifieroid > http://schemas.microsoft.com/identity/claims/objectidentifier
  • tid > http://schemas.microsoft.com/identity/claims/tenantidtid > http://schemas.microsoft.com/identity/claims/tenantid
  • unique_name > http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameunique_name > http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  • UPN > http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upnupn > http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

Transformações de afirmaçõesClaims transformations

Durante o fluxo de autenticação, pode querer modificar as afirmações que obtém do IDP.During the authentication flow, you might want to modify the claims that you get from the IDP. No núcleo do ASP.NET, pode executar a transformação de declarações dentro dos AuthenticationValidated evento o middleware de OpenID Connect.In ASP.NET Core, you can perform claims transformation inside of the AuthenticationValidated event from the OpenID Connect middleware. (Consulte eventos de autenticação.)(See Authentication events.)

Qualquer afirmações que adicionar durante AuthenticationValidated são armazenadas no cookie de autenticação de sessão.Any claims that you add during AuthenticationValidated are stored in the session authentication cookie. Eles não obter enviados de volta para o Azure AD.They don't get pushed back to Azure AD.

Aqui estão alguns exemplos de transformação de declarações:Here are some examples of claims transformation:

  • Normalização de afirmações, ou fazer afirmações consistente entre utilizadores.Claims normalization, or making claims consistent across users. Isso é especialmente relevante se estiver a obter afirmações de vários IDPs, o que poderão utilizar tipos de declaração diferentes para informações semelhantes.This is particularly relevant if you are getting claims from multiple IDPs, which might use different claim types for similar information. Por exemplo, o Azure AD envia uma afirmação de "upn" que contém o correio eletrónico do utilizador.For example, Azure AD sends a "upn" claim that contains the user's email. Outros IDPs poderão enviar uma afirmação de "email".Other IDPs might send an "email" claim. O código a seguir converte a afirmação "upn" numa afirmação de "email":The following code converts the "upn" claim into an "email" claim:

    var email = principal.FindFirst(ClaimTypes.Upn)?.Value;
    if (!string.IsNullOrWhiteSpace(email))
    {
        identity.AddClaim(new Claim(ClaimTypes.Email, email));
    }
    
  • Adicionar padrão de valores de afirmação declarações que não estão presentes — por exemplo, atribuir um utilizador a uma função de predefinição.Add default claim values for claims that aren't present — for example, assigning a user to a default role. Em alguns casos isso pode simplificar a lógica de autorização.In some cases this can simplify authorization logic.

  • Adicione tipos de afirmação personalizada com informações específicas sobre o utilizador.Add custom claim types with application-specific information about the user. Por exemplo, poderia armazenar algumas informações sobre o utilizador numa base de dados.For example, you might store some information about the user in a database. Poderia adicionar uma declaração personalizada com essas informações para o tíquete de autenticação.You could add a custom claim with this information to the authentication ticket. A afirmação é armazenada num cookie, portanto, precisa apenas passá-lo da base de dados uma vez por início de sessão.The claim is stored in a cookie, so you only need to get it from the database once per login session. Por outro lado, também queira evitar a criação de cookies excessivamente grandes, por isso terá de considerar o compromisso entre o tamanho de cookie em comparação com pesquisas de base de dados.On the other hand, you also want to avoid creating excessively large cookies, so you need to consider the trade-off between cookie size versus database lookups.

Após concluir o fluxo de autenticação, as afirmações estão disponíveis no HttpContext.User.After the authentication flow is complete, the claims are available in HttpContext.User. Nesse ponto, deve tratá-los como uma coleção de só de leitura—usá-los por exemplo, para tomar decisões de autorização.At that point, you should treat them as a read-only collection—for example, using them to make authorization decisions.

Validação do emissorIssuer validation

No OpenID Connect, a afirmação do emissor ("iss") identifica o IDP que emitiu o token de ID.In OpenID Connect, the issuer claim ("iss") identifies the IDP that issued the ID token. Parte do fluxo de autenticação OIDC é verificar se a afirmação do emissor corresponde ao emissor real.Part of the OIDC authentication flow is to verify that the issuer claim matches the actual issuer. O middleware OIDC manipula isso para.The OIDC middleware handles this for you.

No Azure AD, o valor de emissor é exclusivo por inquilino do AD (https://sts.windows.net/<tenantID>).In Azure AD, the issuer value is unique per AD tenant (https://sts.windows.net/<tenantID>). Por conseguinte, o aplicativo deve fazer uma verificação adicional, para se certificar de que o emissor representa um inquilino que está autorizado a iniciar sessão aplicação.Therefore, an application should do an additional check, to make sure the issuer represents a tenant that is allowed to sign in to the app.

Para uma aplicação de inquilino único, apenas pode verificar que o emissor é o seu inquilino.For a single-tenant application, you can just check that the issuer is your own tenant. Na verdade, o middleware OIDC faz isso automaticamente por predefinição.In fact, the OIDC middleware does this automatically by default. Numa aplicação multi-inquilino, terá de permitir que vários emissores, correspondente para os inquilinos diferentes.In a multitenant app, you need to allow for multiple issuers, corresponding to the different tenants. Esta é uma abordagem geral para utilizar:Here is a general approach to use:

  • Nas opções de middleware OIDC, defina ValidateIssuer como falso.In the OIDC middleware options, set ValidateIssuer to false. Isto desativa a verificação automática.This turns off the automatic check.
  • Quando um inquilino se inscreve, armazene o inquilino e o emissor na sua DB do utilizador.When a tenant signs up, store the tenant and the issuer in your user DB.
  • Sempre que um utilizador inicia sessão, procure o emissor na base de dados.Whenever a user signs in, look up the issuer in the database. Se o emissor não for encontrado, significa que ainda não se inscreveu nesse inquilino.If the issuer isn't found, it means that tenant hasn't signed up. Pode redirecioná-los para uma página de inscrição.You can redirect them to a sign up page.
  • Poderia também lista de proibições determinados inquilinos; Por exemplo, para os clientes que não a sua subscrição pagam.You could also blacklist certain tenants; for example, for customers that didn't pay their subscription.

Para uma discussão mais detalhada, consulte Inscreva-se e integração de inquilinos numa aplicação multi-inquilino.For a more detailed discussion, see Sign-up and tenant onboarding in a multitenant application.

Utilizar afirmações de autorizaçãoUsing claims for authorization

Com declarações, a identidade do utilizador já não é uma entidade monolítica.With claims, a user's identity is no longer a monolithic entity. Por exemplo, um utilizador pode ter um endereço de e-mail, número de telefone, aniversário, sexo, etc. Talvez IDP o usuário armazena todas essas informações.For example, a user might have an email address, phone number, birthday, gender, etc. Maybe the user's IDP stores all of this information. Mas quando se autentica o usuário, normalmente obtém um subconjunto desses como afirmações.But when you authenticate the user, you'll typically get a subset of these as claims. Nesse modelo, a identidade do utilizador é simplesmente um pacote de declarações.In this model, the user's identity is simply a bundle of claims. Quando tomar decisões de autorização sobre um utilizador, irá procurar particulares conjuntos de declarações.When you make authorization decisions about a user, you will look for particular sets of claims. Em outras palavras, a pergunta "O utilizador X executar ação Y", por fim, torna-se "Faz o utilizador ter de X reclamação Z".In other words, the question "Can user X perform action Y" ultimately becomes "Does user X have claim Z".

Aqui estão alguns padrões básicos para a verificação de afirmações.Here are some basic patterns for checking claims.

  • Para verificar se o utilizador tem uma afirmação específica com um valor específico:To check that the user has a particular claim with a particular value:

    if (User.HasClaim(ClaimTypes.Role, "Admin")) { ... }
    

    Esse código verifica se o utilizador tem uma afirmação de função com o valor "Admin".This code checks whether the user has a Role claim with the value "Admin". Ele manipula corretamente o caso em que o utilizador tem nenhuma afirmação de função ou múltiplas declarações de função.It correctly handles the case where the user has no Role claim or multiple Role claims.

    O ClaimTypes classe define constantes para tipos de afirmação utilizadas com frequência.The ClaimTypes class defines constants for commonly used claim types. No entanto, pode utilizar qualquer valor de cadeia de caracteres para o tipo de afirmação.However, you can use any string value for the claim type.

  • Para obter um valor único para um tipo de afirmação, quando espera daí para ter um máximo de um valor:To get a single value for a claim type, when you expect there to be at most one value:

    string email = User.FindFirst(ClaimTypes.Email)?.Value;
    
  • Para obter todos os valores de um tipo de afirmação:To get all the values for a claim type:

    IEnumerable<Claim> groups = User.FindAll("groups");
    

Para obter mais informações, consulte autorização baseada em funções e baseada em recursos em aplicações multi-inquilino.For more information, see Role-based and resource-based authorization in multitenant applications.

SeguinteNext