Sumário. Campus Universitário Darcy Ribeiro Av. L3 Norte Gleba A, SC 04 CEP Fone: +55 (61) Fax: +55 (61) unasus.gov.

Transcrição

1 Brasília, 23 de abril de 2013 Guia de Instalação e Configuração do Módulo de Matrícula versão1.0 Responsáveis: Salvador Melo/Márcio Batista/Lino Muniz/Ricardo Z ago Sumário 1 Introdução Adquisição do módulo de matrícula Obtenção dos dados da plataforma Arouca O que é SSL? Procedimento para acesso ao web service da Plataforma Arouca Passos para assinatura certificado com OpenSSL º PASSO Gerando o CSR º PASSO Enviandoo CSR gerado para assinatura º PASSO Utilizando o seu certificado Perguntas Frequentes Como faço para testar o acesso WSDL da Plataforma Arouca pelo meu navegador? Como faço para renovar meu certificado SSL? E quando a CSR (requisição) não pode ser decodificada? Como faço uma solicitação de suporte? Apaguei acidentalmente meu [nome da sua chave privada].key. Como devo proceder? Como posso obter maiores informações sobre o uso do web service da Plataforma Arouca? Como checar meus certificados? Instalação do Módulo Configurando chave e senha de autenticação de WebService Configuração do módulo de matrícula Cadastrando regra da matrícula Modo de processamento Configurações de mensagens Configuração da função Cron Matrícula manual Campos de perfil Seleção do módulo de inscrição no curso

2 1 Introdução O módulo de matrícula UNA-SUS foi desenvolvido em PHP para a plataforma Moodle versão 1.9.x. Ele se conecta à plataforma Arouca, via WebService e é capaz de realizar consultas pelo CBO (Classificação Brasileira de Ocupações) dos usuários utilizando essa base de dados. A principal funcionalidade desse módulo é aceitar ou recusar as solicitações de matrícula em um curso disponibilizado no Moodle, tendo como critério o CBO dos usuários. O filtro de matrícula por CBO garante que apenas as categorias de profissionais, que constituem o público alvo, terão a solicitação de matrícula aceita. CBO. Nas próximas versões do módulo será possível criar outros tipos de regras de matricula, além do Os passos necessários para a instalação e configuração da referido módulo são os seguintes: Adquirir o módulo de matrícula junto a SE/UNA-SUS. Obter os dados da plataforma Arouca, a saber: Senha da chave privada, Url do web service e o Arquivo com a chave de autenticação. O sistema de login da sua plataforma moodle deverá esta integrado a federação ou os campos id number e user name, padrões do moode, deverá ser preenchido com o CPF dos usuários da plataforma; Instalar o módulo de inscrição junto a SE/UNA-SUS. Configurar o módulo de inscrição junto a SE/UNA-SUS. Selecionar o módulo de inscrição junto a SE/UNA-SUS para um determiando curso. 2

3 2 Adquisição do módulo de matrícula Para obter o módulo de matrícula, você deve estar cadastrado num provedor de identidade da Federação, por exmeplo a Arouca, para poder acessar o ambiente denominado Comunidades e fazer o download do referido módulo. Caso você não tenha um cadastro num provedores de identidade válidos, poderá seguir as instruções constantes no manual que consta no endereço abaixo e fazer o seu cadastro: O plugin de matrícula (arquivo denominado unasus.zip) está disponível na plataforma Comunidades, em Grupos de Trabalho, no GT 9: Tecnologia da Informação, no item denominado Compartilhamento Plugin para Módulos e sistemas complementares, no seguinte endereço: Caso não tenha acesso à plataforma Comunidades, entre em contato com o suporte técnico da UNA-SUS, disponível no endereço abaixo, identificando-se e solicitando acesso. 3

4 3 Obtenção dos dados da plataforma Arouca 3.1 O que é SSL? Secure Socket Layer (SSL) é um padrão global em tecnologia de segurança que abre um canal criptografado entre o seu cliente de web service e o servidor da plataforma Arouca para garantir que todos os dados transmitidos sejam sigilosos e seguros. Ao escolher ativar o SSL, você terá que responder algumas questões sobre a identidade do seu órgão. Será criado para seu cliente do web service um par de chaves criptográficas uma chave privada (Private Key) e uma chave pública (Public Key). A chave privada deverá ser mantida segura onde se encontra o seu Web Service. Esse par de chaves será utilizado para geração de uma requisição de assinatura de certificado (Certificate Signing Request, CSR) um arquivo de dados contendo os detalhes do cliente do WS e do órgão. Você deverá enviar esta CSR através do formulário de suporte do site da Unasus; seus dados serão validados e se estiverem corretos seu certificado digital será emitido. O certificado digital emitido será necessário para o estabelecimento da conexão segura e para identificar seu cliente web service junto à plataforma Arouca. Uma chave privada tem este formato: -----BEGIN RSA PRIVATE KEY END RSA PRIVATE KEY----- Uma chave privada encriptada com senha tem este formato: -----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC, E END RSA PRIVATE KEY----- Um certificado tem este formato: -----BEGIN CERTIFICATE END CERTIFICATE

5 Um certificado é associado a um DN, exemplo de um DN: CN=SE-UNA-SUS,OU=Secretaria Executiva UNA-SUS,O=Ministerio da Saude,L=Brasilia,ST=Distrito Federal,C=BR EM PHP quando usamos um certificado cliente, normalmente cria-se um arquivo XXX.pem, composto da chave privada encriptada e o certificado, ou seja, é composto por: -----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC, E END RSA PRIVATE KEY BEGIN CERTIFICATE END CERTIFICATE----- Sendo que a senha necessária para o PHP, é a senha utilizada na encriptação da chave privada. Caso você tenha uma chave privada não encriptada, pode-se encripta-la em LINUX usando o comando: openssl rsa -des3 -in xxx.key -out xxx.key2 (onde xxx.key é um arquivo com apenas a chave privada não encriptada e xxx.key2 é a chave privada encriptada com a senha solicitada ao rodar o comando) comando similar em outras plataformas. Em LINUX, um jeito simples de concatenar dois arquivos (exemplo, chave encriptada chamada aqui de xxx.key2 e certificado xxx.crt) para gerar um arquivo único para uso no PHP exemplo xxx.pem cat xxx.key2 xxx.crt > xxx.pem 3.2 Procedimento para acesso ao web service da Plataforma Arouca Obrigatoriamente, o órgão deverá criar dois certificados com chave privada diferentes. Um para acesso ao ambiente de homologação e outro para acesso ao ambiente de produção da plataforma Arouca. 5

6 Cada ambiente possui uma CA (Autoridade Certificadora) diferente. Ambas servem apenas para autenticação do WS. Primeiramente o órgão deve solicitar assinatura para o certificado de acesso ao ambiente de homologação, a fim de fazer testes de inserção e pesquisa pelos métodos do WS Arouca. Finalizado os testes, o órgão deve solicitar outra assinatura de certificado para acesso ao ambiente de produção. A seguir iremos explicar como gerar o certificado digital. 3.3 Passos para assinatura certificado com OpenSSL º PASSO Gerando o CSR Um CSR é um arquivo contendo as informações para a solicitação do seu certificado. Para gerar um par de chaves, pública e privada, e o CSR utilize as instruções: openssl req -newkey rsa:2048 -nodes -keyout [nome da sua chave privada].key -out [nome do arquivo].csr Isso gera dois arquivos. O arquivo [nome da sua chave privada].key contém a chave privada. Observações: Não compartilhe esse arquivo com alguém; Proteja a sua chave com cuidado; Será solicitado que você forneça os dados a serem incluídos no seu CSR. Em alguns campos haverá um valor padrão; Se você colocar., o campo ficará em branco; Não abrevie as informações nem utilize caracteres especiais incluindo letras acentuadas. Country Name (C) (Código de país de 2 letras), deve ser preenchido como BR State or Province Name (ST) (Estado, por extenso) Locality Name (L) (Cidade, por extenso) Organization Name (O) (Nome do Órgão) Organizational Unit Name (OU) (Departamento, setor) Common Name (CN) (Nome utilizado para identificar a aplicação cliente) Address (E) (Endereço eletrônico) As seguintes informações são opcionais. A challenge password (Senha para uso da chave privada. Se fornecida deve ser recordada, pois será necessária em configurações posteriores.) An optional company name (Nome alterantivo) Nota: Os campos address, optional company name e challenge password podem ser deixados em branco na solicitação de um certificado de servidor. 6

7 Pronto. Seu CSR foi gerado º PASSO Enviandoo CSR gerado para assinatura Após a geração do arquivo de CSR, acesse o sistema de suporte técnico SE/UNASUS pelo endereço eletrônico ( e crie um chamado com Assunto: Assinatura Certificado AroucaHomologação para acesso ao ambiente de homologação ou com assunto: Assinatura certificado Arouca Produção para acesso ao ambiente de produção. Enviado o chamado, aguarde retorno do atendimento º PASSO Utilizando o seu certificado Você receberá um arquivo.zip contendo 2 arquivos do suporte Arouca: Seu certificado [seu certificado assinado].crt Certificado AC Arouca [ACArouca_Ambiente].crt Nota: Caso solicite certificado para o ambiente de homologação, por exemplo, você receberá o certificado da AC Arouca_homologação. Cada ambiente possui uma AC diferente. Descompacte os arquivos e salve-os no diretório de sua preferência. Seu certificado e chave privada estão em formato PEM. Dependendo do seu cliente, diferentes formatos de chave/certificado podem ser necessários. Caso precise dos certificados como PKCS#12, utilize o comando abaixo para converter o arquivo: openssl pkcs12 -export -out [nome do arquivo].p12 -inkey [nome da sua chave privada].key -in [seu certificado assinado].pem -certfile [ACArouca_Ambiente].pem A seguir será solicitada uma senha. Enter password: (NOTA: guarde esta senha para poder acessar o [nome do arquivo].p12 pela sua aplicação) Caso precise converter para DEM, por exemplo, sugerimos: openssl x509 -in [seu certificado assinado].pem -inform PEM out [seu certificado assinado].crt -outform DER openssl rsa -in [nome da sua chave privada]imput.key -inform PEM -out [nome da sua chave privada output].key -outform DER Acesse o WSDL da plataforma Arouca conforme orientações no Documento de uso Web Service Arouca disponível para download no endereço eletrônico: Entre em contato com nosso suporte para tirar dúvidas técnicas ou de instalação através do canal: Perguntas Frequentes 7

8 3.4.1 Como faço para testar o acesso WSDL da Plataforma Arouca pelo meu navegador? Abra o navegador e importe o certificado [nome do arquivo].p12. Exemplo: No Firefox abrir a opção: Editar/Preferências/Avançado/Criptografia/Certificados Clique em Seus Certificados/Importar Busque pelo [nome do arquivo].p12 criado Informe a senha. Caso esteja usando o certificado digital para acesso ao servidor de homologação da Plataforma Arouca acesse a url: Caso esteja usando o certificado digital para acesso ao servidor de produção da Plataforma Arouca acesse a url: O WSDL deverá ser exibido Como faço para renovar meu certificado SSL? O processo de renovação é idêntico ao da aquisição inicial. Você deverá gerar uma nova CSR e solicitar o certificado, seguindo os passos deste guia E quando a CSR (requisição) não pode ser decodificada? Isso significa que falta algum pedaço do arquivo. Por exemplo, não podem ser suprimidas as linhas BEGIN CERTIFICATE REQUEST e END CERTIFICATE REQUEST Como faço uma solicitação de suporte? Acesse o endereço eletrônico e crie um chamado direcionado para a categoria Plataforma Arouca Apaguei acidentalmente meu [nome da sua chave privada].key. Como devo proceder? Primeiro, verifique se tem um backup e reinstale o certificado assinado. Se não tiver um backup, gere uma nova CSR e solicite a reposição do certificado pelo Como posso obter maiores informações sobre o uso do web service da Plataforma Arouca? Para maiores infor[nome da sua chave privada].key[nome da sua chave privada].keymações sobre uso do web service da Plataforma Arouca acesse o documento Documento de uso Web Service Arouca disponível no endereço eletrônico: 8

9 3.4.7 Como checar meus certificados? Use o comando: openssl x509 -in MYCERT.crt -text -noout (Para checar o certificado) openssl pkcs12 -info -in [nome do arquivo].p12 ( Para checar o pkcs12 ) 9

10 4 Instalação do Módulo A instalação do módulo de inscrição segue o procedimento padrão de instalação de outros módulos na Plataforma Moodle. Para efetuar a instalação siga estes passos: Transfira a pasta unasus para a pasta enrol, que fica no diretório de instalação do Moodle ( MOODLE_INSTALL_DIR/enrol); Após o passo 2, acesse o ambiente do Moodle com login de administrador do sistema; No bloco Administração do site, visível apenas para administrador, clique em avisos ou acesse a seguinte url: trocando a parte em vermelho pelo seu endereço real. Feito isso, automaticamente o plugin unasus será detectado e instalado. Figura 1: localização da opção "avisos" no bloco Administração do site 10

11 5 Configurando chave e senha de autenticação de WebService O primeiro passo a ser realizado para conexão com a Plataforma Arouca é a configuração do certificado digital. Esta configuração é feita editando o arquivo config_dist.php localizado na pasta de instalação do plugin. Abra o arquivo e insira as informações como Endereço do arquivo de certificado digital no servidor Endereço do arquivo no servidor que contêm a senha privada do certificado e Endereço web do WSDL conforme figura abaixo. Figura Após a inserção das informações basta renomear o arquivo config_dist.php para config.php Obs.: você não pode deixar de renomear o arquivo config_dist.php, caso contrário sua conexão com a plataforma Arouca não será estabelecida. Este procedimento só poderá ser realizado pelo administrador do servidor, caso você seja apenas administrador do moodle, deverá entra em contato com o administrador do seu servidor para que ele possa configura o referido arquivo. 6 Configuração do módulo de matrícula Após a instalação do módulo é hora de configurá-lo, definir os CBO s válidos para matrícula. Ative o módulo instalado no gerenciador de plugins de inscrição. Para isso, clique no menu Administração do site, selecione Cursos e clique em Inscrições, conforme figura abaixo. 11

12 Figura 2: localização da opção Inscrições no bloco Administração do site Se preferir, acesse o seguinte link pelo seu navegador, trocando a parte em vermelho pelo endereço da sua plataforma Moodle. No gerenciador de plugin, localize o módulo Sistema de Matrícula UNA-SUS, marque-o como ativo e depois clique no botão Salvar mudanças. Figura 3: localização do módulo Sistema de Matrícula UNA-SUS. Após marcar a opção ativar e clicar em salvar, clique em editar no módulo de matrícula UNA-SUS. Uma janela será aberta, conforme figura abaixo. Para iniciar a configuração do módulo propriamente dito, clique em Gerenciar Inscrição. 12

13 Figura 4: janela acessar a configuração do módulo Após a inserção dos dados, clique em Salvar. Com os procedimentos anteriores seguidos, estará estabelecida a conexão da sua plataforma Moodle com a plataforma Arouca, o que possibilitará ao Moodle consultar os CBO s dos profissionais de saúde na Arouca. 6.1 Cadastrando regra da matrícula Atualmente, só é possível definir regra de matrícula com base no CBO. Nas próximas versões deste módulo, poderemos contemplar outras regras. A regra do CBO consiste em definir uma lista de códigos CBO s como requisito para matrícula. Quando um usuário tenta se matricular em um curso, o sistema faz uma consulta à plataforma Arouca, verificando se o usuário possui CBO válido para matrícula. Se houver, a matrícula será efetivada, caso contrário, será negada. Para cadastrar a regra de matrícula, acesse o menu Regra da Matrícula do módulo, e selecione uma opção para definir a regra. Figura 5: tela de cadastramento das regras de matrícula As regras de matrícula podem ser cadastradas nos níveis: Contexto do sistema: as regras se aplicam para todas as categorias e cursos; 13

14 Categoria de cursos: as regras se aplicam em nível de categoria, ou seja, se aplica apenas aos cursos vinculados às categorias específicas; Contexto de curso: neste contexto podemos configurar as regras de matrícula apenas para um curso específico. Matrícula. Após escolher os contextos desejados, clique na opção Cadastrar na coluna Regra de Figura 6: tela para edição das regras de matrícula Na tela de configuração da regra de matrícula, a parte mais importante, e que requer bastante atenção, é o campo CBO. Nele deverá ser inserido o código de Classificação Brasileira de Ocupações CBO s dos profissionais que terão sua solicitação de matrícula permitida no curso. Você deve ter observado na Figura 6 acima que alguns códigos possuem XX no final, como, por exemplo o código 2251XX. O número 2251 é o código utilizado para representar a profissão dos Médicos Clínicos, 2252 é o código para os Médicos em Especialidades Cirúrgicas e 2253 para os Médicos em Medicina Diagnóstica e Terapêutica, já o código com o dígito no final é utilizado para designar a especialidade do profissional médico, exemplo (médico alergista). No caso de um curso que permita a matrícula de qualquer médico, você deverá inserir o código seguido de XX, exemplo 2251XX. Isso permitirá a matrícula de qualquer médico, independente da sua especialidade. A mesma regra se aplica às demais profissões. Após definir as regras de matrícula, clique na opção Salvar. Para consultar a lista de CBO s acesse o link: 14

15 6.2 Modo de processamento O Módulo unasus permite três tipos de processamento: manual, automático e manualautomático. Manual: esta opção habilita o gestor do curso a aceitar as solicitações de matrículas que foram recusadas com base na regra do CBO. Automático: esta opção habilita o cron a reprocessar as solicitações de matrículas que foram recusadas com base na regra do CBO. Manual automático: esta opção habilita as duas alternativas acima mencionadas. Figura 7: tela de escolha do tipo de processamento Para selecionar uma das opções listadas, clique na aba configurações, em seguida modo de processamento e por último cadastrar. Selecione um dos modos, manual, automático ou manualautomático. 6.3 Configurações de mensagens A configuração de mensagens é obrigatória e sem esta o módulo não funcionará. Há vários tipos de mensagens que são exibidas na tela e enviadas por durante o processo de matrícula. As mesmas devem ser configuradas no contexto em que a regra foi definida: Contexto do sistema, Categoria de cursos ou Contexto de curso. Observação: a mensagem pode ser definida em um contexto diferente da regra que foi definida. Uma vez definida a regra, a mensagem deve ser defina no mesmo ou no contexto superior. Clique sobre o contexto desejado e cadastre as mensagens conforme figura abaixo. 15

16 Figura 8: definição do contexto desejado e cadastramento das mensagens Figura 9: visualização das mensagens 6.4 Configuração da função Cron A configuração da função Cron é necessária caso o modo de processamento automático seja habilitado. O uso do cron possibilita que o plugin reprocesse as matrículas recusadas nos casos: Erro de 16

17 conexão com Arouca, CBO não consta na Plataforma Arouca, Não existe nenhuma regra de inscrição cadastrada na base de dados ou o CBO não consta na lista de requisitos. Para efetuar essa configuração, acesse o módulo e clique no menu Configuração / Cron. Em seguida, escolha um contexto para cadastrar a mensagem. Escolha sempre o contexto (Sistema, curso ou categoria de curso) em que a regra da matrícula já esteja configurada. Outra coisa a ser definida é o Intervalo de processamento. Essa configuração define o intervalo de tempo e horário que o cron de revisão da matrícula deve ser processado. Se não for definido nenhum valor ou se for definido o valor zero, o processamento ficará desabilitado. Se for definido um valor acima de zero, a funcionalidade do cron relativo à revisão da matrícula será executada sempre com a carência do valor definido. Por exemplo: se for definido intervalo de 12 horas, a execução será feita duas vezes ao dia. A configuração da rotina do cron no sistema operacional deve ter um intervalo de tempo igual ou inferior. Figura 10: tela de configuração do cron 6.5 Matrícula manual O processo de matrícula manual foi pensado para casos específicos em que uma matrícula tenha sido recusada através do processo automático. Porém, a função só poderá ser usada caso a matrícula tenha sido recusada pelo processo automático. Nesses casos, o administrador da plataforma Moodle poderá acessar o módulo e realizar a matrícula do usuário manualmente, clicando na aba de pesquisa e localizando o usuário desejado. Use o campo de busca (usuário) ou os demais filtros. 17

18 Figura 11: tela de localização Após localizar o usuário desejado, clique sobre o número do ID e uma nova janela será aberta. Figura 12:tela de justificativa para a matrícula manual. Insira uma justificativa para a matrícula manual e clique em Salvar. Com isso, o usuário será matriculado no curso e receberá um de confirmação com o texto inserido na justificativa. Observação: ficará registrada no sistema a justificativa e o nome da pessoa que realizou a matrícula manual. 6.6 Campos de perfil A função campos de perfil foi desenvolvida para coletar dados de usuários para fins estatísticos no momento da matrícula. 18

19 Ao clicar na aba configurações do módulo de matrícula, você poderá criar uma categoria e adicionar um item escolhendo a opção na caixa de seleção. Os itens a serem criados para o formulário serão os mesmos do formulário padrão do Moodle com as opções de campo: caixa de seleção, menu de escolha, texto de entrada e área de texto. Observação: o formulário para coleta de dados não é obrigatório. O plugin pode ser usado sem essa função configurada. 19

20 7 Seleção do módulo de inscrição no curso Acesse o ambiente do seu curso como Administrador e selecione Configurações no bloco Administração. Figura 13: identificação do campo "Configurações" no bloco "Administração". Localize o campo chamado Inscrições e em Plugins para inscrição selecione Sistema de Matrícula UNA-SUS. Figura 14: tela de seleção do plugin recém instalado. 20