npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@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

8

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]
    • Usuarios:
      • Pedro
      • Antonio
      • João
    • Papeis:
      • Admin
      • Viewer
      • Editor

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