@ozmap/kcozadmin
v1.1.2
Published
Esta biblioteca é uma ferramenta para trabalhar com autenticação e autorização dentro das soluções da DevOZ.
Downloads
26
Maintainers
Keywords
Readme
KCOZAdmin
Esta biblioteca é uma ferramenta para trabalhar com autenticação e autorização dentro das soluções da DevOZ.
Sobre o keycloak:
Keycloak é um software de gerenciamento de identidade e controle de acesso. Permite a autenticação com serviços e aplicativos existentes usando várias identidades de usuário. Centraliza a gerencia de usuarios e permissões de toda a organização.
Definições
- Realm: é um domínio ( organização ) que agrupa elementos relacionados com segurança, como usuários, papéis ou policies. Ele é formado por uma série de configurações que definem como a autenticação e autorização são gerenciadas.
- Users: Entidades que podem se autenticadas. ex: João
- Roles: Direitos que podem ser atribuídos aos usuários. ex: Admin Actions: A Role é um agrupamento de ações e atributos
- Clients: (Clientes): Aplicações que usam Keycloak para autenticar usuários. ex:OZneutral, OZmap, diagnoz
Exemplo
Como é uma organização dentro do keycloak:
- Organização: OZmap
- Clients:
- OZmap
- Pedro: [Admin]
- OZneutral
- Pedro [Viewer]
- João [Admin]
- Grafana
- Antonio [Admin]
- OZmap
- Usuarios:
- Pedro
- Antonio
- João
- Papeis:
- Admin
- Viewer
- Editor
- Clients:
Como utilizar a biblioteca
Primeiro instale a biblioeteca:
npm install --save @ozmap/kcozadmin
Após instalada, importe e instancie um objeto da classe KCOZAdmin, passando ao construtor os dados de host e autorização:
import { KCOZAdmin } from '@ozmap/kcozadmin';
const kcozAdmin = new KCOZAdmin({
baseUrl: "http://localhost:8080",
realmName: "master"
}, {
username: "user",
password: "senha",
grantType: "password",
clientId: "admin-cli",
})
Uma vez instanciado, a classe oferece as seguintes funções:
createRealm(), removeRealm()
Para criar um realm, a função createRealm recebe três parâmetros:
- realmData: objeto contendo o nome do realm a ser criado
- [clientData]
- userData: objeto contendo dados do usuário a ser criado no realm
Caso os dados clientData sejam passados, a biblioteca irá criar um client de id/nome "organization" contendo as informações vindas do parâmetro.
Caso o parâmetro userData esteja vazio, a biblioteca irá criar um usuário "admin", com a senha "admin". Este usuário terá por padrão permissões para alterar usuarios e clients dentro do realm.
Para criar realms, você precisa estar conectado com um usuario que tenha permissão de criação de realms. Idealmente, use o usuário "admin" do realm "master".
O client responsável por acesso a "API" do keycloak é o "admin-cli". Por default, a biblioteca ja inicia usando este client, caso não seja passado nenhum outro como parametro.
Abaixo, um exemplo de criação de realm com usuário e client:
const realm = await kcozAdmin.createRealm(
{ realmName: 'teste-automatico' },
[
{
clientId: "clientName",
name: "clientName",
baseUrl: 'https://teste-automatico.organization.com/',
adminUrl: 'https://teste-automatico.organization.com/',
rootUrl: 'https://teste-automatico.organization.com/',
redirectUris: [
'https://teste-automatico.organization.com/',
'https://teste-automatico.organization.com/*',
'https://organization.com/*'
],
webOrigins: [
'https://teste-automatico.organization.com/',
'https://teste-automatico.organization.com/*',
'https://organization.com/*'
],
description: `Description`,
protocol: 'openid-connect',
clientAuthenticatorType: 'client-secret',
implicitFlowEnabled: false,
fullScopeAllowed: true,
frontchannelLogout: false,
enabled: true,
standardFlowEnabled: true,
surrogateAuthRequired: false
}]
);
Para remover um realm, a função removeRealm recebe apenas um parâmetro:
- realmName
updateClient(), getClientSecret
Após criar um realm contendo um "organization", pode ser necessário modificar algumas das configurações deste client. Para isso, a função updateClient recebe dois parâmetros:
- realmName
- clientData
O ID do cliente a ser alterado deve ser especificado em clientData.id. Exemplo alterando a baseUrl de um cliente abaixo:
const updatedClient = await kcozAdmin.updateClient( 'teste-automatico', {
id: "organization",
baseUrl: 'https://teste-automatico.ozmap.com/'
});
Para obter o secret de um cliente, a função getClientSecret recebe dois parâmetros:
- realmName: nome do realm a qual o cliente pertence
- id: id do cliente desejado
createUser(), removeUser(), getUsers(), updateUserPassword()
Para criar um novo usuário em um real existente, a função createUser recebe dois parâmetros:
- realmName: nome do realm em qual o usuário será criado
- userData: dados do usuário
Segue o exemplo de criação de cliente no realm "teste-automatico":
createdUser = await kcozAdmin.createUser('teste-automatico', {
username: "teste",
email: "[email protected]",
firstName: "teste",
lastName: "teste",
enabled: true,
emailVerified: true,
requiredActions: [],
groups: []
});
Para realizar a remoção de um usuário, a função removeUser recebe os seguintes parâmetros:
- realmName: nome do realm a qual o usuário pertence
- id: id do usuário a ser removido
Para listar os usuários registrados a um realm, a função getUsers recebe apenas um parâmetro:
- realmName: nome do realm desejado
Para realizar a alteração de senha de um usuário, a função updateUserPassword recebe três parâmetros:
- realmName: nome do realm a qual o usuário pertence
- password: nova senha para o usuário
- id: id do usuário a ser editado
Futuro da biblioteca
- Adicionar novos clients a realms existentes
Configuração do Projeto
Requisitos:
- NodeJS: v16.#
- NPM: v8.#
- Docker
- Docker-compose
Após cumprir os requisitos, execute os seguintes comandos para configurar o projeto em sua máquina.
# Clonar o repositório remoto
git clone [email protected]:developmentOneZero/kcozadmin.git
# Instalar pacotes
npm install
# Rodar uma instancia do keycloak para testar localmente
cd testar
docker-compose up -d
Com os passos anteriores concluídos, agora você pode executar os testes.
Testes
Para executar os testes com o Jest, use o seguinte comando:
# Execute testes com Jest
npm test
Para publicar no npm
npm init --scope=@zmap
npm run build
npm publish --access public