> For the complete documentation index, see [llms.txt](https://guias.mosaico.gov.pt/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guias.mosaico.gov.pt/guias-praticos/integrar-com-o-servico-de-autenticacao/entidade-no-papel-de-fornecedora-de-servicos-de-autenticacao-web.md).
# Entidade no papel de fornecedora de serviços de autenticação web
## **Autenticação baseada em SAML v2.0**
O formato de dados trocados entre o Serviço de Autenticação e as entidades é baseado em SAML v2.0 (Security Assertion Markup Language), de forma a assegurar a autenticidade e a integridade de todas as transações. A utilização do SAML HTTP Post Binding associado ao SAML Web Browser SSO Profile permite que a autenticação seja feita pelo browser do utilizador, sem necessidade de ligação física entre as entidades e o Serviço de Autenticação. As comunicações entre o Serviço de Autenticação e as entidades são efetuadas sobre HTTP em canal cifrado – Secure Socket Layer (SSL) ou Transport Layer Security (TLS). Esta comunicação é feita online.
O Serviço de Autenticação responde à entidade com informação autorizada pelo utilizador. A resposta inclui os atributos solicitados no pedido de autenticação. Esta ligação é também feita sobre HTTP em canal cifrado – SSL ou TLS. A utilização de canais cifrados, associada ao formato específico SAML, garante que a troca de dados segue as seguintes considerações:
* Privacidade de dados – a utilização de canais cifrados garante que os dados do utilizador se mantêm privados, e impede a visualização por terceiros (ex.: por sniffer de rede)
* Integridade de dados – o protocolo SAML, através de assinatura digital nos pedidos e respostas de autenticação SAML, garante a integridade de dados de modificações não autorizadas (ex.: ataque por Man-in-the-Middle). A utilização do Serviço de Autenticação é feita apenas através do ambiente web e online
A imagem acima descreve as interações entre o portal da entidade e o Serviço de Autenticação, ao usar o browser do utilizador como intermediário. As adaptações a realizar pela entidade recaem nos pontos 2 e 4, que correspondem, respetivamente, à criação do pedido de autenticação SAML e a resposta proveniente do Serviço de Autenticação:
• Pedido de autenticação – corresponde ao pedido de identificação pela entidade. Permite reconhecer a origem do pedido, através da assinatura digital por um certificado digital x.509v3 associado à entidade. O pedido tem os atributos que devem ser obtidos (ex.: NIF)
• Resposta de autenticação – apresenta o resultado da autenticação e os atributos pedidos pela entidade. A assinatura digital garante que a informação não foi alterada
## **Autenticação baseada em OAuth**
O fornecedor de autenticação (FA) também utiliza o Implicit Grant do OAuth2 para, além da autenticação, devolver os atributos pedidos em três passos. Primeiro é necessário obter um token de autenticação, em que o processo é semelhante ao fluxo de autenticação via SAML (as mensagens trocadas entre os subsistemas do FA e a CMD são feitos via SAML). De seguida é preciso fazer um pedido REST com o token de forma a iniciar o processo de obtenção de dados, e o FA retorna um identificador do processo de autenticação que o sistema requerente deve utilizar para realizar um ou mais pedidos de obtenção de dados. Este fluxo assíncrono pode ser representado de forma simplificada pelo seguinte esquema:
Autenticação baseada em OAuth
1. É feito um pedido GET ao site do FA com os seguintes parâmetros de entrada (devem ser incluídos como query strings):
a. response\_type – valor token
b. client\_id – identificador do sistema requerente, acordado de forma prévia
c. redirect\_uri – url de redirecionamento para voltar para o sistema requerente. Este parâmetro é opcional e caso não seja enviado será devolvido para uma página estática do FA
d. scope – lista de atributos delimitada com um espaço entre cada um (nota: solicitar, no mínimo, o atributo no caso de pessoas que tenham número de identificação civil, ou para estrangeiros que ainda não o tenham)
e. state – parâmetro que não é utilizado de momento
f. authentication\_level – nível de autenticação pretendido (opcional)
g. default\_selected\_tab – aba que aparece selecionada por defeito (opcional)
h. hidden\_tabs – permite esconder abas. Pode ter vários valores (opcional)
2. É pedido ao utilizador que autorize a leitura dos atributos por parte do sistema requerente. O utilizador depois pode utilizar o Cartão de Cidadão ou a Chave Móvel Digital para se autenticar.
3. Assim que é validada a autenticação com sucesso, é devolvido ao sistema requerente através de parâmetros na query string:
a. token\_type – valor bearer
b. expires\_in – long que representa o tempo de vida do access token
c. access\_token – token gerado pelo FA para se utilizar no segundo passo de obtenção dos atributos
d. refresh\_token – gerado pelo FA para obter novos access\_token sem ter de fazer nova autenticação
4. O sistema requerente, após obtenção do access token no fluxo anterior, envia-o para a API do FA através de um método POST, passando um objecto JSON do tipo:
a. token – valor do token obtido no passo anterior
b. attributesName – lista de strings dos atributos a filtrar. Este parâmetro é opcional e
caso não seja preenchido irá retornar todos os atributos relacionados com o token
c. A API do FA retorna um objeto JSON com os seguintes atributos:
i. token – token obtido no passo anterior
ii. authenticationContextId – identificador do processo de autenticação
5. O sistema requerente deve depois utilizar o token e o authenticationContextId como valores query string num pedido GET para obter os valores dos atributos pedidos.
1. Formato do pedido GET:
\?token=\\&authenticationContextId=\
2. Após o FA validar o token com sucesso é devolvida a lista em JSON de atributos com o respetivo estado e valor (se já obtido). Os atributos que ainda não tenham sido obtidos são devolvidos com o valor null; como a obtenção poderá demorar algum tempo, dependendo dos atributos pedidos e de sistemas externos, os atributos pedidos poderão não estar disponíveis na altura em que é feito o pedido ao sistema FA – cabe ao sistema requerente decidir como agir nestas situações. A única restrição é que não seja feito mais de um pedido por segundo à API do FA. Cada atributo poderá estar num dos seguintes estados:
**Available** – A entidade responsável pelo envio do atributo já enviou o valor.
**NotAvailable** – A entidade responsável pelo envio do atributo não conseguiu encontrar e responder com o valor do atributo.
**Pending** – A entidade responsável pelo envio do atributo ainda não retornou o valor.