Como: personalizar declarações emitidas em tokens para um aplicativo específico em um locatário (versão prévia)How to: Customize claims emitted in tokens for a specific app in a tenant (Preview)

Observação

Esse recurso substitui a personalização de declarações oferecida pelo portal atualmente.This feature replaces and supersedes the claims customization offered through the portal today. No mesmo aplicativo, se você personalizar declarações usando o portal, além de usar o método Graph/PowerShell detalhado neste documento, os tokens emitidos para o aplicativo ignorarão a configuração no portal.On the same application, if you customize claims using the portal in addition to the Graph/PowerShell method detailed in this document, tokens issued for that application will ignore the configuration in the portal. Configurações feitas por meio dos métodos detalhados neste documento não serão refletidas no portal.Configurations made through the methods detailed in this document will not be reflected in the portal.

Esse recurso é usado por administradores de locatários para personalizar as declarações emitidas em tokens para um aplicativo específico em seu locatário.This feature is used by tenant admins to customize the claims emitted in tokens for a specific application in their tenant. Você pode usar as políticas de mapeamento de declarações para:You can use claims-mapping policies to:

  • Selecionar quais declarações são incluídas nos tokens.Select which claims are included in tokens.
  • Crie tipos de declaração que ainda não existem.Create claim types that do not already exist.
  • Escolher ou alterar a fonte dos dados emitidos em declarações específicas.Choose or change the source of data emitted in specific claims.

Observação

Atualmente, essa capacidade está em visualização pública.This capability currently is in public preview. Esteja preparado para reverter ou remover quaisquer alterações.Be prepared to revert or remove any changes. O recurso está disponível em qualquer assinatura do Azure AD (Azure Active Directory) durante a visualização pública.The feature is available in any Azure Active Directory (Azure AD) subscription during public preview. No entanto, quando o recurso for disponibilizado para todos, alguns aspectos dele poderão exigir uma assinatura do Azure AD Premium.However, when the feature becomes generally available, some aspects of the feature might require an Azure AD premium subscription. Esse recurso é compatível com a configuração das políticas de mapeamento de declarações para os protocolos WS-Fed, SAML, OAuth e OpenID Connect.This feature supports configuring claim mapping policies for WS-Fed, SAML, OAuth, and OpenID Connect protocols.

Tipo de política de mapeamento de declaraçõesClaims mapping policy type

No Azure AD, um objeto de Política representa um conjunto de regras empregadas em aplicativos individuais ou em todos os aplicativos de uma organização.In Azure AD, a Policy object represents a set of rules enforced on individual applications or on all applications in an organization. Cada tipo de política tem uma estrutura exclusiva, com um conjunto de propriedades que são aplicadas aos objetos aos quais são atribuídas.Each type of policy has a unique structure, with a set of properties that are then applied to objects to which they are assigned.

Uma política de mapeamento de declarações é um tipo de objeto de Política que modifica as declarações emitidas em tokens emitidos para aplicativos específicos.A claims mapping policy is a type of Policy object that modifies the claims emitted in tokens issued for specific applications.

Conjuntos de declaraçõesClaim sets

Há determinados conjuntos de declarações que definem como e quando elas são usadas em tokens.There are certain sets of claims that define how and when they're used in tokens.

Conjunto de declaraçõesClaim set DescriptionDescription
Conjunto de declarações de núcleoCore claim set Estão presentes em todos os tokens, independentemente da política.Are present in every token regardless of the policy. Essas declarações também são consideradas restritas e não podem ser modificadas.These claims are also considered restricted, and can't be modified.
Conjunto de declarações básicasBasic claim set Inclui as declarações que são emitidas por padrão para os tokens (além do conjunto de declarações principais).Includes the claims that are emitted by default for tokens (in addition to the core claim set). Você pode omitir ou modificar as declarações básicas usando as políticas de mapeamento de declarações.You can omit or modify basic claims by using the claims mapping policies.
Conjunto de declarações restritasRestricted claim set Não pode ser modificado usando a política.Can't be modified using policy. A fonte de dados não pode ser alterada e nenhuma transformação é aplicada ao gerar essas declarações.The data source cannot be changed, and no transformation is applied when generating these claims.

Tabela 1: Conjunto de declarações restritas do JWT (Token Web JSON)Table 1: JSON Web Token (JWT) restricted claim set

Tipo de declaração (nome)Claim type (name)
_claim_names_claim_names
_claim_sources_claim_sources
access_tokenaccess_token
account_typeaccount_type
acracr
actoractor
actortokenactortoken
aioaio
altsecidaltsecid
amramr
app_chainapp_chain
app_displaynameapp_displayname
app_resapp_res
appctxappctx
appctxsenderappctxsender
appidappid
appidacrappidacr
asserçãoassertion
at_hashat_hash
audaud
auth_dataauth_data
auth_timeauth_time
authorization_codeauthorization_code
azpazp
azpacrazpacr
c_hashc_hash
ca_enfca_enf
cccc
cert_token_usecert_token_use
client_idclient_id
cloud_graph_host_namecloud_graph_host_name
cloud_instance_namecloud_instance_name
cnfcnf
códigocode
controlscontrols
credential_keyscredential_keys
csrcsr
csr_typecsr_type
deviceiddeviceid
dns_namesdns_names
domain_dns_namedomain_dns_name
domain_netbios_namedomain_netbios_name
e_expe_exp
emailemail
endpointendpoint
enfpolidsenfpolids
expexp
expires_onexpires_on
grant_typegrant_type
grafograph
group_sidsgroup_sids
de recursosgroups
hasgroupshasgroups
hash_alghash_alg
home_oidhome_oid
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
http://schemas.microsoft.com/ws/2008/06/identity/claims/expiration
http://schemas.microsoft.com/ws/2008/06/identity/claims/expired
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
iatiat
identityprovideridentityprovider
idpidp
in_corpin_corp
instanceinstance
ipaddripaddr
isbrowserhostedappisbrowserhostedapp
ississ
jwkjwk
key_idkey_id
key_typekey_type
mam_compliance_urlmam_compliance_url
mam_enrollment_urlmam_enrollment_url
mam_terms_of_use_urlmam_terms_of_use_url
mdm_compliance_urlmdm_compliance_url
mdm_enrollment_urlmdm_enrollment_url
mdm_terms_of_use_urlmdm_terms_of_use_url
nameidnameid
nbfnbf
netbios_namenetbios_name
noncenonce
oidoid
on_prem_idon_prem_id
onprem_sam_account_nameonprem_sam_account_name
onprem_sidonprem_sid
openid2_idopenid2_id
passwordpassword
platfplatf
polidspolids
pop_jwkpop_jwk
preferred_usernamepreferred_username
previous_refresh_tokenprevious_refresh_token
primary_sidprimary_sid
puidpuid
pwd_exppwd_exp
pwd_urlpwd_url
redirect_uriredirect_uri
refresh_tokenrefresh_token
refreshtokenrefreshtoken
request_noncerequest_nonce
recursoresource
funçãorole
rolesroles
scopescope
scpscp
sidsid
assinaturasignature
signin_statesignin_state
src1src1
src2src2
subsub
tbidtbid
tenant_display_nametenant_display_name
tenant_region_scopetenant_region_scope
thumbnail_photothumbnail_photo
tidtid
tokenAutologonEnabledtokenAutologonEnabled
trustedfordelegationtrustedfordelegation
unique_nameunique_name
upnupn
user_setting_sync_urluser_setting_sync_url
Nome de Usuáriousername
utiuti
verver
verified_primary_emailverified_primary_email
verified_secondary_emailverified_secondary_email
widswids
win_verwin_ver

Tabela 2: conjunto de declarações restritas do SAMLTable 2: SAML restricted claim set

Tipo de declaração (URI)Claim type (URI)
http://schemas.microsoft.com/ws/2008/06/identity/claims/expiration
http://schemas.microsoft.com/ws/2008/06/identity/claims/expired
http://schemas.microsoft.com/identity/claims/accesstoken
http://schemas.microsoft.com/identity/claims/openid2_id
http://schemas.microsoft.com/identity/claims/identityprovider
http://schemas.microsoft.com/identity/claims/objectidentifier
http://schemas.microsoft.com/identity/claims/puid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier [MR1]
http://schemas.microsoft.com/identity/claims/tenantid
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
http://schemas.microsoft.com/accesscontrolservice/2010/07/claims/identityprovider
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
http://schemas.microsoft.com/claims/groups.link
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
http://schemas.microsoft.com/ws/2008/06/identity/claims/wids
http://schemas.microsoft.com/2014/09/devicecontext/claims/iscompliant
http://schemas.microsoft.com/2014/02/devicecontext/claims/isknown
http://schemas.microsoft.com/2012/01/devicecontext/claims/ismanaged
http://schemas.microsoft.com/2014/03/psso
http://schemas.microsoft.com/claims/authnmethodsreferences
http://schemas.xmlsoap.org/ws/2009/09/identity/claims/actor
http://schemas.microsoft.com/ws/2008/06/identity/claims/samlissuername
http://schemas.microsoft.com/ws/2008/06/identity/claims/confirmationkey
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/authorizationdecision
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/authentication
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/sid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarygroupsid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlyprimarysid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/denyonlysid
http://schemas.microsoft.com/ws/2008/06/identity/claims/denyonlywindowsdevicegroup
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsdeviceclaim
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsdevicegroup
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsfqbnversion
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowssubauthority
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsuserclaim
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/x500distinguishedname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/spn
http://schemas.microsoft.com/ws/2008/06/identity/claims/ispersistent
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
http://schemas.microsoft.com/identity/claims/scope

Propriedades da política de mapeamento de declaraçõesClaims mapping policy properties

Para controlar quais declarações são emitidas e o local em que os dados são originados, use as propriedades de uma política de mapeamento de declarações.To control what claims are emitted and where the data comes from, use the properties of a claims mapping policy. Se uma política não for definida, o sistema emitirá tokens que incluam o conjunto de declarações principais, o conjunto de declarações básicas e quaisquer declarações adicionais que o aplicativo optou por receber.If a policy is not set, the system issues tokens that include the core claim set, the basic claim set, and any optional claims that the application has chosen to receive.

Incluir um conjunto de declarações básicasInclude basic claim set

Cadeia de caracteres: IncludeBasicClaimSetString: IncludeBasicClaimSet

Tipo de dados: booliano (True ou False)Data type: Boolean (True or False)

Resumo: essa propriedade determina se o conjunto de declarações básicas está incluído nos tokens afetados por essa política.Summary: This property determines whether the basic claim set is included in tokens affected by this policy.

  • Se definido como True, todas as declarações no conjunto de declarações básicas serão emitidas nos tokens afetados pela política.If set to True, all claims in the basic claim set are emitted in tokens affected by the policy.
  • Se definido como False, as declarações no conjunto de declarações básicas não estarão nos tokens, a menos sejam adicionadas individualmente na propriedade de esquema de declarações da mesma política.If set to False, claims in the basic claim set are not in the tokens, unless they are individually added in the claims schema property of the same policy.

Observação

As declarações no conjunto de declarações de núcleo estão presentes em todos os tokens, independentemente de como essa propriedade estiver definida.Claims in the core claim set are present in every token, regardless of what this property is set to.

Esquema de declaraçõesClaims schema

Cadeia de caracteres: ClaimsSchemaString: ClaimsSchema

Tipo de dados: blob JSON com uma ou mais entradas de esquema de declaraçãoData type: JSON blob with one or more claim schema entries

Resumo: esta propriedade define quais declarações estão presentes nos tokens afetados pela política, além do conjunto de declarações básicas e do conjunto de declarações de núcleo.Summary: This property defines which claims are present in the tokens affected by the policy, in addition to the basic claim set and the core claim set. Para cada entrada de esquema de declaração definida nesta propriedade, certas informações são necessárias.For each claim schema entry defined in this property, certain information is required. Especifique o local em que os dados são originados (Valor ou o par Origem/ID) e com qual declaração eles são emitidos (Tipo de declaração).Specify where the data is coming from (Value or Source/ID pair), and which claim the data is emitted as (Claim Type).

Elementos de entrada do esquema de declaraçãoClaim schema entry elements

Valor: o elemento de valor define um valor estático como os dados a serem emitidos na declaração.Value: The Value element defines a static value as the data to be emitted in the claim.

Par Origem/ID: os elementos de Origem e ID definem de onde os dados na declaração foram originados.Source/ID pair: The Source and ID elements define where the data in the claim is sourced from.

Defina o elemento Origem para um dos seguintes valores:Set the Source element to one of the following values:

  • "user": os dados na declaração são uma propriedade no objeto User."user": The data in the claim is a property on the User object.
  • "application": os dados na declaração são uma propriedade na entidade de serviço de aplicativo (cliente)."application": The data in the claim is a property on the application (client) service principal.
  • "resource": os dados na declaração são uma propriedade na entidade de serviço de recurso."resource": The data in the claim is a property on the resource service principal.
  • "audience": os dados na declaração são uma propriedade da entidade de serviço que é o público-alvo do token (o cliente ou o recurso de entidade de serviço)."audience": The data in the claim is a property on the service principal that is the audience of the token (either the client or resource service principal).
  • "company": os dados na declaração são uma propriedade do objeto Company do locatário do recurso.“company”: The data in the claim is a property on the resource tenant’s Company object.
  • "transformation": os dados na declaração são de uma transformação de declarações (consulte a seção "Transformação de declarações" mais adiante neste artigo)."transformation": The data in the claim is from claims transformation (see the "Claims transformation" section later in this article).

Se a fonte for uma transformação, o elemento TransformationID deverá ser incluído na definição de declaração.If the source is transformation, the TransformationID element must be included in this claim definition as well.

O elemento ID identifica qual propriedade na origem fornece o valor da declaração.The ID element identifies which property on the source provides the value for the claim. A tabela a seguir lista os valores de ID válida para cada valor de Origem.The following table lists the values of ID valid for each value of Source.

Tabela 3: Valores de ID válida por origemTable 3: Valid ID values per source

OrigemSource IDID DescriptionDescription
UsuárioUser sobrenomesurname Nome da famíliaFamily Name
UsuárioUser givennamegivenname NomeGiven Name
UsuárioUser displaynamedisplayname Nome de exibiçãoDisplay Name
UsuárioUser objectidobjectid ObjectIDObjectID
UsuárioUser mailmail Endereço de EmailEmail Address
UsuárioUser userprincipalnameuserprincipalname Nome UPNUser Principal Name
UsuárioUser departmentdepartment departmentDepartment
UsuárioUser onpremisessamaccountnameonpremisessamaccountname Nome da conta SAM localOn-premises SAM Account Name
UsuárioUser netbiosnamenetbiosname Nome NetBiosNetBios Name
UsuárioUser dnsdomainnamednsdomainname Nome de Domínio DNSDNS Domain Name
UsuárioUser onpremisesecurityidentifieronpremisesecurityidentifier Identificador de segurança localOn-premises Security Identifier
UsuárioUser companynamecompanyname Nome da OrganizaçãoOrganization Name
UsuárioUser streetaddressstreetaddress EndereçoStreet Address
UsuárioUser postalcodepostalcode Código postalPostal Code
UsuárioUser preferredlanguangepreferredlanguange Idioma preferencialPreferred Language
UsuárioUser onpremisesuserprincipalnameonpremisesuserprincipalname UPN localOn-premises UPN
UsuárioUser mailNicknamemailnickname Apelido de emailMail Nickname
UsuárioUser extensionattribute1extensionattribute1 Atributo de extensão 1Extension Attribute 1
UsuárioUser extensionattribute2extensionattribute2 Atributo de extensão 2Extension Attribute 2
UsuárioUser extensionattribute3extensionattribute3 Atributo de extensão 3Extension Attribute 3
UsuárioUser extensionattribute4extensionattribute4 Atributo de extensão 4Extension Attribute 4
UsuárioUser extensionattribute5extensionattribute5 Atributo de extensão 5Extension Attribute 5
UsuárioUser extensionattribute6extensionattribute6 Atributo de extensão 6Extension Attribute 6
UsuárioUser extensionattribute7extensionattribute7 Atributo de extensão 7Extension Attribute 7
UsuárioUser extensionattribute8extensionattribute8 Atributo de extensão 8Extension Attribute 8
UsuárioUser extensionattribute9extensionattribute9 Atributo de extensão 9Extension Attribute 9
UsuárioUser extensionattribute10extensionattribute10 Atributo de extensão 10Extension Attribute 10
UsuárioUser extensionattribute11extensionattribute11 Atributo de extensão 11Extension Attribute 11
UsuárioUser extensionattribute12extensionattribute12 Atributo de extensão 12Extension Attribute 12
UsuárioUser extensionattribute13extensionattribute13 Atributo de extensão 13Extension Attribute 13
UsuárioUser extensionattribute14extensionattribute14 Atributo de extensão 14Extension Attribute 14
UsuárioUser extensionattribute15extensionattribute15 Atributo de extensão 15Extension Attribute 15
UsuárioUser othermailothermail Outro emailOther Mail
UsuárioUser countrycountry PaísCountry
UsuárioUser citycity CidadeCity
UsuárioUser statestate EstadoState
UsuárioUser jobtitlejobtitle CargoJob Title
UsuárioUser employeeidemployeeid ID do funcionárioEmployee ID
UsuárioUser facsimiletelephonenumberfacsimiletelephonenumber Número de telefone de faxFacsimile Telephone Number
aplicativo, recurso, público-alvoapplication, resource, audience displaynamedisplayname Nome de exibiçãoDisplay Name
aplicativo, recurso, público-alvoapplication, resource, audience objectedobjected ObjectIDObjectID
aplicativo, recurso, público-alvoapplication, resource, audience marcastags Marcação da entidade de serviçoService Principal Tag
EmpresaCompany tenantcountrytenantcountry País/Região do locatárioTenant’s country

TransformationID: o elemento TransformationID deverá ser fornecido apenas se o elemento de origem estiver definido como "transformation".TransformationID: The TransformationID element must be provided only if the Source element is set to “transformation”.

  • Esse elemento deve corresponder ao elemento de ID da entrada de transformação na propriedade ClaimsTransformation que define como os dados dessa declaração são gerados.This element must match the ID element of the transformation entry in the ClaimsTransformation property that defines how the data for this claim is generated.

Tipo de declaração: os elementos JwtClaimType e SamlClaimType definem a quais declarações essa entrada de esquema de declaração se refere.Claim Type: The JwtClaimType and SamlClaimType elements define which claim this claim schema entry refers to.

  • O JwtClaimType deve conter o nome da declaração a ser emitida em JWTs.The JwtClaimType must contain the name of the claim to be emitted in JWTs.
  • O SamlClaimType deve conter o URI da declaração a ser emitida em tokens SAML.The SamlClaimType must contain the URI of the claim to be emitted in SAML tokens.

Observação

Nomes e URIs de declarações no conjunto de declaração restritas não podem ser usados para os elementos de tipo de declaração.Names and URIs of claims in the restricted claim set cannot be used for the claim type elements. Para obter mais informações, consulte a seção "Restrições e exceções" mais adiante neste artigo.For more information, see the "Exceptions and restrictions" section later in this article.

Transformação de declaraçõesClaims transformation

Cadeia de caracteres: ClaimsTransformationString: ClaimsTransformation

Tipo de dados: blob JSON com uma ou mais entradas de transformaçãoData type: JSON blob, with one or more transformation entries

Resumo: use esta propriedade para aplicar transformações comuns a dados de origem para gerar os dados de saída para declarações especificadas no esquema de declarações.Summary: Use this property to apply common transformations to source data, to generate the output data for claims specified in the Claims Schema.

ID: use o elemento de ID para fazer referência a esta entrada de transformação na entrada de esquema de transformações TransformationID.ID: Use the ID element to reference this transformation entry in the TransformationID Claims Schema entry. Esse valor deve ser exclusivo para cada entrada de transformação nesta política.This value must be unique for each transformation entry within this policy.

TransformationMethod: o elemento TransformationMethod identifica qual operação é executada para gerar os dados para a declaração.TransformationMethod: The TransformationMethod element identifies which operation is performed to generate the data for the claim.

Com base no método escolhido, um conjunto de entradas e saídas é esperado.Based on the method chosen, a set of inputs and outputs is expected. Defina as entradas e as saídas usando os elementos InputClaims, InputParameters e OutputClaims.Define the inputs and outputs by using the InputClaims, InputParameters and OutputClaims elements.

Tabela 4: Métodos de transformação e entradas e saídas esperadasTable 4: Transformation methods and expected inputs and outputs

TransformationMethodTransformationMethod Entrada esperadaExpected input Saída esperadaExpected output DescriptionDescription
JoinJoin cadeia1, cadeia2, separadorstring1, string2, separator outputClaimoutputClaim Une cadeias de entrada usando um separador entre elas.Joins input strings by using a separator in between. Por exemplo: cadeia1: "foo@bar.com", cadeia2: "sandbox", separador: "." resulta no outputClaim: "foo@bar.com.sandbox"For example: string1:"foo@bar.com" , string2:"sandbox" , separator:"." results in outputClaim:"foo@bar.com.sandbox"
ExtractMailPrefixExtractMailPrefix mailmail outputClaimoutputClaim Extrai a parte local do endereço de email.Extracts the local part of an email address. Por exemplo: email: "foo@bar.com" resulta no outputClaim: "foo".For example: mail:"foo@bar.com" results in outputClaim:"foo". Se não houver nenhum sinal @ presente, a cadeia de caracteres de entrada original será retornada sem alterações.If no @ sign is present, then the original input string is returned as is.

InputClaims: use um elemento InputClaims para passar os dados de uma entrada de esquema de declaração para uma transformação.InputClaims: Use an InputClaims element to pass the data from a claim schema entry to a transformation. Ele tem dois atributos: ClaimTypeReferenceId e TransformationClaimType.It has two attributes: ClaimTypeReferenceId and TransformationClaimType.

  • ClaimTypeReferenceId é unido ao elemento de ID da entrada de esquema de declaração para encontrar a declaração de entrada apropriada.ClaimTypeReferenceId is joined with ID element of the claim schema entry to find the appropriate input claim.
  • TransformationClaimType é usado para fornecer um nome exclusivo a essa entrada.TransformationClaimType is used to give a unique name to this input. Esse nome deve corresponder a uma das entradas esperadas para o método de transformação.This name must match one of the expected inputs for the transformation method.

InputParameters: use um elemento InputParameters para passar um valor constante para uma transformação.InputParameters: Use an InputParameters element to pass a constant value to a transformation. Ele tem dois atributos: Value e ID.It has two attributes: Value and ID.

  • Value é o valor constante real a ser passado.Value is the actual constant value to be passed.
  • O elemento ID é usado para fornecer um nome exclusivo a essa entrada.ID is used to give a unique name to the input. O nome deve corresponder a uma das entradas esperadas para o método de transformação.The name must match one of the expected inputs for the transformation method.

OutputClaims: usam um elemento OutputClaims para armazenar os dados gerados por uma transformação e associá-lo a uma entrada de esquema de declaração.OutputClaims: Use an OutputClaims element to hold the data generated by a transformation, and tie it to a claim schema entry. Ele tem dois atributos: ClaimTypeReferenceId e TransformationClaimType.It has two attributes: ClaimTypeReferenceId and TransformationClaimType.

  • ClaimTypeReferenceId é unido à ID da entrada de esquema de declaração para encontrar a declaração de saída apropriada.ClaimTypeReferenceId is joined with the ID of the claim schema entry to find the appropriate output claim.
  • TransformationClaimType é usado para fornecer um nome exclusivo à saída.TransformationClaimType is used to give a unique name to the output. O nome deve corresponder a uma das saídas esperadas para o método de transformação.The name must match one of the expected outputs for the transformation method.

Exceções e restriçõesExceptions and restrictions

NameID e UPN SAML: os atributos dos quais você obtém os valores de NameID e UPN, bem como as transformações de declarações que são permitidas, são limitados.SAML NameID and UPN: The attributes from which you source the NameID and UPN values, and the claims transformations that are permitted, are limited. Consulte as tabelas 5 e 6 para ver os valores permitidos.See table 5 and table 6 to see the permitted values.

Tabela 5: Atributos permitidos como fonte de dados para NameID SAMLTable 5: Attributes allowed as a data source for SAML NameID

OrigemSource IDID DescriptionDescription
UsuárioUser mailmail Endereço de EmailEmail Address
UsuárioUser userprincipalnameuserprincipalname Nome UPNUser Principal Name
UsuárioUser onpremisessamaccountnameonpremisessamaccountname Nome da conta SAM localOn Premises Sam Account Name
UsuárioUser employeeidemployeeid ID do funcionárioEmployee ID
UsuárioUser extensionattribute1extensionattribute1 Atributo de extensão 1Extension Attribute 1
UsuárioUser extensionattribute2extensionattribute2 Atributo de extensão 2Extension Attribute 2
UsuárioUser extensionattribute3extensionattribute3 Atributo de extensão 3Extension Attribute 3
UsuárioUser extensionattribute4extensionattribute4 Atributo de extensão 4Extension Attribute 4
UsuárioUser extensionattribute5extensionattribute5 Atributo de extensão 5Extension Attribute 5
UsuárioUser extensionattribute6extensionattribute6 Atributo de extensão 6Extension Attribute 6
UsuárioUser extensionattribute7extensionattribute7 Atributo de extensão 7Extension Attribute 7
UsuárioUser extensionattribute8extensionattribute8 Atributo de extensão 8Extension Attribute 8
UsuárioUser extensionattribute9extensionattribute9 Atributo de extensão 9Extension Attribute 9
UsuárioUser extensionattribute10extensionattribute10 Atributo de extensão 10Extension Attribute 10
UsuárioUser extensionattribute11extensionattribute11 Atributo de extensão 11Extension Attribute 11
UsuárioUser extensionattribute12extensionattribute12 Atributo de extensão 12Extension Attribute 12
UsuárioUser extensionattribute13extensionattribute13 Atributo de extensão 13Extension Attribute 13
UsuárioUser extensionattribute14extensionattribute14 Atributo de extensão 14Extension Attribute 14
UsuárioUser extensionattribute15extensionattribute15 Atributo de extensão 15Extension Attribute 15

Tabela 6: Métodos de transformação permitidos para o NameID SAMLTable 6: Transformation methods allowed for SAML NameID

TransformationMethodTransformationMethod RestriçõesRestrictions
ExtractMailPrefixExtractMailPrefix NenhumNone
JoinJoin O sufixo que está sendo acrescentado deve ser um domínio verificado do locatário do recurso.The suffix being joined must be a verified domain of the resource tenant.

Chave de assinatura personalizadaCustom signing key

Uma chave de assinatura personalizada deve ser atribuída ao objeto de entidade de serviço para que uma política de mapeamento de declarações entre em vigor.A custom signing key must be assigned to the service principal object for a claims mapping policy to take effect. Isso garante a confirmação de que os tokens foram modificados pelo criador da política de mapeamento de declarações e protege os aplicativos contra as políticas de mapeamento de declarações criadas por atores mal-intencionados.This ensures acknowledgment that tokens have been modified by the creator of the claims mapping policy and protects applications from claims mapping policies created by malicious actors. Para adicionar uma chave de assinatura personalizada, você pode usar o cmdlet do Azure PowerShell new-azureadapplicationkeycredential para criar uma credencial de chave simétrica para seu objeto de aplicativo.In order to add a custom signing key, you can use the Azure Powershell cmdlet new-azureadapplicationkeycredential to create a symmetric key credential for your Application object. Para obter mais informações sobre este cmdlet do Azure PowerShell, clique aqui.For more information on this Azure Powershell cmdlet click here.

Os aplicativos que têm o mapeamento de declarações habilitado devem validar suas chaves de assinatura de token acrescentando appid={client_id} às suas solicitações de metadados do OpenID Connect.Apps that have claims mapping enabled must validate their token signing keys by appending appid={client_id} to their OpenID Connect metadata requests. Abaixo está o formato do documento de metadados do OpenID Connect que você deve usar:Below is the format of the OpenID Connect metadata document you should use:

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

Cenários entre locatáriosCross-tenant scenarios

As políticas de mapeamento de declarações não se aplicam a usuários convidados.Claims mapping policies do not apply to guest users. Se um usuário convidado tentar acessar um aplicativo com uma política de mapeamento de declarações atribuída à sua entidade de serviço, o token padrão será emitido (a política não terá efeito).If a guest user tries to access an application with a claims mapping policy assigned to its service principal, the default token is issued (the policy has no effect).

Atribuição de política de mapeamento de declaraçõesClaims mapping policy assignment

Políticas de mapeamento de declarações podem ser atribuídas somente a objetos de entidade de serviço.Claims mapping policies can only be assigned to service principal objects.

Exemplos de políticas de mapeamento de declaraçõesExample claims mapping policies

No Azure AD, muitos cenários são possíveis quando você pode personalizar as declarações emitidas em tokens para entidades de serviço específicas.In Azure AD, many scenarios are possible when you can customize claims emitted in tokens for specific service principals. Nesta seção, percorremos alguns cenários comuns que podem ajudá-lo a entender como usar o tipo de política de mapeamento de declarações.In this section, we walk through a few common scenarios that can help you grasp how to use the claims mapping policy type.

Pré-requisitosPrerequisites

Nos exemplos a seguir, você cria, atualiza, vincula e exclui políticas de entidades de serviço.In the following examples, you create, update, link, and delete policies for service principals. Se você é um novo usuário do Azure AD, recomendamos que aprenda como obter um locatário do Azure AD antes de prosseguir com estes exemplos.If you are new to Azure AD, we recommend that you learn about how to get an Azure AD tenant before you proceed with these examples.

Para começar, execute uma destas etapas:To get started, do the following steps:

  1. Baixe a versão mais recente da Visualização pública do módulo do Azure AD PowerShell.Download the latest Azure AD PowerShell Module public preview release.

  2. Execute o comando Connect para entrar em sua conta do administrador do Azure AD.Run the Connect command to sign in to your Azure AD admin account. Execute esse comando sempre que você iniciar uma nova sessão.Run this command each time you start a new session.

    Connect-AzureAD -Confirm
    
  3. Para ver todas as políticas criadas em sua organização, execute o comando a seguir.To see all policies that have been created in your organization, run the following command. É recomendável que você execute esse comando após a maioria das operações nos cenários a seguir, a fim de verificar se as políticas estão sendo criadas conforme o esperado.We recommend that you run this command after most operations in the following scenarios, to check that your policies are being created as expected.

    Get-AzureADPolicy
    

Exemplo: criar e atribuir uma política para omitir as declarações básicas de tokens emitidos para uma entidade de serviçoExample: Create and assign a policy to omit the basic claims from tokens issued to a service principal

Neste exemplo, você cria uma política que remove o conjunto de declarações básicas de tokens emitidos para entidades de serviço vinculadas.In this example, you create a policy that removes the basic claim set from tokens issued to linked service principals.

  1. Crie uma política de mapeamento de declarações.Create a claims mapping policy. Essa política, vinculada a entidades de serviço específicas, remove o conjunto de declarações básicas do token.This policy, linked to specific service principals, removes the basic claim set from tokens.
    1. Para criar a política, execute este comando:To create the policy, run this command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"false"}}') -DisplayName "OmitBasicClaims" -Type "ClaimsMappingPolicy"
      
    2. Para ver a nova política e obter a ObjectId da política, execute o comando a seguir:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. Atribuir a política à entidade de serviço.Assign the policy to your service principal. Você também precisará da ObjectId de sua entidade de serviço.You also need to get the ObjectId of your service principal.
    1. Para ver todas as entidades de serviço de sua organização, você pode consultar Microsoft Graph.To see all your organization's service principals, you can query Microsoft Graph. Ou, no Graph Explorer, entre em sua conta do Azure AD.Or, in Graph Explorer, sign in to your Azure AD account.

    2. Quando você tiver a ObjectId de sua entidade de serviço, execute o seguinte comando:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

Exemplo: criar e atribuir uma política para incluir EmployeeID e TenantCountry como declarações em tokens emitidos para uma entidade de serviçoExample: Create and assign a policy to include the EmployeeID and TenantCountry as claims in tokens issued to a service principal

Neste exemplo, você cria uma política que adiciona EmployeeID e TenantCountry a tokens emitidos para entidades de serviço vinculadas.In this example, you create a policy that adds the EmployeeID and TenantCountry to tokens issued to linked service principals. EmployeeID é emitido como o tipo de declaração de nome em tokens SAML e JWTs.The EmployeeID is emitted as the name claim type in both SAML tokens and JWTs. TenantCountry é emitido como o tipo de declaração de país em tokens SAML e JWTs.The TenantCountry is emitted as the country claim type in both SAML tokens and JWTs. Neste exemplo, continuamos incluindo o conjunto de declarações básicas nos tokens.In this example, we continue to include the basic claims set in the tokens.

  1. Crie uma política de mapeamento de declarações.Create a claims mapping policy. Essa política, vinculada a entidades de serviço específicas, adiciona as declarações de EmployeeID e TenantCountry em tokens.This policy, linked to specific service principals, adds the EmployeeID and TenantCountry claims to tokens.
    1. Para criar a política, execute o seguinte comando:To create the policy, run the following command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"employeeid","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name","JwtClaimType":"name"},{"Source":"company","ID":"tenantcountry","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country","JwtClaimType":"country"}]}}') -DisplayName "ExtraClaimsExample" -Type "ClaimsMappingPolicy"
      
    2. Para ver a nova política e obter a ObjectId da política, execute o comando a seguir:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. Atribuir a política à entidade de serviço.Assign the policy to your service principal. Você também precisará da ObjectId de sua entidade de serviço.You also need to get the ObjectId of your service principal.
    1. Para ver todas as entidades de serviço de sua organização, você pode consultar Microsoft Graph.To see all your organization's service principals, you can query Microsoft Graph. Ou, no Graph Explorer, entre em sua conta do Azure AD.Or, in Graph Explorer, sign in to your Azure AD account.

    2. Quando você tiver a ObjectId de sua entidade de serviço, execute o seguinte comando:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

Exemplo: criar e atribuir uma política que usa uma transformação de declarações em tokens emitidos para uma entidade de serviçoExample: Create and assign a policy that uses a claims transformation in tokens issued to a service principal

Neste exemplo, você cria uma política que emite uma declaração personalizada “JoinedData” para JWTs emitidos para entidades de serviço vinculadas.In this example, you create a policy that emits a custom claim “JoinedData” to JWTs issued to linked service principals. Esta declaração contém um valor criado unindo os dados armazenados no atributo extensionattribute1 no objeto do usuário com ".sandbox".This claim contains a value created by joining the data stored in the extensionattribute1 attribute on the user object with “.sandbox”. Neste exemplo, excluímos o conjunto de declarações básicas nos tokens.In this example, we exclude the basic claims set in the tokens.

  1. Crie uma política de mapeamento de declarações.Create a claims mapping policy. Essa política, vinculada a entidades de serviço específicas, adiciona as declarações de EmployeeID e TenantCountry em tokens.This policy, linked to specific service principals, adds the EmployeeID and TenantCountry claims to tokens.
    1. Para criar a política, execute o seguinte comando:To create the policy, run the following command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema":[{"Source":"user","ID":"extensionattribute1"},{"Source":"transformation","ID":"DataJoin","TransformationId":"JoinTheData","JwtClaimType":"JoinedData"}],"ClaimsTransformations":[{"ID":"JoinTheData","TransformationMethod":"Join","InputClaims":[{"ClaimTypeReferenceId":"extensionattribute1","TransformationClaimType":"string1"}], "InputParameters": [{"ID":"string2","Value":"sandbox"},{"ID":"separator","Value":"."}],"OutputClaims":[{"ClaimTypeReferenceId":"DataJoin","TransformationClaimType":"outputClaim"}]}]}}') -DisplayName "TransformClaimsExample" -Type "ClaimsMappingPolicy"
      
    2. Para ver a nova política e obter a ObjectId da política, execute o comando a seguir:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. Atribuir a política à entidade de serviço.Assign the policy to your service principal. Você também precisará da ObjectId de sua entidade de serviço.You also need to get the ObjectId of your service principal.
    1. Para ver todas as entidades de serviço de sua organização, você pode consultar Microsoft Graph.To see all your organization's service principals, you can query Microsoft Graph. Ou, no Graph Explorer, entre em sua conta do Azure AD.Or, in Graph Explorer, sign in to your Azure AD account.

    2. Quando você tiver a ObjectId de sua entidade de serviço, execute o seguinte comando:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

Consulte tambémSee also

Para saber como personalizar as declarações emitidas no token SAML por meio do portal do Azure, consulte como: Personalizar declarações emitidas no token SAML para aplicativos empresariaisTo learn how to customize claims issued in the SAML token through the Azure portal, see How to: Customize claims issued in the SAML token for enterprise applications