Provedor de Segurança - OAuth¶

O provedor de segurança OAuth integra-se a aplicativos de externo usando o fluxo de concessão de código de autorização OAuth 2.0, conforme documentado no padrão OAuth 2.0: https://tools.ietf.org/html/rfc6749

Neste fluxo, o Vinyl redireciona o agente do usuário para o servidor de autorização. Depois que o usuário tiver entrado com sucesso no servidor de autorização e aprovado a solicitação de autorização, o agente do usuário será redirecionado de volta ao Vinyl. O redirecionamento inclui um código de autorização. O Vinyl faz uma solicitação de back-channel ao servidor de autorização, trocando o código de autorização por um token de acesso. O token de acesso pode então ser usado para autorizar solicitações a serviços da web

Por si só, o OAuth fornece autorização, não autenticação. Portanto, os provedores de segurança OAuth normalmente não são usados como provedores de autenticação externa: eles são usados para autorizar solicitações a um provedor de dados compatível, como OData ou REST. No entanto, se o provedor de segurança OAuth publicar um endpoint que forneça a identidade do usuário, o provedor de segurança OAuth poderá ser usado como um provedor de autenticação externo. Consulte UserInfoEndpoint para obter detalhes adicionais.

Se a solicitação do token de acesso incluir um token de atualização, o Vinyl tentará automaticamente usar o token de atualização para adquirir um novo token de acesso após receber uma resposta 401 Não Autorizado.

Configurando OAuth¶

O Vinyl oferece suporte à estrutura de autorização OAuth 2.0 (https://tools.ietf.org/html/rfc6749). Especificamente, o provedor de segurança OAuth do Vinyl pode trabalhar em conjunto com os provedores de segurança HTTP e OData para autorizar o acesso a recursos REST e OData usando o fluxo de código de autorização (https://tools.ietf.org/html/rfc6749#section-1.3.1). Neste fluxo, o Vinyl assume o papel de “cliente”, delegando a autenticação a um servidor de autorização OAuth.

Autenticação Vs. Autorização¶

Ao contrário da maioria dos outros provedores de segurança, o provedor de segurança OAuth é um provedor de autorização. OAuth, por si só, não identifica um usuário. Em vez disso, o processo de login do OAuth produz um token que pode ser usado para acessar recursos em nome de um usuário. Conseqüentemente, o OAuth normalmente não pode ser usado para autenticar usuários. Em vez disso, é usado para estender a autorização de um usuário autenticado.

Em termos práticos, isso significa que um provedor de segurança OAuth não pode ser apresentado como uma opção de login no formulário de login (ou seja, Mostrar no formulário de login). Em vez disso, os usuários serão solicitados a entrar no provedor de segurança OAuth quando tentarem acessar um recurso (REST ou OData) que exija uma autorização OAuth. Neste cenário, o Vinyl lançará um “desafio”. O cliente web interceptará o desafio e redirecionará o navegador para o formulário de login. No entanto, se o Redirect On Challenge estiver ativado, o cliente web ignorará o formulário de login, redirecionando o usuário para o provedor OAuth.

Observe, entretanto, que alguns fornecedores estenderam o protocolo OAuth para incluir autenticação. Normalmente, isso é feito publicando um endpoint separado que identifica o usuário. Embora não faça parte do padrão OAuth, o Vinyl oferece suporte a esses protocolos de autenticação, desde que o endpoint atenda a vários requisitos. Consulte a documentação do provedor de segurança OAuth para obter informações adicionais.

Integração com Provedores OAuth¶

Muitos serviços de nuvem e APIs oferecem suporte ao OAuth 2.0. As etapas para instalar e configurar o OAuth variam de acordo com o provedor. No entanto, o procedimento fundamental é o mesmo.

1. Determine o URI de redirecionamento.
2. Registre o Vinyl como um aplicativo cliente no provedor OAuth.
3. Crie o provedor OAuth no Vinyl.
4. Crie um provedor de autenticação de fonte de dados (HTTP ou OData) dentro do Vinyl.
5. Crie um servidor de origem de dados (REST ou OData) que utilize o provedor de autenticação de origem de dados.

Determine o URI de Redirecionamento¶

O endpoint de autorização OAuth (https://tools.ietf.org/html/rfc6749#section-4.1.1) define um parâmetro redirect_uri (https://tools.ietf.org/html/rfc6749#section-3.1.2). Às vezes, isso é chamado de URL de "retorno de chamada". O redireccionamento_uri é definido pelo Vinyl. É uma URL absoluta para a qual os usuários serão redirecionados após fazer login no provedor OAuth.

Um redirecionamento_uri será parecido com isto:

https://example.com/Vinyl/signin-Acme

Este exemplo pressupõe que o Vinyl está hospedado no seguinte URL:

https://example.com/Vinyl/

O restante do redirect_uri assume o seguinte formato:

signin-<provider-name>

Onde <provider-name> é o nome do provedor de segurança do Vinyl. No exemplo acima, o nome do provedor é Acme. Observe que o nome deve ser codificado em URL conforme RFC 3986 (https://tools.ietf.org/html/rfc3986).

Portanto, para determinar o redirect_uri, você precisará saber o seguinte:

• O URL raiz do Vinyl.
• O nome do provedor de segurança.

Registre o Vinyl Como um Aplicativo Cliente com o Provedor OAuth¶

Conforme observado acima, o Vinyl é um cliente OAuth. Os clientes OAuth devem ser pré-registrados no servidor de autorização. O procedimento varia de acordo com o provedor.

Dito isto, o processo de registro exigirá o redirect_uri. Assim que o registro for concluído, o provedor OAuth fornecerá valores para os seguintes parâmetros OAuth:

• client_id - O parâmetro client_id identifica o cliente Vinyl.
• client_secret - O client_secret é usado para autenticar solicitações de token de acesso.
• scope - O parâmetro scope é usado para limitar a autorização. O parâmetro scope é opcional e muitas vezes não é utilizado.

Além dos parâmetros OAuth mencionados acima, o Vinyl exigirá os seguintes endpoints:

• endpoint de autorização - O Vinyl redirecionará os agentes do usuário para o endpoint de autorização. Exemplo: http://example.com/oauth/authorize
• Token endpoint - O Vinyl fará uma solicitação de back-channel ao token endpoint para trocar um código de autorização por um token de acesso. Exemplo: http://example.com/oauth/token

Normalmente, esses endpoints não são específicos do cliente e podem ser encontrados na documentação do provedor OAuth.

Crie o Provedor OAuth no Vinyl¶

Para criar um provedor OAuth, comece entrando no Vinyl como administrador.

1. Navegue até o Centro de Controle
2. Clique no botão Provedores de segurança
3. No painel Autenticação de fonte de dados, clique no botão Criar

4. Forneça o seguinte:

   • Nome: {Nome do provedor OAuth}

     Exemplo: Acme

   • Tipo: OAuth

   • Prioridade: Um número inteiro exclusivo entre 10 e 100. Observe que esse valor deve ser exclusivo.

     Exemplo: 50

   • Ativado: Verifique

5. Clique no botão Salvar

6. Defina as propriedades a seguir. No painel Propriedades, clique no botão Criar → Selecione o parâmetro → Forneça o valor → Clique no ícone Salvar.

   • AuthorizationEndpoint: o URI do endpoint de autorização fornecido pelo provedor OAuth.

     Example: http://example.com/oauth/authorize

   • TokenEndpoint: o URI do endpoint do token fornecido pelo provedor OAuth.

     Example: http://example.com/oauth/token

   • ClientId: O parâmetro client_id fornecido pelo provedor OAuth.

   • ClientSecret: O parâmetro client_secret fornecido pelo provedor OAuth.

Crie um Provedor de Autenticação de Fonte de Dados (http Ou OData) no Vinyl¶

Para criar um provedor de autenticação de fonte de dados, comece entrando no Vinyl como administrador.

1. Navegue até o Centro de Controle
2. Clique no botão Provedores de segurança
3. No painel Autenticação de fonte de dados, clique no botão Criar

4. Forneça o seguinte:

   • Nome: {Nome do provedor da fonte de dados}

     Exemplo: AcmeDS

   • Tipo: HTTP ou OData

   • Prioridade: Um número inteiro exclusivo entre 10 e 100. Observe que esse valor deve ser exclusivo.

     Exemplo: 60

   • Ativado: Verifique

5. Clique no botão Salvar

6. Defina as propriedades a seguir. No painel Propriedades, clique no botão Criar → Selecione o Parâmetro → Forneça o Valor → Clique no ícone Salvar.

7. AuthenticationType: AuthorizationCode

8. OAuthProvider: {Nome do provedor OAuth}

   Exemplo: Acme

Crie um servidor de fonte de dados (REST ou OData) que utilize o provedor de autenticação de fonte de dados.

Instalar e configurar um servidor de origem de dados está além do escopo deste documento. Consulte exemplos específicos para obter mais informações.

Concessões OAuth 2.0¶

Fluxo de Código de Autorização (delegado)¶

O fluxo do código de autorização OAuth 2.0 fornece autenticação em nível de usuário. Neste fluxo, os códigos de autorização são trocados por tokens de acesso OAuth. O fluxo do código de autorização OAuth 2.0 é padronizado em RFC 6749.

Ao contrário dos esquemas de autenticação Anônimo e HTTP Básico, o fluxo do Código de Autorização deve ser explicitamente habilitado. Isso é feito associando uma fonte de dados a um provedor de segurança OData que possui um tipo de autenticação "AuthorizationCode".

Além disso, o fluxo do código de autorização OAuth funciona em conjunto com um provedor de segurança OAuth. O provedor de segurança OAuth é responsável por autorizar o usuário e trocar códigos de autorização por tokens de acesso.

Configuração¶

Parâmetros¶

Os parâmetros a seguir habilitam e configuram o fluxo do código de autorização OAuth 2.0:

Fluxo de Credenciais do Cliente¶

O fluxo de credenciais do cliente OAuth 2.0 fornece autenticação no nível do cliente, semelhante a uma conta de serviço. Neste fluxo, as credenciais do cliente OAuth são trocadas por um token de acesso OAuth. O fluxo de credenciais do cliente OAuth 2.0 é padronizado em RFC 6749.

Configuração¶

Parâmetros¶

Os parâmetros a seguir habilitam e configuram o fluxo de credenciais do cliente OAuth 2.0:

Fluxo de Token Portador do Token da Web JSON¶

O fluxo Bearer Token (JWT) JSON Web Token do OAuth 2.0 fornece autenticação em nível de usuário. Neste fluxo, os JWTs são trocados por tokens de acesso OAuth. O fluxo do OAuth 2.0 JWT Bearer Token é padronizado em RFC 7523.

Configuração¶

Parâmetros¶

Os parâmetros a seguir habilitam e configuram o fluxo do token de portador JWT do OAuth 2.0:

Fluxo de Credenciais de Senha do Proprietário do Recurso¶

O fluxo de credenciais de senha do proprietário do recurso é definido em RFC 6749. No entanto, o fluxo já foi obsoleto.

A concessão de credenciais de senha do proprietário do recurso NÃO DEVE ser usada.

Conforme concebido originalmente, a concessão de credenciais de senha do proprietário do recurso OAuth 2.0 fornece autorização no nível do usuário. O usuário fornece seu nome de usuário e senha a um cliente confiável. O cliente confiável troca as credenciais por um token de acesso.

O Vinyl fornece suporte parcial para o fluxo de credenciais de senha do proprietário do recurso OAuth 2.0. O Vinyl não solicita suas credenciais ao usuário. Em vez disso, um único conjunto de credenciais é usado para autorizar todos os usuários. Dessa forma, é funcionalmente equivalente a uma conta de serviço.

Configuração¶

Parâmetros¶

Os parâmetros a seguir habilitam e configuram o fluxo de credenciais de senha do proprietário do recurso OAuth 2.0:

Fluxo de Declaração do Portador SAML 2.0¶

O fluxo de asserção de portador SAML 2.0 do OAuth 2.0 fornece autenticação em nível de usuário. Neste fluxo, as asserções SAML são trocadas por tokens de acesso OAuth. O fluxo de declaração do portador OAuth 2.0 SAML 2.0 é padronizado em RFC 7522.

Configuração¶

Parâmetros¶

Os parâmetros a seguir habilitam e configuram o fluxo de asserção do portador SAML 2.0 do OAuth 2.0:

Ao usar o fluxo de asserção do portador SAML 2.0, as asserções SAML podem ser originadas de duas maneiras:

1. Um provedor de identidade (IdP) externo emitirá uma declaração SAML durante o processo de logon único (SSO) SAML. Consulte o tipo de provedor SAML Para maiores informações.
2. O Vinyl pode gerar e assinar as declarações SAML sob demanda. Nesse caso, o Vinyl atua como o IdP.

Cada fonte requer configuração adicional.

Obtendo Afirmações SAML por Meio de um IdP de Externo¶

Gerando Asserções SAML Sob Demanda¶

Configuração¶

O provedor de segurança OAuth expõe um único endpoint, escutando respostas de autorização no endereço:

• https://example.com/Vinyl/signin-{Provider}

Onde https://example.com/Vinyl é o URL absoluto para o diretório raiz do aplicativo Vinyl e "{Provider}" é o nome codificado em URL e que diferencia maiúsculas de minúsculas do provedor de segurança.

O padrão OAuth define este URI como o "Redirection Endpoint": https://tools.ietf.org/html/rfc6749#section-3.1.2

A maioria dos aplicativos de terceiros precisará ser configurada com o endpoint de redirecionamento antes de autorizar qualquer solicitação.

Parâmetros¶

O provedor de segurança OAuth define os seguintes parâmetros:

Suporte a Protocolo¶

Ao construir uma solicitação de autorização, o Vinyl incluirá o ID do cliente (client_id), o segredo do cliente (client_secret) e os escopos (escopo). Além disso, o Vinyl anexará automaticamente os seguintes parâmetros padrão:

• redirec_uri - Vinyl constrói o parâmetro redireccionamento_uri a partir do URL actual. Assume o formato https:example.com/Vinyl/signin-OAuth, onde OAuth é o nome do provedor de segurança OAuth.
• state - O parâmetro state é uma coleção criptografada de pares nome/valor. Inclui um token Cross-Site Request Forgery (CSRF) conforme https://tools.ietf.org/html/rfc6749#section-10.12

Usando OAuth para Autenticação Externa¶

Conforme observado acima, OAuth é um protocolo de autorização, não um protocolo de autenticação. No entanto, algumas implementações de fornecedores estendem o protocolo OAuth para incluir autenticação. Normalmente, isso é feito publicando um endpoint que identifica o usuário. Vinyl refere-se a um endpoint como UserInfoEndpoint.

O Vinyl pode ser configurado para consultar UserInfoEndpoint para recuperar a identidade do usuário. Isso permite que um provedor de segurança OAuth seja usado para autenticação externa. Observe, entretanto, que o endpoint deve atender aos seguintes requisitos:

• O endpoint deve ser acessível pelo Vinyl.
• O endpoint deve responder a uma solicitação HTTP GET que não inclua um corpo de solicitação.
• O endpoint deve respeitar a autenticação do cliente OAuth Basic (conforme descrito acima).
• A resposta HTTP deve ter um código de status 200.
• A resposta HTTP deve incluir um corpo com um Content-Type de application/json.
• O documento JSON deve incluir uma propriedade de nível superior que identifique o usuário.

Após adquirir o token de acesso, o Vinyl fará uma solicitação autenticada do cliente ao UserInfoEndpoint. O Vinyl analisará o corpo da resposta como JSON, tratando as propriedades de nível superior como declarações.

Por exemplo, dado o seguinte exemplo de resposta:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "user_name": "arthur.dent",
    "name": "Arthur Dent",
    "email": "arthurdent@example.com"
}

Os seguintes tipos de reivindicação estarão disponíveis:

• nome de usuário
• nome
• email

Além de especificar o UserInfoEndpoint, o desenvolvedor deve mapear a declaração que identifica o usuário – neste caso, a declaração user_name – para o tipo de uso da declaração Name.