Como Criar e Configurar um Cliente de Aplicação
Um cliente de aplicação é a representação da sua aplicação no sistema de autenticação do grupo Magalu. Ele funciona como uma identidade única que permite que sua aplicação acesse as APIs do ecossistema Magalu de forma segura e controlada.
Para que serve um cliente:
- Autenticação: Identifica sua aplicação perante o sistema OAuth 2.0 do Magalu
- Autorização: Define quais APIs e recursos sua aplicação pode acessar através de escopos
- Controle de Acesso: Estabelece as URLs autorizadas para redirecionamento durante o fluxo de autenticação
- Segurança: Gera credenciais seguras (
client_ideclient_secret) para autenticar sua aplicação
O que você fará com o cliente criado: Após criar o cliente, você utilizará as credenciais geradas para implementar o fluxo OAuth 2.0 em sua aplicação, permitindo que os sellers autorizem o acesso aos seus dados e recursos através das APIs do grupo Magalu.
Vídeo de Instruções para Criação de Credenciais
Passo a Passo para Criação de um Client
Cadastrar sua conta
Crie uma conta com o ID Magalu neste link.
Caso já tenha uma conta no SuperApp do Magalu ou no Portal do Seller, poderá utilizar o mesmo login e senha; caso contrário, realize seu cadastro!
Baixar o IDM
Realize o download do arquivo de acordo com o sistema operacional na página de Lançamentos do IDM.
Tornar o arquivo executável
- Windows
- Linux
- macOS
Mova o arquivo para a pasta C:\Windows\System32. Abra o Powershell e navegue até C:\Windows\System32.
Use aspas duplas ao invés de aspas simples ao executar comandos em seu Powershell
Abra um novo terminal, navegue até a pasta em que fez o download do IDM e execute o seguinte comando:
chmod +x idm
Abra um novo terminal, navegue até a pasta em que fez o download do IDM e execute o seguinte comando:
chmod +x idm
Permitir a execução do app não baixado pela App Store:
Criar o client
Para criar um client, utilizaremos o comando ./idm client create.
Você pode utilizar o parâmetro --help após qualquer comando para ver detalhes sobre aquele comando e seus parâmetros. Ex: ./idm client create --help
Parâmetros disponíveis para o comando
| Campo | Obrigatório | Descrição |
|---|---|---|
--audience | Sim | A Lista de URLs referente aos ambientes que serão acessados pelo client. URLs devem ser separadas por espaços. Consulte as URLs dos ambientes aqui. |
--name | Sim | Nome da sua aplicação. Esse nome será exibido para o Seller durante a etapa de Consentimento. Confira as Diretrizes para o Nomear sua aplicação |
--privacy-term | Sim | A URL para a política de privacidade da sua aplicação. Importante: Esta URL será exibida como um link acessível para o seller durante a etapa de Autorização de Escopos, permitindo que ele consulte suas políticas de privacidade antes de conceder o consentimento. |
--redirect-uris | Sim | Lista de URLs autorizadas para receber o código de autorização OAuth 2.0 após autenticação bem-sucedida. As URLs devem ser separadas por espaços. Importante: Essas URLs serão utilizadas durante o fluxo OAuth 2.0 para retornar o código de autorização durante a Requisição de Consentimento. Por isso, esses endpoints devem estar preparados para capturar e processar o parâmetro code enviado via query string. Por questões de segurança, apenas URLs configuradas neste parâmetro serão aceitas. |
--scopes | Sim | A lista de escopos de acesso. Escopos devem ser separados por espaço. Veja o comando para listar escopos |
--terms-of-use | Sim | A URL que leva aos termos de uso da sua aplicação. Importante: Esta URL será exibida como um link acessível para o seller durante a etapa de Autorização de Escopos, permitindo que ele consulte seus termos de uso antes de conceder o consentimento. |
--description | Não | Uma descrição sobre a aplicação. |
--access-token-exp | Não | O tempo de vida do token de acesso em segundos. Máximo é 7200. |
--always-require-login | Não (Recomendado) | Ignorar a sessão ativa do Magalu ID e sempre exigir login (true/false). Recomenda-se utilizar false |
--backchannel-logout-session-required | Não | Cliente requer sessão de logout backchannel (true/false) |
--backchannel-logout-uri | Não | URI de logout backchannel |
--icon | Não | URL do ícone da aplicação. Veja as diretrizes de design |
--reason | Não | Motivo pelo qual a aplicação precisa dos escopos informados. |
--refresh-token-custom-expires-enabled | Não | Usar valor personalizado para expiração do refresh token (true/false) |
--refresh-token-exp | Não | Valor personalizado de expiração do refresh token (em segundos) |
--scopes-default | Não (Recomendado) | A lista de escopos padrão que serão automaticamente adicionados aos escopos solicitados durante o consentimento. Escopos devem ser separados por espaço. Veja o comando para listar escopos Importante: Estes escopos serão sempre incluídos no consentimento, sendo combinados com os escopos definidos no parâmetro scope da Requisição de Consentimento. O seller verá: --scopes-default + scope (da URL). |
Exemplo de comando de criação:
Este comando de criação de cliente já inclui todos os escopos e audiences para o ambiente produtivo. Altere os parâmetros --name, --description, --terms-of-use, --privacy-term, --redirect-uris e --scopes-default conforme necessário para sua aplicação.
./idm client create \
--name "client_teste" \
--description "cliente de testes" \
--terms-of-use "https://your-redirect-url.com/terms-of-use" \
--privacy-term "https://your-redirect-url.com/privacy-term" \
--redirect-uris "https://your-redirect-url.com/code-webhook" \
--audience "https://api.magalu.com https://services.magalu.com" \
--scopes "apiin:all open:logistic-carrier-shippings:read open:order-delivery-seller:read open:order-delivery-seller:write open:order-invoice-seller:read open:order-invoice:read open:order-logistics-seller:read open:order-logistics-seller:write open:order-order-seller:read open:portfolio-prices-seller:read open:portfolio-prices-seller:write open:portfolio-prices:read open:portfolio-prices:write open:portfolio-scores-seller:read open:portfolio-skus-seller:read open:portfolio-skus-seller:write open:portfolio-skus:read open:portfolio-skus:write open:portfolio-stocks-seller:read open:portfolio-stocks-seller:write open:portfolio-stocks:read open:portfolio-stocks:write open:sac-transaction-seller:read open:ticket-events-seller:read open:ticket-events-seller:write open:ticket-messages-seller:read open:ticket-messages-seller:write open:ticket-returns-seller:read open:ticket-returns-seller:write open:tickets-seller:read open:tickets-seller:write services:conversations-seller:read services:conversations-seller:write services:questions-seller:read services:questions-seller:write services:ticket-messages-seller:read services:ticket-messages-seller:write services:tickets-seller:read services:tickets-seller:write" \
--scopes-default "apiin:all open:logistic-carrier-shippings:read open:order-delivery-seller:read open:order-delivery-seller:write open:order-invoice-seller:read open:order-invoice:read open:order-logistics-seller:read open:order-logistics-seller:write open:order-order-seller:read open:portfolio-prices-seller:read open:portfolio-prices-seller:write open:portfolio-prices:read open:portfolio-prices:write open:portfolio-scores-seller:read open:portfolio-skus-seller:read open:portfolio-skus-seller:write open:portfolio-skus:read open:portfolio-skus:write open:portfolio-stocks-seller:read open:portfolio-stocks-seller:write open:portfolio-stocks:read open:portfolio-stocks:write open:sac-transaction-seller:read open:ticket-events-seller:read open:ticket-events-seller:write open:ticket-messages-seller:read open:ticket-messages-seller:write open:ticket-returns-seller:read open:ticket-returns-seller:write open:tickets-seller:read open:tickets-seller:write services:conversations-seller:read services:conversations-seller:write services:questions-seller:read services:questions-seller:write services:ticket-messages-seller:read services:ticket-messages-seller:write services:tickets-seller:read services:tickets-seller:write" \
--access-token-exp 7200 \
--always-require-login false
Armazenar as credenciais do client com segurança
Após a criação bem-sucedida do client, você receberá três credenciais importantes:
UUID: Identificador único do seu client (utilizado em comandos do IDM)Client ID: Identificador público do seu client (utilizado em requisições de APIs do grupo Magalu)Client Secret: Chave secreta de autenticação
O Client Secret é uma informação sensível e crítica para a segurança da sua aplicação:
- Armazene-o em um local seguro, preferencialmente em um gerenciador de segredos
- Nunca compartilhe ou exponha esta informação
- Por razões de segurança, não é possível recuperar o Client Secret após sua geração
- Caso o Client Secret seja comprometido ou perdido, será necessário criar um novo client
Para visualizar as demais configurações do seu client, utilize o comando listar clients
Durante a criação do client, alguns escopos solicitados podem requerer aprovação adicional antes de serem liberados para uso. Por exemplo, o escopo open:portfolio-scores-seller:read necessita de uma validação especial. Você pode verificar quais os escopos necessitam de aprovação a partir do comando de Listar Escopos
O sistema informará quais escopos estão pendentes de aprovação durante a criação do client. Você também pode verificar o status dos escopos através do comando Listar Clients
Como Listar Clients
Listar os clients
Para visualizar todos os seus clients e suas configurações, execute o comando:
./idm client list
O comando listará uma tabela com todos os parâmetros definidos durante a criação do client, como nome, descrição, URLs configuradas e demais configurações.
Este comando é especialmente útil para:
- Verificar o status de aprovação dos seus escopos (AVAILABLE, PENDING)
- Consultar quem é o aprovador dos escopos pendentes (APPROVER)
- Confirmar quais escopos estão configurados como padrão (indicados com "default")
- Validar todas as configurações do seu client
Como Atualizar um Client
Atualizar o client
Para atualizar um client existente, utilize o comando ./idm client update.
Parâmetros disponíveis para o comando de atualização
| Campo | Obrigatório | Descrição |
|---|---|---|
--uuid | Sim | UUID do cliente que será atualizado |
--access-token-exp | Não | Tempo de expiração do token de acesso (em segundos) |
--always-require-login | Não | Deve ignorar a sessão ativa do Magalu ID e sempre exigir login (true/false) |
--audience | Não | Audiência do token de acesso (separado por espaços) |
--backchannel-logout-session-required | Não | Cliente requer sessão de logout backchannel (true/false) |
--backchannel-logout-uri | Não | URI de logout backchannel |
--description | Não | Descrição do cliente |
--icon | Não | Link do ícone do cliente |
--name | Não | Nome do cliente |
--privacy-policy-term | Não | Link para os termos da política de privacidade |
--redirect-uris | Não | URIs de redirecionamento do cliente (separadas por espaços) |
--refresh-token-custom-expires-enabled | Não | Usar valor personalizado para expiração do refresh token (true/false) |
--refresh-token-exp | Não | Valor personalizado de expiração do refresh token (em segundos) |
--service-term | Não | Link para os termos de serviço |
Ao atualizar as audiências, todas as audiências previamente configuradas serão substituídas pelo novo valor informado. Certifique-se de incluir todas as audiências necessárias ao realizar a atualização para evitar a perda de permissões importantes.
Exemplo de comando de atualização:
./idm client update \
--uuid "27668929-f53a-4647-ab40-7db627b99a02" \
--audience "https://api.magalu.com https://api-sandbox.magalu.com https://services.magalu.com"
Como Adicionar Escopos a um Client Existente
Adicionar escopos a um client
Para adicionar novos escopos a um client já existente, utilize o comando específico ./idm client add-scope. Essa operação é separada da atualização geral do client, pois a inclusão de escopos pode exigir justificativas adicionais e está sujeita a validações de segurança.
Parâmetros disponíveis para o comando
| Campo | Obrigatório | Descrição |
|---|---|---|
--client-uuid | Sim | UUID do cliente que terá escopos adicionados |
--scopes | Sim | Lista de escopos a serem adicionados separados por espaço |
--reason | Não | Motivo pelo qual você está adicionando os escopos |
--scopes-default | Não | Lista de escopos padrão a serem adicionados separados por espaço |
Exemplo de comando para adicionar escopos:
./idm client add-scope \
--client-uuid "XXXXXX-XXXf-4XX2-8XXa9-37cXXXXXXd09" \
--scopes "apiin:all open:logistic-carrier-shippings:read" \
--scopes-default "apiin:all open:logistic-carrier-shippings:read" \
--reason "Necessário para integrar funcionalidades de logística e automação de pedidos."
Note que se trata de uma operação de adição e não atualização. Portanto não é necessário repetir escopos já adicionados nos parâmetros --scopes e --scopes-default
Caso queira apenas adicionar escopos ao parâmetro --scopes-default pode fazê-lo repetindo um --scope já adicionado à sua aplicação e passando os --scope-default necessários.
Após a execução do comando, a solicitação será processada e poderá passar por uma análise de conformidade antes da aprovação dos novos escopos. Verifique o status de aprovação dos escopos com o comando de Listar Clients
Como Consultar Escopos Disponíveis
Consultar escopos disponíveis
Para listar todos os escopos disponíveis, execute o comando:
./idm scopes list
O comando retornará uma tabela com as seguintes informações para cada escopo:
SCOPE ID: Identificador único do escopoSCOPE NAME: Nome do escopo que deve ser usado nos comandosAPI PRODUCT: Produto/API ao qual o escopo pertenceCONSENT TEXT: Texto que será exibido ao seller para autorização do escopoCONSENT REQUIRED: Se requer consentimento do seller (true/false)APPROVAL REQUIRED: Se requer aprovação administrativa (true/false)