Provedor de segurança OAuth no Jitterbit App Builder
Introdução
O provedor de segurança OAuth habilita suporte para OAuth 2.0. O provedor de segurança é responsável por autorizar requisições de serviços web. Os seguintes tipos de fonte de dados suportam OAuth:
-
REST
-
OData
-
RDBMS (limitado aos provedores CData suportados)
Além disso, é possível configurar um provedor de segurança OAuth como um provedor de autenticação externa. Veja abaixo para mais informações.
Concessões OAuth 2.0
O provedor de segurança OAuth suporta as seguintes concessões OAuth 2.0:
-
Authorization Code RFC 6749.
-
Client Credentials RFC 6749.
-
Resource Owner Password Credentials RFC 6749.
-
SAML 2.0 Bearer Assertion RFC 7522.
-
JWT Bearer Token RFC 7523.
Authorization code
A concessão Authorization Code do OAuth 2.0 fornece autorização delegada em nível de usuário. Essa concessão é definida em RFC 6749.
No fluxo Authorization Code, o App Builder redireciona o agente do usuário (navegador) para o servidor de autorização. Após o usuário fazer login com êxito e aprovar a requisição de autorização, o servidor de autorização redireciona o agente do usuário de volta para o App Builder. O redirecionamento inclui um código de autorização. O App Builder faz uma requisição de canal traseiro ao servidor de autorização, trocando o código de autorização por um token de acesso. O token de acesso pode ser usado para autorizar requisições a serviços web.
Por si só, OAuth fornece autorização, não autenticação. Portanto, provedores de segurança OAuth não são tipicamente usados como provedores de autenticação externa: são usados para autorizar requisições a um provedor de dados compatível, como OData ou REST. Porém, se o provedor de segurança OAuth publica um endpoint que fornece a identidade do usuário, o provedor de segurança OAuth pode ser usado como um provedor de autenticação externa. Veja o User Info Endpoint para mais detalhes.
Client credentials
A concessão Client Credentials do OAuth 2.0 fornece autenticação em nível de cliente, semelhante a uma conta de serviço. Neste fluxo, as credenciais do cliente OAuth são trocadas por um token de acesso OAuth. A concessão Client Credentials é definida em RFC 6749.
Resource owner password credentials
A concessão Resource Owner Password Credentials do OAuth 2.0 é definida em RFC 6749. Porém, a concessão foi descontinuada.
Importante
A concessão resource owner password credentials NÃO DEVE ser usada.
Conforme originalmente concebido, a concessão Resource Owner Password Credentials do OAuth 2.0 fornece autorização em nível de 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 App Builder fornece suporte parcial para a concessão Resource Owner Password Credentials do OAuth 2.0. O App Builder não solicita ao usuário suas credenciais. Em vez disso, uma única credencial é usada para autorizar todos os usuários. Dessa forma, a concessão é funcionalmente equivalente a uma conta de serviço.
SAML 2.0 bearer assertion
A concessão SAML 2.0 Bearer Assertion do OAuth 2.0 fornece autenticação de fonte de dados em nível de usuário. Neste fluxo, asserções SAML são trocadas por tokens de acesso OAuth. A concessão SAML 2.0 Bearer Assertion do OAuth 2.0 é definida em RFC 7522.
JWT bearer token
A concessão JWT Bearer Token do OAuth 2.0 fornece autenticação de fonte de dados em nível de usuário. Neste fluxo, JSON Web Tokens (JWTs) são trocados por tokens de acesso OAuth. A concessão JWT Bearer Token do OAuth 2.0 é definida em RFC 7523.
Configuração
A configuração varia conforme a concessão OAuth. No mínimo, OAuth requer:
-
Identificador do cliente (
client_id) e segredo do cliente (client secret). -
Ponto de extremidade de token.
Concessões OAuth individuais exigirão configuração adicional conforme indicado abaixo.
Autenticação
As propriedades de autenticação determinam a concessão OAuth e os esquemas de autenticação.
-
Tipo de Autenticação: OAuth
-
Concessão OAuth: Selecione uma concessão OAuth compatível.
-
Autenticação do Cliente OAuth: Determina o esquema de autenticação do cliente OAuth 2.0 RFC 6749 Seção 2.3. As opções incluem:
-
Básico: Indica que o esquema de Senha do Cliente será usado. As credenciais serão fornecidas usando autenticação HTTP Basic. (
client_secret_basic.) -
JWT do Segredo do Cliente: O cliente é autenticado usando um JSON Web Token (JWT) assinado com o segredo do cliente (
client_secret_jwt). (Consulte Tipos de autenticação do cliente JWT.) -
Nenhum: Indica que o cliente não deve ser autenticado. (
none.) -
Post: Indica que o esquema de Senha do Cliente será usado. As credenciais serão fornecidas como parâmetros de formulário no corpo da solicitação. (
client_secret_post.) -
JWT de Chave Privada: O cliente é autenticado usando um JSON Web Token (JWT) assinado com uma chave privada (
private_key_jwt). (Consulte Tipos de autenticação do cliente JWT.)
-
-
Autenticação de Recurso OAuth: Determina o esquema de autenticação da solicitação de recurso. As opções incluem:
-
Bearer: Esquema de autenticação Bearer. Padrão.
-
Formulário: Acrescente o token de acesso ao corpo codificado em URL de formulário.
-
Consulta: Acrescente o token de acesso à string de consulta.
-
-
Proprietário do Token: Determina se os tokens são emitidos para usuários individuais ou para o sistema cliente. As opções incluem:
-
Usuário: Os tokens são emitidos para usuários individuais.
-
Cliente: Os tokens são emitidos para o sistema cliente.
-
-
Excluir Token ao Sair: Quando ativado, o App Builder exclui o token armazenado quando o usuário faz logout. Padrão: Desativado.
Tipos de autenticação do cliente JWT
Os tipos de autenticação do cliente JWT suportam as seguintes opções de configuração:
-
Asserção:
-
Emissor: Sem padrão. Geralmente usa um identificador de aplicativo ou o ID do cliente. Consulte a documentação do servidor de autorização.
-
Público: Assume como padrão o ponto de extremidade de token (conforme definido no painel Pontos de Extremidade) de acordo com o padrão.
-
Assunto: Assume como padrão o ID do cliente (conforme especificado no painel Credenciais) de acordo com o padrão.
-
-
Credenciais:
-
Tipo:
ClientID do Cliente é obrigatório. Segredo do Cliente é ignorado e pode ser omitido.
-
-
Certificados:
-
Uso:
SigningUm certificado é usado apenas pelo tipo de autenticação do cliente JWT de Chave Privada. O JWT do Segredo do Cliente usa o segredo do cliente como chave.
-
-
Propriedades:
-
Parâmetro:
JwtClaimSet -
Parâmetro:
SigningAlgorithm
-
Token
As seguintes concessões geram tokens que são trocados por tokens de acesso OAuth:
-
Asserção do Portador SAML 2.0.
-
Token do Portador JWT.
Asserção do portador SAML 2.0
-
Emissor: O emissor da asserção SAML.
-
Público: A restrição de público da asserção SAML. Embora a especificação SAML indique que o público é uma URI, muitas implementações não a respeitam. Consequentemente, o App Builder não exige que o público seja uma URI.
-
Destinatário: O URI do destinatário da asserção SAML (por exemplo,
http://example.com/service).
Token do portador JWT
-
Emissor: Afirmação do emissor JWT (https://tools.ietf.org/html/rfc7523#section-3). Assume como padrão o identificador do cliente (
client_id). -
Assunto: Afirmação do assunto JWT (https://tools.ietf.org/html/rfc7523#section-3).
-
Se o Proprietário do Token é Usuário, usa por padrão a identidade do usuário atual.
-
Se o Proprietário do Token é Cliente, o Assunto é obrigatório.
-
Público: Declaração de público do JWT (https://tools.ietf.org/html/rfc7523#section-3). Usa por padrão o Endpoint de Token.
Endpoints
| Tipo | Concessões | Descrição |
|---|---|---|
| Endpoint de Autorização | Código de Autorização | URL do endpoint de autorização OAuth 2.0. RFC 6749 |
| Endpoint de Token | Todos | URL do endpoint de token OAuth 2.0. RFC 6749 |
| Endpoint de Informações do Usuário | Código de Autorização | Endpoint que fornece a identidade do usuário. Obrigatório ao tratar OAuth como um provedor de autenticação externo. Não faz parte do padrão OAuth. O endpoint deve retornar uma resposta JSON que inclua a identidade do usuário. |
Credenciais
| Tipo | Concessões | Descrição |
|---|---|---|
| Cliente | Todos | Identificador do cliente OAuth 2.0 (client_id) e segredo (client_secret). RFC 6749 |
| Proprietário do Recurso | Credenciais de Senha do Proprietário do Recurso | Nome de usuário (username) e senha (password) do proprietário do recurso OAuth 2.0. RFC 6749 |
Certificados
| Tipo | Concessões | Descrição |
|---|---|---|
| Assinatura | Declaração de Portador SAML 2.0 | A concessão Declaração de Portador SAML 2.0 requer um certificado X.509 com chave privada em um contêiner PKCS#12 (.pfx) protegido por senha. |
| Token de Portador JWT | A concessão Token de Portador JWT requer uma chave privada RSA PKCS#1 codificada em PEM (RSA PRIVATE KEY). |
Propriedades
O provedor de segurança OAuth suporta os seguintes parâmetros adicionais:
| Parâmetro | Padrão | |
|---|---|---|
BearerSchemeIdentifier |
Bearer |
Esquema de Autorização ao usar a autenticação de recurso Bearer. |
ExpiresIn |
Expiração do token de acesso em segundos. Pode ser usada se o endpoint de token não fornecer uma expiração e o servidor de recursos não retornar uma resposta 401 Unauthorized quando o token de acesso tiver expirado. |
|
IgnoreTlsErrors |
False |
Indica se o App Builder deve ignorar erros de TLS ao fazer solicitações de back-channel ao endpoint de token. Deve-se usar apenas para desenvolvimento e testes. |
Scopes |
Lista de escopos de token de acesso OAuth 2.0 delimitada por espaço em branco. RFC 6749 | |
SingleUseAccessToken |
False |
Indica se o token de acesso pode ser usado apenas uma vez. |
TokenEndpointParameters |
Parâmetros passados ao endpoint de token OAuth. Por padrão, o App Builder gera os parâmetros apropriados com base no fluxo OAuth. Use essa configuração apenas para APIs OAuth não conformes ou não suportadas. Os parâmetros devem ser especificados em formato de URL codificada (application/x-www-form-urlencoded). Se a lista de parâmetros começa com um E comercial (&), os parâmetros serão mesclados aos parâmetros gerados. Se um parâmetro tem o mesmo nome que um parâmetro gerado, o parâmetro gerado será sobrescrito. Se um parâmetro fornecido não tem um valor, por exemplo &grant_type&username=user&password=password, o parâmetro gerado será removido. Caso contrário, o parâmetro fornecido é anexado aos parâmetros gerados. A lista de parâmetros suporta interpolação de string. Expressões podem referenciar parâmetros dinâmicos, por exemplo username={{ client_id }}&password={{ client_secret }}. Isso é útil ao integrar com APIs de terceiros que não usam nomes de parâmetro padrão. |
|
RefreshRequiresScopes |
False |
Indica se os escopos (scope) devem ser incluídos no corpo da solicitação enviada ao endpoint de token ao atualizar o token de acesso. |
AuthorizationEndpointParameters |
(Desde o App Builder 4.57.) Permite que administradores injetem parâmetros de URL ao redirecionar para o servidor de autorização (por exemplo, &access_type=offline). Esse parâmetro segue as mesmas regras que a propriedade TokenEndpointParameters. |
Código de autorização
As seguintes propriedades adicionais se aplicam à concessão de Código de Autorização.
| Parâmetro | Padrão | |
|---|---|---|
BackchannelAuthorization |
False |
Indica se um código de autorização pode ser obtido por meio de uma solicitação de backchannel (servidor para servidor). Esta é uma extensão não padrão da concessão de Código de Autorização. |
Asserção portadora SAML 2.0
As seguintes propriedades adicionais se aplicam à concessão de Asserção Portadora SAML 2.0.
| Parâmetro | |
|---|---|
SamlSingleSignOnProvider |
Nome de um provedor de segurança SAML do App Builder. Este parâmetro se aplica apenas à concessão de Asserção Portadora SAML 2.0. |
Token portador JWT
As seguintes propriedades adicionais se aplicam à concessão de Token Portador JWT.
| Parâmetro | Padrão | |
|---|---|---|
JwtClaimSet |
{ "scope": "{{ scope }}" } |
Os servidores de autorização podem exigir declarações personalizadas. Por exemplo, o Google exige uma declaração scope correspondente ao parâmetro OAuth scope. O parâmetro JwtClaimSet permite que administradores forneçam declarações adicionais. O valor assume a forma de um modelo JSON. Os seguintes valores podem ser substituídos no modelo:
|
SigningAlgorithm |
RS256 |
Parâmetro de algoritmo JWT conforme definido em RFC 7518. O único algoritmo suportado é RS256. |
Rest
As propriedades adicionais a seguir se aplicam quando o provedor de segurança OAuth é usado para autenticar fontes de dados REST. Estas são ignoradas para endpoints OAuth e outros tipos de fontes de dados, incluindo OData e RDBMS.
Os cabeçalhos de solicitação devem ser separados por um retorno de carro (aparecer em sua própria linha).
| Parâmetro | Padrão | Exemplo | |
|---|---|---|---|
RequestHeaders |
X-Custom-Header: Value X-Another-Header: Value |
Cabeçalhos HTTP personalizados anexados às solicitações de endpoint REST. Os cabeçalhos devem ser formatados de acordo com RFC 7230. Dobra de linha não é suportada. |
Suporte a protocolo
Tokens de atualização
Se a solicitação do token de acesso incluir um token de atualização, o App Builder tentará automaticamente usar o token de atualização para adquirir um novo token de acesso após receber uma resposta 401 Unauthorized.
Código de autorização
Solicitação de autorização
Ao construir uma solicitação de autorização, o App Builder incluirá o identificador do cliente (client_id), o segredo do cliente (client_secret) e os escopos (scope). Além disso, o App Builder anexará automaticamente os seguintes parâmetros padrão:
-
redirect_uri: O App Builder constrói o parâmetroredirect_uria partir da URL atual. Assume a formahttps://example.com/Vinyl/signin-OAuth, onde OAuth é o esquema do provedor de segurança OAuth. -
state: O parâmetro state é uma carga útil criptografada e opaca. Inclui um token de Proteção contra Solicitação entre Sites (CSRF) conforme RFC 6749.
Endpoint de redirecionamento
Conforme definido em RFC 6749, a concessão do código de autorização expõe um endpoint de redirecionamento. Este endpoint escuta respostas de autorização no endereço:
https://example.com/Vinyl/signin-OAuth
Onde https://example.com/Vinyl é a URL absoluta para o diretório raiz da aplicação do App Builder e OAuth é o esquema sensível a maiúsculas/minúsculas do provedor de segurança. Todos os caracteres especiais precisam ser codificados em URL.
A maioria das aplicações de terceiros precisará ser configurada com o endpoint de redirecionamento antes de autorizar qualquer solicitação.
Proxy reverso
Desde o App Builder 4.59, o URI de redirecionamento OAuth omite o número da porta quando a porta padrão é usada. Isso garante compatibilidade com provedores OAuth quando o App Builder é hospedado atrás de um proxy reverso.
Para contornar esse problema com o App Builder 4.58 ou anterior, configure um provedor de segurança de Reescrita de URL para remover a porta explícita do URI de redirecionamento:
- Navegue até IDE > Provedores de Segurança.
- No painel Provedores de Segurança, expanda o menu Mais e clique em Importar Provedor.
-
Cole a configuração a seguir, substituindo
example.compelo nome de host do App Builder:{ "name": "URL Rewrite", "type": "rewrite_url", "settings": { "MatchUrl": "https://example.com:443", "RewriteUrl": "https://example.com" } } -
Clique no botão Importar e, em seguida, clique em Prosseguir para confirmar.
- Retorne à página Segurança. No painel Provedores de Segurança, expanda o menu Mais e clique em Pipeline de Solicitação.
- Localize o provedor de Reescrita de URL importado. Defina sua Prioridade (por exemplo,
10) e marque a opção Ativado.
Para verificar a correção, retorne à página Segurança, expanda o menu Mais do painel Configuração e clique em Inspecionar Solicitação. A Porta deve estar vazia e Padrão deve estar marcado.
Usando OAuth para autenticação externa
Conforme observado acima, OAuth é um protocolo de autorização, não de autenticação. Porém, algumas implementações de fornecedores estendem o protocolo OAuth para incluir autenticação. Normalmente, isso é feito publicando um endpoint que identifica o usuário. O App Builder refere-se a tal endpoint como o User Info Endpoint.
O App Builder pode ser configurado para consultar o User Info Endpoint a fim de recuperar a identidade do usuário. Isso permite que um provedor de segurança OAuth seja usado para autenticação externa. Note, porém, que o endpoint deve atender aos seguintes requisitos:
-
O endpoint deve ser acessível pelo App Builder.
-
O endpoint deve responder a uma solicitação HTTP
GETque não inclui um corpo de solicitação. -
O endpoint deve honrar autenticação 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-Typedeapplication/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 App Builder fará uma solicitação autenticada por cliente para o User Info Endpoint. O App Builder analisará o corpo da resposta como JSON, tratando as propriedades de nível superior como claims.
Por exemplo, dada a seguinte resposta de amostra:
HTTP/1.1 200 OK
Content-Type: application/json
{
"user_name": "arthur.dent",
"name": "Arthur Dent",
"email": "arthurdent@example.com"
}
Os seguintes tipos de claim estarão disponíveis:
-
user_name -
name -
email
Além de especificar o User Info Endpoint, o desenvolvedor deve mapear o claim que identifica o usuário–neste caso, o claim user_name–para o tipo de uso de claim Name.
Asserção Bearer SAML 2.0
Ao usar o fluxo SAML 2.0 Bearer Assertion, asserções SAML podem ser originadas de uma de duas maneiras:
-
O App Builder gera e assina as asserções SAML sob demanda. Neste caso, o App Builder atua como o IdP.
-
(Descontinuado) um provedor de identidade (IdP) de terceiros emite uma asserção SAML durante o processo de logon único SAML (SSO). consulte o tipo de provedor SAML para mais informações.
Cada origem requer configuração adicional.
Gerar asserções SAML sob demanda
Para gerar uma asserção SAML sob demanda, configure as propriedades Token conforme descrito acima. Além disso, a concessão SAML 2.0 Bearer Assertion requer um certificado de Signing com uma chave privada.
Originar asserções SAML de um IdP
Para originar asserções SAML de um IdP de terceiros, defina o parâmetro SamlSingleSignOnProvider.
Limitações
- Tipos de autenticação cliente JWT não podem ser usados com a concessão JWT Bearer Token. Ambos usam um JWT, mas cada token tem requisitos diferentes. O provedor de segurança OAuth suporta a configuração de apenas um único token JWT.