O Single Sign-on (SSO) é um serviço que permite o utilizador identifica-se apenas uma vez e ter acesso a múltiplas aplicações, melhorando assim a sua experiência na utilização de serviços online. O Autentika permite a aplicações autenticar os seus utilizadores utilizando o protocolo OpenID Connect.
Este documento descreve como o Autentika implementa o protocolo OpenID Connect, incluindo os detalhes da iteração entre uma Aplicação e o Autentika durante o processo de autenticação.
Para que a sua aplicação possa utilizar o serviço de autenticação do Autentika, a mesma tem de estar registada. Para o registo o desenvolvedor deve fornecer os seguintes detalhes:
Após o registo, são fornecidos os seguintes detalhes ao desenvolvedor da aplicação:
A listagem a seguir apresenta os endpoints do OpenID Connect (do Autentika):
| Endpoint | Url |
|---|---|
| Authorization Endpoint | https://autentika.gov.cv/oauth2/authorize |
| Token Endpoint | https://autentika.gov.cv/oauth2/token |
| Token Revocation Endpoint | https://autentika.gov.cv/oauth2/revoke |
| Token Introspection Endpoint | https://autentika.gov.cv/oauth2/introspect |
| User Info Endpoint | https://autentika.gov.cv/oauth2/userinfo |
| Session IFrame Endpoint | https://autentika.gov.cv/oidc/checksession |
| Logout Endpoint | https://autentika.gov.cv/oidc/logout |
Mais detalhes dos endpoints OpenID Connect encontra-se nesta página.
A sua aplicação deve implementar as especificações da Autenticação OpenID. Os detalhes dessa especificação encontram-se definidas nesta página.
Os principais frameworks de desenvolvimento modernos possuem bibliotecas/plugins que implementam as especificações da Autenticação OpenID.
A autenticação do utilizador consiste em enviar uma requisição de autenticação, redirecionando o utilizador para o Autentika com o objetivo de obter uma Token de identidade (ID Token). O ID Token consiste numa JSON Web Token que codifica os dados de identidade do utilizador.
Existem diferentes tipos de concessão de autorização segundo a especificação. Neste documento está descrito a concessão de autorização utilizando um código (Authorization Code).
A aplicação executa os seguintes passos para autenticar o utilizador:
A aplicação inicia o processo de autenticação, preparando uma requisição de autenticação e redirecionando o utilizador para o Autentika. Essa requisição é uma requisição de autorização OAuth 2.0 para autenticação do utilizador (o pedido de autenticação é especificado passando o valor openid no parametro scope).
Segue um exemplo de um redireccionamento de autenticação:
HTTP/1.1 302 Found
Location: https://autentika.gov.cv/oauth2/authorize?
response_type=code
&scope=openid
&client_id=s6BhdRkqt3
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fexemplo.app.cv%2Fcb
A listagem a seguir caracteriza cada um dos parâmetros da requisição acima:
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| scope | Sim | Especifica o escopo da requisição. A requisição OpenID deve conter o valor onpenid nesse parâmetro. Valores adicionais podem ser incluidos no parâmetro scope |
| response_type | Sim | Indica o tipo de concessão de autorização. Utilize o valor code para a concessão do tipo código |
| client_id | Sim | O id que identifica a aplicação no Autentika. Esse valor é atribuído no momento do registo da aplicação no Autentika |
| state | Não* | Valor opaco utilizado para manter o estado entre a requisição e a chamada de volta (entre a aplicação e o Autentika) |
| redirect_uri | Sim | URI de redireccionamento por onde o utilizador será redirecionado após autenticar-se. Essa URI deve ser exatamente igual ao fornecido no registo da aplicação |
Ao receber esta requisição, o Autentika executa as seguintes ações:
Exemplo dum retorno para a aplicação:
HTTP/1.1 302 Found
Location: https://exemplo.app.cv/cb?
code=SplxlOBeZQQYbYS6WxSbIA
&state=af0ifjsldkj
A aplicação deve validar o parâmetro state e proceder para a troca do código pelo ID Token.
A aplicação requisita o token de acesso e o ID Token ao Autentika, utilizando o código recebido e identificando-se com o seu ID e a sua chave secreta. Essa requisição deve ser realizada no backend e possui a vantagem de não expor os tokens ao agente do utilizador (web browser) e garantir a autenticação da aplicação no Autentika.
Segue-se um exemplo de uma requisição por um token:
POST /oauth2/token HTTP/1.1
Host: autentika.gov.cv
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fexemplo.app.cv%2Fcb
O ID da aplicação e a sua chave secreta são enviadas no cabeçalho de autorização (Authorization header).
Descrição dos parâmetros da requisição:
Após validar a requisição o Autentika retorna um objeto JSON, incluindo o ID token e o token de acesso, como mostra o seguimento a seguir:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
"access_token": "SlAV32hkKG",
"token_type": "Bearer",
"expires_in": 3600,
}
O seguimento a seguir exemplifica a resposta a uma requisição inválida:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_request"
}
A aplicação deve validar o ID Token antes da sua utilização.
O token de acesso será utilizado na requisição de informações do perfil do utilizador.
A aplicação utiliza o token de acesso na requisição às informações de perfil (claims) do utilizador autenticado. Na solicitação, pode especificar um escopo que inclui um conjunto de atributos ou pode especificar cada atributo individualmente.
A resposta do Autentika consiste num objeto JSON que contém os claims/atributos do utilizador em forma de pares nome e valor.
Por exemplo, a requisição às informações do utilizador incluindo o escopo email (scope=openid%20email) segue o seguinte formato:
HTTP/1.1 302 Found
Location: https://autentika.gov.cv/oauth2/authorize?
response_type=code
&scope=openid%20email
&client_id=s6BhdRkqt3
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fexemplo.app.cv%2Fcb
Exemplo da resposta com as informações do utilizador (ao chamar o /oauth2/userinfo), seria por exemplo:
HTTP/1.1 200 OK
Content-Type: application/json
{
"sub": "248289761001",
"name": "Pedro Ramos",
"given_name": "Pedro",
"email": "pedro.ramos@nosi.cv",
}
São retornados apenas os atributos que o utilizador tiver preenchido no seu perfil.
Garanta que a sua aplicação solicite apenas os atributos essenciais, pois o aumento do número de atributos solicitados diminui a chance do utilizador conceder a autorização (aprovar a partilha dos dados).
Após obter as informações do utilizador a aplicação determina se trata de um novo utilizador ou se trata de um utilizador já registado.
Caso for um utilizador já registado, por exemplo uma aplicação web poderá iniciar a sessão para esse utilizador. Ao navegar entre as páginas a aplicação verifica se o utilizador está autenticado a partir dos dados de sessão.
Caso for a primeira vez que o utilizador visita a aplicação (novo utilizador), é criada a sua conta com base nas informações recebidas do Autentika (como por exemplo o nome e o email). Caso essas informações não forem suficientes para o registo a aplicação poderá solicitar dados adicionais ao utilizador.