Mapeamento de Claims

Importância do Mapeamento de Claims

Em cenários de federação de identidade, o mapeamento de claims permite:

• Fornecer atributos específicos do utilizador à aplicação
• Personalizar tokens para requisitos específicos da aplicação
• Incluir dados de fontes personalizadas
• Transformar dados para formatos esperados pelo destino
• Implementar lógica de decisão baseada em atributos

O Microsoft Entra ID oferece recursos robustos para mapeamento de claims tanto para tokens SAML como para tokens JWT (OAuth2/OIDC).

Configuração via Microsoft Graph API

Para configurar mapeamentos de claims em aplicações SAML:

# Conectar ao Microsoft Graph
Connect-MgGraph -Scopes "Application.ReadWrite.All"

# ID da aplicação a modificar
$appId = "11111111-1111-1111-1111-111111111111"

# Obter o objeto da aplicação
$app = Get-MgApplication -Filter "appId eq '$appId'"

# Definir os mapeamentos de claims SAML
$claimsMappings = @(
    @{
        name = "EmployeeId"
        source = "user"
        saml = @{
            attributeName = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid"
            attributeNamespace = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims"
        }
    },
    @{
        name = "Department"
        source = "user"
        saml = @{
            attributeName = "department"
            attributeNamespace = "http://schemas.contoso.com/identity/claims"
        }
    }
)

# Atualizar configuração SAML da aplicação
$samlConfiguration = @{
    mappedClaims = $claimsMappings
}

# Aplicar a configuração
Update-MgApplication -ApplicationId $app.Id -SamlMetadataUrl $app.SamlMetadataUrl -SamlSingleSignOnSettings @{
    relayState = $null
}

Para configurações mais avançadas, como mapeamentos baseados em grupos ou expressões condicionais:

# Mapeamento avançado com condições
$advancedMappings = @(
    @{
        name = "Role"
        source = "group"
        saml = @{
            attributeName = "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
            attributeNamespace = "http://schemas.microsoft.com/ws/2008/06/identity"
        }
        sourceFilter = @("11111111-1111-1111-1111-111111111111", "22222222-2222-2222-2222-222222222222")
    },
    @{
        name = "Country"
        source = "transformation"
        saml = @{
            attributeName = "country"
            attributeNamespace = "http://schemas.contoso.com/identity/claims"
        }
        transformationMethod = "ExtractCountryFromAddress"
    }
)

Mapeamento para Tokens JWT (OAuth2/OIDC)

Para aplicações que usam OAuth2/OIDC:

# Definir mapeamentos personalizados para JWT
$optionalClaims = @{
    idToken = @(
        @{
            name = "employeeid"
            source = "user"
            essential = $false
            additionalProperties = @("emit_as_roles")
        },
        @{
            name = "extension_CustomAttribute"
            source = "user"
            essential = $false
        }
    )
    accessToken = @(
        @{
            name = "department"
            source = "user"
            essential = $false
        }
    )
}

# Atualizar a aplicação
Update-MgApplication -ApplicationId $app.Id -OptionalClaims $optionalClaims

Casos de Uso Comuns

Enviar Membros de Grupo como Funções (Roles)

# Mapeamento de grupos para roles
$groupsAsRolesClaim = @{
    name = "groups"
    source = "user"
    saml = @{
        attributeName = "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
        attributeNamespace = "http://schemas.microsoft.com/ws/2008/06/identity"
    }
    additionalProperties = @("emit_as_roles")
}

Inclusão de Atributos de Extensão

# Atributos de extensão
$extensionClaim = @{
    name = "extension_ab603c56068041afb2f6832e2a17e237_EmployeeType"
    source = "user"
    saml = @{
        attributeName = "EmployeeType"
        attributeNamespace = "http://schemas.contoso.com/identity/claims"
    }
}

Transformação de Valores

# Exemplo de transformação simples (maiúsculas)
$transformedClaim = @{
    name = "mailNickname"
    source = "transformation"
    saml = @{
        attributeName = "LoginName"
        attributeNamespace = "http://schemas.contoso.com/identity/claims"
    }
    transformationMethod = "ToUpperCase"
}

Validação do Mapeamento

Para validar configurações de mapeamento:

# Testar token SAML
$testUser = "user@contoso.com"
$samlToken = Get-MgApplicationSamlToken -ApplicationId $app.Id -UserId $testUser

# Mostrar claims mapeadas no token
$samlToken.Claims | Where-Object { $_.Type -like "*department*" -or $_.Type -like "*role*" }

Considerações Importantes

• Atributos de extensão devem incluir o prefixo completo (extension_[app-id]_AttributeName)
• Mapeamentos de grupos podem ter impacto no tamanho do token (considere usar funções de aplicação para grandes conjuntos)
• Tokens SAML têm limitações de tamanho (~50KB), evite incluir grandes quantidades de dados
• Transformações complexas podem requerer a criação de políticas personalizadas

Melhores Práticas

• Documente claramente todos os mapeamentos de claims configurados
• Minimize dados sensíveis em tokens para seguir o princípio de privilégio mínimo
• Teste mapeamentos com múltiplos perfis de utilizadores para garantir consistência
• Considere o impacto em aplicações existentes ao modificar mapeamentos
• Use convenções de nomenclatura consistentes para atributos personalizados