1. Leitores-alvo

O principal objetivo de implementar OAuth 2.0 é proteger as APIs da Web por tokens de acesso. Portanto, todos vocês finalmente precisarão ler este documento.

O que as pessoas querem fazer é proteger suas APIs web por tokens de acesso, mas eles logo perceberão que têm que implementar RFC 6749 (OAuth 2.0) como pré-requisito. O Authlete existe para mitigar a carga para implementar a especificação e permitir que você se concentre na implementação de suas APIs web.

2. O que é “Ponto final de recurso protegido”?

As APIs web protegidas por tokens de acesso OAuth 2.0 são chamadas pontos finais de recursos protegidos. Esses pontos finais fazem o seguinte antes de devolver os dados solicitados aos aplicativos do cliente.

1. Extrair um token de acesso de uma solicitação.
2. Obtenha informações detalhadas sobre o token de acesso do servidor de autorização.
3. Valide o token de acesso.

As seções a seguir descrevem como fazer isso.

3. Extrair token de acesso

Como um ponto final de recurso protegido deve aceitar um token de acesso de um aplicativo cliente? É possível criar quantas novas maneiras de fazer isso você quiser. No entanto, não temos que reinventar a roda. RFC 6750 (Uso de token do portador) já definiu três maneiras de aceitar um token de acesso conforme listado abaixo.

1. Via Authorization cabeçalho. (2.1. Campo de cabeçalho de solicitação de solicitação de autorização)
2. Através de um parâmetro de formulário access_token. (2.2. Parâmetro do corpo codificado por formulário)
3. Através de um parâmetro de consulta access_token. (2.3. Parâmetro de consulta uri)

A maneira mais desejável é a primeira e RFC 6750 Diz “Os servidores de recursos devem suportar esse método”. Simplesmente dizendo, quando um aplicativo cliente usa a primeira maneira, um ponto final de recurso protegido pode encontrar um cabeçalho HTTP como abaixo na solicitação.

Authorization: Bearer access-token

Abaixo estão exemplos para extrair um token de acesso.

• >Java (JAX-RS)
• Ruby (Sinatra)
• PHP

padrão final estático privado CHALLENGE\_PATTERN
\= Pattern.compile("^Portador \*(\[^]+) \*$", Pattern.CASE\_INSENSITIVE);

/\*\*

*   Ponto de entrada para o método GET.
    \*/
    @GET
    resposta pública obter(
    @HeaderParam (HttpHeaders.AUTHORIZATION) Autorização de string,
    @QueryParam ("access\_token") Acesso à seqüênciatoken)
    {
    Extrair um token de acesso do cabeçalho ou uso da Autorização
    o valor do parâmetro de consulta 'access\_token'.
    accessToken = extratoAken (autorização, acessoToken);
    }

/\*\*

*   Ponto de entrada para o método POST.
    \*/
    @POST
    @Consumes(MediaType.APPLICATION\_FORM\_URLENCODED)
    post de resposta pública(
    @HeaderParam (HttpHeaders.AUTHORIZATION) Autorização de string,
    @FormParam ("access\_token") Acesso à cordaToken)
    {
    Extrair um token de acesso do cabeçalho ou uso da Autorização
    o valor do parâmetro de forma 'access\_token'.
    accessToken = extratoAken (autorização, acessoToken);
    }

/\*\*

*   Extrair um token de acesso do cabeçalho autorização ou retornar
*   o valor do parâmetro de solicitação 'access\_token'.
    \*/
    extrato de string estática privadaAccessToken(
    Autorização de string, String accessToken)
    {
    Se o cabeçalho autorização não for encontrado na solicitação.
    se (autorização == nulo)
    {
    Devolva o valor do parâmetro de solicitação 'access\_token'.
    acesso de retornoToken;
    }

    Correspondência de padrões no valor do cabeçalho autorização.
    Matcher matcher = CHALLENGE\_PATTERN.matcher (autorização);

    Se o valor do cabeçalho autorização estiver no formato de
    'Bearer access-token'.
    se (matcher.match())
    {
    Devolva o valor extraído do cabeçalho autorização.
    retorno matcher.group(1);
    }
    mais
    {
    Devolva o valor do parâmetro de solicitação 'access\_token'.
    acesso de retornoToken;
    }
    }

# Método para extrair um token de acesso de uma solicitação.

def extract\_access\_token(solicitação)

# O valor do cabeçalho autorização.

cabeçalho = request.env\["HTTP\_AUTHORIZATION"]

# Se o valor estiver no formato de 'Bearer access-token'.

se /^Bearer\[]+(.+)/i =~ cabeçalho
\# Devolva o valor extraído do cabeçalho autorização.
devolver $1
fim

# Devolva o valor do parâmetro de solicitação 'access\_token'.

solicitação de retorno \["access\_token"]
fim

# Ponto de entrada para o método GET.

obter '/Olá' do

# Extrair um token de acesso da solicitação.

access\_token = extract\_access\_token(solicitação)
fim

# Ponto de entrada para o método POST.

postar '/Olá' do

# Extrair um token de acesso da solicitação.

access\_token = extract\_access\_token(solicitação)
fim

/\*\*

*   Função para extrair um token de acesso de uma solicitação.
    \*/
    extract\_access\_token de função()
    {
    O valor do cabeçalho autorização.
    $header = $\_SERVER\['HTTP\_AUTHORIZATION'];

    Se o valor estiver no formato de 'Bearer access-token'.
    se ($header != nulo && preg\_match('/^Portador\[]+(.+)/i', $header, $captured))
    {
    Devolva o valor extraído do cabeçalho autorização.
    $captured de retorno;
    }

    se ($\_SERVER\['REQUEST\_METHOD'] == 'GET')
    {
    Devolva o valor do parâmetro de consulta 'access\_token'.
    devolver $\_GET \['access\_token'];
    }
    mais
    {
    Retorne o valor do parâmetro de formulário 'access\_token'.
    devolver $\_POST \['access\_token'];
    }
    }

4. Token de acesso introspect

RFC 7662

O processo para obter informações detalhadas sobre um token de acesso é chamado introspecção. Como introspecr um token de acesso depende de cada implementação dos servidores de autorização OAuth 2.0.

No entanto, em outubro de 2015, RFC 7662 (OAuth 2.0 Token Introspection) foi lançado como uma especificação padrão para introspecção. Se um servidor de autorização que você estiver usando suporta rfc 7662, seus pontos finais de recursos protegidos podem introspectar tokens de acesso sem depender de uma implementação específica do servidor de autorização. Mas, ainda assim, como proteger o ponto final de introspecção em si depende de cada implementação como mencionado em “2.1. Solicitação de introspecção” de “RFC 7662”.

Da RFC 7662, 2.1. Solicitação de Introspecção;

Para evitar ataques de digitalização de tokens, o ponto final também deve exigir alguma forma de autorização para acessar este ponto final, como a autenticação do cliente, conforme descrito no OAuth 2.0 [RFC 6749] ou um token de acesso OAuth 2.0 separado, como o token portador descrito no OAuth 2.0 Bearer Token Usage [RFC 6750]. Os métodos de gerenciamento e validação dessas credenciais de autenticação estão fora de escopo desta especificação.

API de introspecção Authlete

Authlete fornece uma API de introspecção em /auth/introspection. A implementação da API não está em conformidade com a RFC 7662, mas do ponto de vista daqueles que desenvolvem pontos finais de recursos protegidos, nossa API é melhor que a RFC 7662 conforme listado abaixo.

1. Você pode delegar validação à nossa API de introspecção.
2. Nossa API de introspecção gera uma mensagem de erro que cumpre RFC 6750 quando um determinado token de acesso é inválido.

Simplesmente dizendo, API de introspecção de Authlete faz introspecção + validação + construindo uma mensagem de erro cumprindo com rfc 6750. Você pode encontrar a especificação detalhada da API de introspecção da Authlete em Documento de APIs da Web Authlete.

5. Validar o Token de Acesso

O próximo passo depois de obter informações detalhadas sobre um token de acesso é validar o token de acesso. A validação envolve as seguintes etapas.

1. Expirou ou não?
2. Foi revogada ou não?
3. Cobre as permissões necessárias?
4. Está associado ao usuário final esperado?

Como mencionado, você pode delegar validação para a API de introspecção da Authlete, se quiser. scopes e subject são parâmetros opcionais para a API de introspecção para especificar os escopos (= permissões) que o ponto final de recurso protegido requer e o assunto (= identificador exclusivo) de um usuário final que o ponto final de recurso protegido espera.

Se você utilizar scopes parâmetro e subject parâmetro de acordo com suas necessidades, você não precisa escrever código de validação separado.

6. Resposta de erro

Se você quiser cumprir RFC 6750, as respostas dos pontos finais de recursos protegidos devem conter o cabeçalho WWW-Authenticate sobre erros. O formato detalhado do valor do cabeçalho é descrito em “3. O campo de cabeçalho de resposta www-autenticado”. O formato não é tão simples como você pode imaginar. Abaixo está um exemplo com parâmetros mencionados em RFC 6750 (alguns são opcionais, porém).

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example",
                  scope="read write",
                  error="invalid_token",
                  error_description="The access token expired",
                  error_uri="http://example.com/error/123"

Você pode ser seduzido a ignorar essa especificação porque você pode duvidar que vale a pena fazer um esforço apenas para contar detalhes de erro para aplicativos de clientes. No entanto, você não precisa fazer um compromisso se você usar a API de introspecção da Authlete. É porque uma resposta da API contém responseContent propriedade cujo valor pode ser usado como o valor de WWW-Authenticate cabeçalho. Como resultado, você pode facilmente construir uma resposta de erro como abaixo.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Just embed responseContent here.

7. Despacho de acordo com o resultado de validação

Se um erro for detectado na validação, um ponto final de recurso protegido deve retornar 400 Bad Request, 401 Unauthorized ou 403 Forbidden (ou 500 Internal Server Error), com base na causa do erro.

Por outro lado, quando um token de acesso é válido, um ponto final de recurso protegido pode gerar qualquer resposta que ele gosta. Em um caso típico, ele retornará o recurso solicitado no formato JSON com 200 OK à aplicação do cliente.

Para facilitar o envio com base no resultado de validação, uma resposta da API de introspecção da Authlete contém action propriedade. É uma sequência que representa o próximo action você deve tomar. Valores de ação e seus significados são os seguintes.

Abaixo estão as implementações de exemplo para despachar de acordo com o resultado de validação. Cada método/implementação de função (1) aceita um token de acesso [obrigatório], uma matriz de sequência de escopos [opcional] e um assunto [opcional], (2) chama a API de introspecção e (3) despacha o fluxo de acordo com o valor de action propriedade na resposta da API de introspecção. Quando action não é OK, responseContent propriedade na resposta da API de introspecção é usado como o valor de WWW-Authenticate cabeçalho na resposta a um aplicativo cliente.

• >Java (JAX-RS)
• Ruby (Sinatra)
• PHP

/\*\*

*   Ligue para a API/auth/introspecção da Authlete.
*   Uma resposta da API é devolvida quando o
*   o token de acesso é válido. Caso contrário, um
*   WebApplicationException é levantado.
    \*/
    introspecção estática privadaResponse doIntrospection(
    Acesso de stringToken, string\[] escopos, sujeito string)
    {
    Ligue para a API/auth/introspecção da Authlete.
    Resposta de resposta de introspecção = chamadaIntrospectionApi (accessToken, escopos, assunto);

    O valor do cabeçalho 'WWW-Authenticate' no erro.
    Conteúdo de string = response.getResponseContent();

    status int;

    Confira a próxima ação.
    switch (response.getAction())
    {
    INTERNAL\_SERVER\_ERROR caso:
    500 erros internos do servidor.
    O pedido de API desta implementação estava errado
    ou um erro ocorreu em Authlete.
    status = 500;
    quebrar;

         case BAD_REQUEST:
             // 400 Bad Request.
             //   The request from the client application does not
             //   contain an access token.
             status = 400;
             break;

         case UNAUTHORIZED:
             // 401 Unauthorized.
             //   The presented access token does not exist or has expired.
             status = 401;
             break;

         case FORBIDDEN:
             // 403 Forbidden.
             //   The access token does not cover the required scopes
             //   or the subject associated with the access token is
             //   different.
             status = 403;
             break;

        case OK:
             // The access token is valid (= exists and has not expired).
             return response;

         default:
             // This never happens.
             throw new WebApplicationException("Unknown action", 500);

    }

    Resposta res = Resposta
    .status(status)
    .header (HttpHeaders.WWW\_AUTHENTICATE, conteúdo)
    .build();

    lançar novo WebApplicationException(res);
    }

\#--------------------------------------------------

# Ligue para a API/auth/introspecção da Authlete.

# Uma resposta da API é devolvida quando o

# o token de acesso é válido. Caso contrário, um WebException

# é levantada.

\#--------------------------------------------------
def do\_introspection (token, escopos, assunto)

# Ligue para a API/auth/introspecção da Authlete.

resposta = call\_introspection\_api (token, escopos, assunto)

# O valor do cabeçalho 'WWW-Authenticate' no erro.

conteúdo = resposta\["respostaContent"]

# "Ação" denota a próxima ação.

resposta de caso \["ação"]
quando "INTERNAL\_SERVER\_ERROR"
\# 500 Erro do servidor interno
\# O pedido de API desta implementação estava errado
\# ou um erro ocorreu em Authlete.
criar WebResponse.new(500).wwwAuthenticate(content).to\_exception

quando "BAD\_REQUEST"
\# 400 Pedido ruim
\# A solicitação do aplicativo do cliente não
\# contenha um token de acesso.
levantar o WebResponse.new(400).wwwAuthenticate(content).to\_exception

quando "NÃO AUTORIZADO"
\# 401 Não Autorizado
\# O token de acesso apresentado não existe ou expirou.
criar WebResponse.new(401).wwwAuthenticate(content).to\_exception

quando "PROIBIDO"
\# 403 Proibido
\# O token de acesso não cobre os escopos necessários
\# ou o assunto associado ao token de acesso é
\# diferente.
criar WebResponse.new(403).wwwAuthenticate(content).to\_exception

quando "OK"
\# O token de acesso é válido (= existe e não expirou).
resposta de retorno

mais
Isso nunca acontece.
levantar o WebResponse.new(500, "Ação desconhecida").plain.to\_exception
fim
fim

/\*\*

*   Ligue para a API/auth/introspecção da Authlete.
*   Uma resposta da API é devolvida quando o
*   o token de acesso é válido. Caso contrário, um WebException
*   é levantada.
    \*/
    do\_introspection de função ($token, $scopes, $subject)
    {
    Ligue para a API/auth/introspecção da Authlete.
    $response = call\_introspection\_api($token, $scopes, $subject);

    valor do cabeçalho 'WWW-Authenticate' no erro.
    $content = $response\['responseContent'];

    "Ação" denota a próxima ação.
    switch ($response\['action'])
    {
    caso 'INTERNAL\_SERVER\_ERROR':
    500 erros internos do servidor
    O pedido de API desta implementação estava errado
    ou um erro ocorreu em Authlete.
    (novo WebResponse(500)->wwwAuthenticate($content)->finish();
    retorno nulo; Não alcance aqui.

         case 'BAD_REQUEST':
             // 400 Bad Request
             //   The request from the client application does not
             //   contain an access token.
             (new WebResponse(400))->wwwAuthenticate($content)->finish();
             return null; // Not reach here.

         case 'UNAUTHORIZED':
             // 401 Unauthorized
             //   The presented access token does not exist or has expired.
             (new WebResponse(401))->wwwAuthenticate($content)->finish();
             return null; // Not reach here.

         case 'FORBIDDEN':
             // 403 Forbidden
             //   The access token does not cover the required scopes
             //   or the subject associated with the access token is
             //   different.
             (new WebResponse(403))->wwwAuthenticate($content)->finish();
             return null; // Not reach here.

         case 'OK':
             // The access token is valid (= exists and has not expired).
             return $response;

         default:
             // This never happens.
             (new WebResponse(500, "Unknown action"))->plain()->finish();
             return null; // Not reach here.

    }
    }

8. Amostra de ponto final

Esta seção mostra implementações de exemplo para (1) extrair um token de acesso e (2) validar o token de acesso em um ponto final de recurso protegido (a chamada API web). Cada implementação requer dois escopos, read e write.

• >Java (JAX-RS)
• Ruby (Sinatra)
• PHP

sequência final privada\[] SCOPES = {"ler", "escrever" };

@GET
olá resposta pública(
@HeaderParam (HttpHeaders.AUTHORIZATION) Autorização de string,
@QueryParam ("access\_token") Acesso à seqüênciatoken)
{
Extrair um token de acesso da solicitação.
accessToken = extratoAken (autorização, acessoToken);

    // Introspect and validate the access token.
    IntrospectionResponse response = doIntrospection(accessToken, SCOPES, null);

    // The access token is valid. Write the main code after here.
    ......

}

obter '/Olá' do

# Extrair um token de acesso da solicitação.

token = extract\_access\_token(solicitação)

começar
\# Introspect e valide o token de acesso.
resposta = do\_introspection(token, \["ler", "escrever"], nil)
resgatar WebException => e
\# O token de acesso é inválido.
e.to\_response de retorno
fim

# O token de acesso é válido. Escreva o código principal depois daqui.

......
fim

<?php
require('../include/introspection-functions.php');

// Extract an access token from the request.
$token = extract_access_token();

// Introspect and validate the access token.
$response = do_introspection($token, ['read', 'write'], null);

// The access token is valid. Write the main code after here.
......
?>

9. Escopo

Como os escopos são usados?

No contexto da OAuth, âmbito é um termo técnico e representa uma permissão. Quando um aplicativo de cliente faz uma solicitação de autorização para um endpoint de autorização de um serviço, o aplicativo pode listar escopos que deseja usando scope parâmetro. A seguir, uma solicitação de autorização de exemplo especificando dois escopos: read e write.

https://host/authorize?response_type=token&client_id=your-client-id&scope=read+write

Depois que o usuário final autoriza a solicitação de autorização, o servidor de autorização emite um token de acesso que está associado aos escopos. O aplicativo cliente usa o token de acesso quando acessa pontos finais de recursos protegidos do serviço. A seguir, uma solicitação de recurso protegido por exemplo que usa access_token parâmetro de consulta para passar por um access token para um ponto final de recurso protegido.

https://host/profile?access_token=access-token

Um ponto final de recurso protegido extrai um token de acesso da solicitação de recurso protegido e valida o token de acesso. Em um caso típico, uma implementação do ponto final de recurso protegido verifica se o token de acesso apresentado está associado a escopos que o ponto final requer. A seguir, um código conceitual para extrair e validar um token de acesso.

// Extract an access token from the protected resource request.
access_token = extract_access_token_from_request(request);

// If the access token has expired.
if (access_token.has_expired) {
    return unauthorized;
}

// Scopes associated with the access token.
scopes = access_token.scopes;

// If the access token covers "read" and "write".
if (scopes.contains("read") && scopes.contains("write")) {
    return ok;
} else {
    return forbidden;
}

Definição de nome de escopo

Um nome de escopo é um caractere ASCII sensível a maiústos. A especificação exata é descrita em “RFC 6749, 3.3. Escopo de token de acesso”, como mostrado abaixo. %x20 (espaço), %x22 (marca de cotação dupla) e %x5C (barra traseira) não é permitido usar.

scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

De acordo com a especificação, %x2C (vírgula) pode ser usado para nomes de escopo, mas o Facebook usa vírgulas como delimitador para listar nomes de escopo. É uma violação contra a especificação.

Escopos padrão

Núcleo de conexão OpenID 1.0 definiu alguns escopos padrão. A tabela abaixo é a lista.

Registro de escopo

Os escopos precisam ser registrados com antecedência antes do uso. Como cadastrar os escopos depende de cada implementação do servidor de autorização.

Authlete fornece GUI para você editar a lista de escopos suportados pelo seu serviço. Login Console do proprietário de serviço, clique no botão “Editar” de um serviço cujos escopos deseja editar e clique na guia “Token”. Você pode ver “escopos suportados” na parte inferior como abaixo.

Depois de editar a lista, não se esqueça de pressionar “Atualizar” para aplicar alterações.

10. Resumo

Authlete fornece uma API de introspecção (/api/auth/introspection) para implementações de pontos finais de recursos protegidos. A API é melhor do que RFC 7662 porque ele não só introspecção, mas também validação e construção de uma mensagem de erro cumprindo RFC 6750.