Tutorial Básico SimpleSAMLphp para Implantar Autenticação Usuários da UFRGS

Autor: Rui Ribeiro
Atualização: 12/08/2010
Revisão: 1

Sumário

1. Introdução
2. Glossário de Variáveis
3. Roteiro de Instalação
4. Roteiro de Configuração
5. Exemplo de Aplicação PHP integrada com o SimpleSAML
6. Descrição dos atributos retornados na autenticação

Introdução

O SimpleSAMLphp (SimpleSAML) [1] é uma ferramenta escrita em PHP, compatível com o Shibboleth, que trata das questões relativas a autenticação. Muito embora o SimpleSAML possa atuar tanto como Identity Provider (IdP) quanto como Service Provider (SP) este tutorial ficará restrito a segunda opção, ou seja, SP.

Este tutorial apresentará os procedimentos necessários para instalar o SimpleSAML e criar uma aplicação básica que utilize a autenticação Shibboleth para realizar a identificação básica de um usuário. Os procedimentos são os seguintes: istalação do SimpleSAML; configuração do SimpleSAML para Federação UFRGS-Teste; e exemplo de Aplicação PHP integrada com o SimpleSAML. Os comandos apresentados no roteiro presumem que a instalação é feita em um servidor Linux onde há possibilidade de acesso shell.

Voltar ao sumário

Glossário de Variáveis

Ao longo deste roteiro poderão ser utilizadas algumas variáveis que estarão destacadas em negrito. A seguir é apresentado um glossário para substituição das variáveis:

HOSTNAME_FULL: corresponde ao endereço completo do Host. Ex.: servidor.ufrgs.br

Voltar ao sumário

Roteiro de Instalação

Este roteiro abordará os passos necessários para fazer a instalação básica da SimpleSAML.

Será considerado a utilização das seguintes pastas:

ss-aplicacao: conterá o SimpleSAML
aplicacao: conterá a aplicação que fará uso do SimpleSAML

1. Faça download do SimpleSAML através do endereço: http://simplesamlphp.googlecode.com/files/simplesamlphp-1.6.1.tar.gz

2. Descompacte o arquivo e renomeie a pasta criada para ss-aplicacao.

tar -zxvf simplesamlphp-1.6.1.tar.gz
mv simplesamlphp-1.6.1 ss-aplicacao

3. É necessário criar um certificado SSL e uma chave privada. Para isso, execute os seguintes passos:

3.1. Crie o arquivo /tmp/openssl.cnf com o conteúdo a seguir:

[ req ]
default_bits = 2048 # Size of keys
string_mask = nombstr # permitted characters
distinguished_name = req_distinguished_name 

[ req_distinguished_name ]
# Variable name   Prompt string
#----------------------   ----------------------------------
0.organizationName = Nome da universidade/organização
organizationalUnitName = Departamento da universidade/organização
emailAddress = Endereço de email da administração
emailAddress_max = 40
localityName = Nome do município (por extenso)
stateOrProvinceName = Unidade da Federação (por extenso)
countryName = Nome do país (código de 2 letras)
countryName_min = 2
countryName_max = 2
commonName = Nome completo do host (incluíndo o domínio)
commonName_max = 64

# Default values for the above, for consistency and less typing. 
# Variable name   Value 
#------------------------------   ------------------------------ 
0.organizationName_default = UFRGS - Universidade Federal do Rio Grande do Sul
# Obs.: o valor de organizationalUnitName_default pode ser modificado, para indicar quem é o provedor do serviço
organizationalUnitName_default = UFRGS - Universidade Federal do Rio Grande do Sul
localityName_default = Porto Alegre
stateOrProvinceName_default = Rio Grande do Sul
countryName_default = BR
commonName_default = $HOSTNAME_FULL

3.2. Execute os seguintes comandos:

openssl genrsa 2048 -config /tmp/openssl.cnf > simplesaml.key 
openssl req -new -x509 -nodes -days 1095 -sha1 -key simplesaml.key -set_serial 00 -config /tmp/openssl.cnf > simplesaml.crt
openssl pkcs12 -export -in simplesaml.crt -inkey simplesaml.key -out simplesaml.p12 -name simplesaml -caname selfsigned

3.3. Mova os arquivos simplesaml.key; simplesaml.crt e simplesaml.p12 para a pasta ss-aplicacao/cert

4. Edite o arquivo de configuração disponível em ss-aplicacao/config/config.php e altere as seguintes entradas:

baseurlpath: pasta www do SimpleSAML (url relatica ao endereço web dentro do servidor). Ex.: ss-aplicacao/www/
auth.adminpassword: senha que será utilizada pelo administrador
technicalcontact_name: nome do contato técnico Ex.: Administrador
technicalcontact_email: e-mail do contato técnico Ex.: suporte@instituicao.br
language.default: definição do idioma. Utilize: en
timezone: ajuste de fuso horário. Utilize: America/Sao_Paulo
secretsalt: string aleatória que será usada para geração de hash. Recomenda-se a geração desta string através do seguinte comando:
tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo

5. Acesso o SimpleSAML através do endereço servidor.ufrgs.br/ss-aplicacao. Se a instalação ocorreu com sucesso, uma tela similar a Figura 1 deverá ser exibida.

Figura 1

Voltar ao sumário

Roteiro de Configuração

Este roteiro abordará os passos necessários para fazer a configuração básica da SimpleSAML para que este atue como um Service Provider (SP).

1. Faça a configuração dos parâmetros do SP. Para tanto edite o arquivo ss-aplicacao/config/authsources.php e substitua o conteúdo do referido arquivo pelas linhas a seguir:

<?php
$config = array (

	'admin' => array(
		'core:AdminPassword',
	),

	'default-sp' => array(
		'saml:SP',
		'privatekey' 	=> 'simplesaml.key',
		'certificate' 	=> 'simplesaml.crt',
		'entityID' 	=> 'https://$HOSTNAME_FULL/caminho/ss-aplicacao',
		'idp' 		=> 'https://login.teste.ufrgs.br/idp/shibboleth',
	),
);

2. O arquivo ss-aplicacao/metadata/saml20-idp-remote.php contém informações relativas ao IdP que será utilizado pelo SimpleSAML. Substitua o conteúdo do arquivo pelas linhas a seguir:

<?php
$metadata['https://login.teste.ufrgs.br/idp/shibboleth'] = array(
	'name' => array(
		'en' 	=> 'UFRGS',
		'pt-BR' => 'UFRGS',
        ),
        'description'          => 'Servidor de autenticação da UFRGS - Teste',
        'SingleSignOnService'  => 'https://login.teste.ufrgs.br/idp/profile/SAML2/Redirect/SSO',
        'certFingerprint'      => 'EA9D6546BF3D1C3DE84D945993516D3E26B39FD8'
);

3. Para obter os metadados do SimpleSAML para adiciona-los a Federação, acesse o SimpleSAML e clique na aba Federation e depois na opção Show Metadata. Os metadados estão presentes na caixa de texto In SAML 2.0 Metadata XML format.

4. É importante ressaltar que o SimpleSAML apenas estará integrado a Federação uma vez que seus metadados (obtidos no passo anterior) estejam inclusos no arquivo de metadados da Federação. Para tanto, envie os metadados para: foscarini@cpd.ufrgs.br

5. Após copiar os metadados é fortemente recomendável o bloqueio do acesso às páginas do SimpleSAML, para tanto, crie o arquivo .htaccess na raiz da pasta ss-aplicacao. O conteúdo deste arquivo deverá ser:

Order deny,allow
deny from all

<Files module.php>
Order allow,deny
Allow from all
</Files>

Voltar ao sumário

Exemplo de Aplicação PHP integrada com o SimpleSAML

Nas linhas a seguir é apresentado o código fonte de uma aplicação escrita em PHP e que utiliza-se do SimpleSAML para fazer o controle de acesso. Tal aplicação utiliza-se ainda dos atributos disponibilizados pelos SimpleSAML e os imprime na tela. Para utilizar o código a seguir, cole-o no arquivo index.php que deverá ficar na pasta aplicacao

<?php
define("UID",           'urn:oid:0.9.2342.19200300.100.1.1');
define("CN",            'urn:oid:2.5.4.3');
define("MAIL",          'urn:oid:0.9.2342.19200300.100.1.3');
define("UFRGSVINCULO",  'urn:oid:1.3.6.1.4.1.12619.200.1.1.15');

require_once('../ss-aplicacao/lib/_autoload.php');

//define que deve ser utilizada a autenticacao shibboleth
$as = new SimpleSAML_Auth_Simple('default-sp');
//obriga que a pagina abaixo somente seja executada por um usuário autenticado
$as->requireAuth();
?>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

<h2>Exemplo de Aplicação PHP+SimpleSAML</h2>

<?php
//real utilizaçao dos valores obtidos na autenticação:
//Cria um array de atributos
$attributes = $as->getAttributes();

//imprime os atributos
print(htmlspecialchars( "uid: " . $attributes[UID][0]) . "<br>");
print(htmlspecialchars( "cn: " . $attributes[CN][0]) . "<br>");
print(htmlspecialchars( "mail: " . $attributes[MAIL][0]) . "<br>");
for ($i=0; $i<count($attributes[UFRGSVINCULO]); $i++)
  print(htmlspecialchars( "ufrgsVinculo ". $i .": " . $attributes[UFRGSVINCULO][$i]) . "<br>");
?>

<br>
</body>
</html>

A aplicação demonstrada ao longo deste tutorial está acessivel através do endereço http://sp.ufrgs.br/aplicacao/ (abre em nova janela).
Para fazer a autenticação deve-se usar usuário e senha 99999999 que refere-se a um usuário fictício e que está presente apenas no LDAP de testes.

Voltar ao sumário

Descrição dos atributos retornados na autenticação

Esta seção apresenta a descrição dos atributos retornados no ato da autenticação

O campo uid corresponde ao número do cartão do usuário que está autenticando.

O campo cn contém o nome completo do usuário, normalmente em caixa alta.

O campo mail contém o endereço de e-mail do usuário que está cadastrado no portal de serviços. Quando da alteração do e-mail, o novo endereço estará disponível no proximo login do usuário, dessa forma indicamos sempre atualizar o endereço de e-mail a cada login caso ele seja armazenado localmente.

O campo ufrgsVinculo retorna uma string que é constituída pelos seguintes elementos:

estadoVinculo:codVinculo:nomeVinculo:codOrgaoExercicio:nomeOrgaoExercicio:codOrgaoLotacao:nomeOrgaoLotacao:codCurso:nomeCurso:dataIngresso:dataAfastamento

Esta nomenclatura foi definida pelo CPD da UFRGS e deve ser utilizada quando os dados forem exibidos. O CPD se reserva a modificar qualquer um dos campos textuais, portando apenas os dados vindos da autenticação devem ser utilizados para exibição. Este é um dos motivos pelo qual não é recomendado armazenar estes dados locamente para consultas futuras.

Voltar ao sumário