Criar um aplicativo de cliente externo

Nota

Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e use as traduções fornecidas entre parênteses para navegar. Copie e cole somente os valores em inglês porque as validações dos desafios dependem de dados em inglês. Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.

Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.

Criar um projeto do SFDX

Agora que seu ambiente está configurado, é hora de criar seu aplicativo de cliente externo. Para isso, você precisará de um projeto do SFDX.

1. Crie uma pasta chamada ECA Metadata (Metadados ECA) no computador onde você queira criar o aplicativo.
   
2. Abra a pasta no VS Code.
   
3. Abra o terminal no VS Code na pasta que você criou.
   
4. Execute este comando no terminal para criar um projeto do Salesforce DX chamado ecaViaMetadata com o modelo padrão.
   

sf project generate --name ecaViaMetadata --template standard

Autorizar sua organização Dev Hub

Conecte o projeto do SFDX no seu computador ao Dev Hub do Trailhead Playground usando o aplicativo conectado. Você precisará do seu domínio nesta etapa. Para encontrar seu domínio em Setup (Configuração), insira My Domain (Meu domínio) na caixa Quick Find (Busca rápida) e clique em My Domain (Meu domínio).

1. Abra a pasta ECA Metadata do projeto do SFDX no VS Code.
   
2. No terminal do VS Code, execute este comando depois de substituir <my domain> pelo domínio da sua organização.
   

sf org login web --set-default-dev-hub --alias ecaViaMetadata --instance-url https://<my domain>

3. Faça login com as credenciais do seu Trailhead Playground na página da Web aberta.
   
4. Permita o acesso à organização.
   

Configurar o projeto do SFDX para um aplicativo de cliente externo

1. Abra o arquivo sfdx-project.json no VS Code.
   
2. Atualize o parâmetro sfdcLoginUrl com seu domínio.
   

Para encontrar seu domínio em Setup (Configuração), insira My Domain (Meu domínio) na caixa Quick Find (Busca rápida) e clique em My Domain (Meu domínio).

3. Expanda o diretório chamado config e abra o arquivo de definição da organização temporária chamado project-scratch-def.json. Adicione ExternalClientApps e ExtlClntAppSecretExposeCtl à configuração dos recursos.
   

	  "features": ["EnableSetPasswordInApi", "ExternalClientApps", "ExtlClntAppSecretExposeCtl"],

4. Crie um arquivo de manifesto package.xml no diretório de projeto.
   
5. Adicione esse conteúdo ao seu arquivo package.xml.
   

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>ExternalClientApplication</name>
    </types>
    <version>61.0</version>
</Package>

6. No diretório force-app/main/default, crie uma pasta chamada externalClientApps.
   
7. Adicione um arquivo à pasta externalClientApps chamado ecaViaMetadata.eca-meta.xml. Ele será o arquivo de cabeçalho do seu aplicativo de cliente externo.
   

8. Adicione esse conteúdo ao seu arquivo de cabeçalho.
   

<?xml version="1.0" encoding="UTF-8"?>
<ExternalClientApplication xmlns="http://soap.sforce.com/2006/04/metadata">
    <contactEmail>eca_metadata@example.com</contactEmail>
    <description>External client app Metadata API creation</description>
    <distributionState>Local</distributionState>
    <isProtected>false</isProtected>
    <label>ecaViaMetadata</label>
</ExternalClientApplication>

Aqui, seu aplicativo de cliente externo está tecnicamente completo. Você poderia implantar essa configuração e ela apareceria no Gerenciador de aplicativo de cliente externo no seu playground como aplicativo de cliente externo básico. Mas, para tornar um aplicativo útil, você precisa de um plugin. Vamos configurar um plugin do OAuth semelhante ao que fizemos no primeiro módulo. Um plugin do Oauth configurado para o fluxo do servidor da Web OAuth 2.0 exige algumas edições e alguns novos arquivos.

Ativar e configurar o plugin do OAuth

Diferentemente dos aplicativos conectados, que combinam todas as configurações em um único arquivo, os aplicativos de cliente externos incluem dois arquivos de configuração e um arquivo de políticas. O arquivo de configurações globais do OAuth inclui campos confidenciais, por exemplo, a chave e o segredo do cliente do OAuth que deveriam estar protegidos. O arquivo de configurações do OAuth inclui todas essas configurações menos confidenciais para um aplicativo de cliente externo. Não existe a necessidade de criar um arquivo de políticas ao configurar um aplicativo de cliente externo para o fluxo do servidor Web porque as políticas são configuradas com base nos arquivos de configuração. O arquivo de políticas do Oauth é gerado quando você implanta o aplicativo de cliente externo.

Criar um arquivo de configurações globais do OAuth

1. No diretório force-app/main/default, crie uma pasta chamada extlClntAppGlobalOauthSets.
   
2. Adicione um arquivo à pasta extlClntAppGlobalOauthSets chamado ecaViaMetadataGlblOAuth.ecaGlblOauth-meta.xml.
   

3. Abra o arquivo ecaViaMetadataGlblOAuth.ecaGlblOauth-meta.xml no VS Code e adicione esse conteúdo a ele.
   

<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppGlobalOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <callbackUrl>https://openidconnect.herokuapp.com/callback</callbackUrl>
    <externalClientApplication>ecaViaMetadata</externalClientApplication>
    <isConsumerSecretOptional>false</isConsumerSecretOptional>
    <isIntrospectAllTokens>false</isIntrospectAllTokens>
    <isPkceRequired>false</isPkceRequired>
    <isSecretRequiredForRefreshToken>true</isSecretRequiredForRefreshToken>
    <label>ecaViaMetadataglobalset</label>
    <shouldRotateConsumerKey>false</shouldRotateConsumerKey>
    <shouldRotateConsumerSecret>false</shouldRotateConsumerSecret>
</ExtlClntAppGlobalOauthSettings>

4. Salve o arquivo de configurações globais do OAuth.
   

Criar um arquivo de configurações do OAuth

1. No diretório force-app/main/default, crie uma pasta chamada extlClntAppOauthSettings.
   
2. Adicione um arquivo à pasta extlClntAppOauthSettings chamado ecaViaMetadataSettings.ecaOauth-meta.xml.
   

3. Abra o arquivo ecaViaMetadataSettings.ecaOauth-meta.xml no VS Code e adicione esse conteúdo a ele.
   

<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <commaSeparatedOauthScopes>Api, Web, OpenID</commaSeparatedOauthScopes>
   <externalClientApplication>ecaViaMetadata</externalClientApplication>
    <label>ECA via Metadata Oauth Settings</label>
</ExtlClntAppOauthSettings>

4. Salve o arquivo de configurações do OAuth.
   

Arquivos de configuração de referência no arquivo de cabeçalho

Agora que você criou os dois arquivos de configuração, precisa incorporá-los ao aplicativo de cliente externo. O arquivo de cabeçalho é uma lista de todos os arquivos que compõem o aplicativo de cliente externo.

1. Abra o arquivo de manifesto package.xml.
   
2. Adicione uma entrada para cada um dos três arquivos OAuth.
   

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>ExternalClientApplication</name>
    </types>
    <types>
        <members>*</members>
        <name>ExtlClntAppOauthSettings</name>
    </types>
    <types>
        <members>*</members>
        <name>ExtlClntAppGlobalOauthSettings</name>
    </types>
    <types>
        <members>*</members>
        <name>ExtlClntAppOauthConfigurablePolicies</name>
    </types>
    <version>61.0</version>
</Package>

3. Salve o arquivo de manifesto package.xml.
   

Implantar seu aplicativo de cliente externo

Agora que seu aplicativo de cliente externo está devidamente configurado, implante-o. O arquivo de políticas é criado na implantação, ou seja, depois de implantar, recupere o aplicativo de cliente externo para levar o arquivo gerado para seu projeto do SFDX.

1. Execute esse comando para implantar o aplicativo de cliente externo. Substitua <username> pelo nome de usuário que você usou para fazer login quando autorizou o Dev Hub.
   

sf project deploy start --manifest package.xml --target-org <Username>

2. Recupere o aplicativo de cliente externo do seu Trailhead Playground. Substitua <username> pelo nome de usuário que você usou para fazer login quando autorizou o Dev Hub.
   

sf project retrieve start --manifest package.xml --target-org <username>

Verificar seu aplicativo

Depois de implantar e recuperar o aplicativo de cliente externo com sucesso, você deverá ver um arquivo de políticas no projeto do SFDX que antes não existia.

Você também pode abrir o Gerenciador de aplicativos de cliente externos e ver um novo aplicativo de cliente externo chamado ecaViaMetadata. Se quiser explorar, você pode coletar a chave e o segredo de cliente do seu My Domain e do OAuth e conectá-los ao OpenID Connect Playground para percorrer o fluxo do servidor Web do OAuth.

Recursos

• Ajuda do Salesforce: Criar um aplicativo de cliente externo com a API de metadados
• Ajuda do Salesforce: Como entender a API de metadados
• Ajuda do Salesforce: Como implantar e recuperar metadados
• Ajuda do Salesforce: Como a experiência de desenvolvedor do Salesforce muda sua forma de trabalhar
• Trailhead: Noções básicas do API