Observação:

Acessar Recursos Protegidos no ORDS usando um Token JWT Emitido pelos Domínios do IAM do OCI

Introdução

O Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) usa domínios de identidade para fornecer recursos de gerenciamento de identidade e acesso, como autenticação, Sign-On Único (SSO) e gerenciamento do ciclo de vida de identidade para OCI, bem como para aplicativos Oracle e não Oracle, seja SaaS, hospedado na nuvem ou local.

O Oracle REST Data Services (ORDS) conecta HTTPS e seu Oracle Database. Um aplicativo Java de camada intermediária, o ORDS fornece uma API REST de Gerenciamento de Banco de Dados, SQL Developer Web, um Gateway PL/SQL, SODA (Simple Oracle Document Access) para REST e a capacidade de publicar Web Services RESTful para interagir com os dados e procedimentos armazenados no Oracle Database.

O ORDS versão 23.3 introduz suporte para JWT (JSON Web Token). Esses tokens de portador permitem que os desenvolvedores do ORDS deleguem autenticação e autorização a qualquer Provedor de Identidades compatível com OAuth2 (IdP) para emitir um token de acesso JWT que o ORDS pode validar para fornecer acesso aos recursos protegidos pelo ORDS.

Neste tutorial, demonstraremos como acessar recursos protegidos no ORDS usando um token JWT emitido pelos domínios do OCI IAM. Para esta demonstração, usaremos um Oracle Autonomous Database na OCI, que vem com um aplicativo ORDS pré-configurado e totalmente gerenciado.

A imagem a seguir mostra a representação de alto nível da arquitetura da solução.

Diagrama de Arquitetura

Objetivos

Pré-requisitos

Observação: O domínio do OCI IAM e o token JWT emitido por ele atendem a todos os requisitos acima.

Tarefa 1: Configurar o ORDS para um Esquema de Banco de Dados, Definir Pontos Finais de API e Configurar o Controle de Acesso

  1. Faça log-in na Console do OCI, navegue até o Oracle Database e clique em Autonomous Database.

  2. Clique em Instância Provisionada do Autonomous Database, Database Actions e, em seguida, clique em SQL.

  3. Execute a consulta a seguir para garantir que você tenha o ORDS versão 23.3 ou mais recente, que suporta JWTs.

    SELECT * FROM ORDS_METADATA.ORDS_VERSION;

    Versão do ORDS

  4. Execute a consulta a seguir para criar um usuário (ordstest) e designar os privilégios necessários.

    CREATE USER ordstest IDENTIFIED BY "<Password>";
GRANT CONNECT, RESOURCE TO ordstest;
ALTER USER ordstest DEFAULT ROLE CONNECT, RESOURCE;

  5. Execute a consulta a seguir para ativar o ORDS para o esquema a fim de permitir a funcionalidade da API REST.

    BEGIN
 ORDS_ADMIN.ENABLE_SCHEMA(
     p_enabled => TRUE,
     p_schema => 'ordstest',
     p_url_mapping_type => 'BASE_PATH',
     p_url_mapping_pattern => 'ordstest',
     p_auto_rest_auth=> FALSE
 );
commit;
END;
/

  6. Execute a consulta a seguir para criar uma tabela chamada emp no esquema ordstest e inserir dados de amostra.

    CREATE TABLE ordstest.emp (
EMPNO NUMBER(4,0),
ENAME VARCHAR2(10 BYTE),
JOB VARCHAR2(9 BYTE),
MGR NUMBER(4,0),
HIREDATE DATE,
SAL NUMBER(7,2),
COMM NUMBER(7,2),
DEPTNO NUMBER(2,0),
CONSTRAINT PK_EMP PRIMARY KEY (EMPNO)
);

    Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7369,'SMITH','CLERK',7902,to_date('17-DEC-80','DD-MON-RR'),800,null,20);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7499,'ALLEN','SALESMAN',7698,to_date('20-FEB-81','DD-MON-RR'),1600,300,30);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7521,'WARD','SALESMAN',7698,to_date('22-FEB-81','DD-MON-RR'),1250,500,30);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7566,'JONES','MANAGER',7839,to_date('02-APR-81','DD-MON-RR'),2975,null,20);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7654,'MARTIN','SALESMAN',7698,to_date('28-SEP-81','DD-MON-RR'),1250,1400,30);

  7. Execute a consulta a seguir para definir um módulo ORDS (demo) que conterá os pontos finais da API.

    BEGIN
  ORDS_ADMIN.DEFINE_MODULE(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_base_path => '/demo/',
     p_items_per_page=> 1000,
     p_status => 'PUBLISHED',
     p_comments=> ''
 );
COMMIT;
END;
/

  8. Execute a consulta a seguir para definir um modelo emp que seja mapeado para um recurso REST específico.

    BEGIN
 ORDS_ADMIN.DEFINE_TEMPLATE(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_pattern => 'emp',
     p_priority => 0,
     p_etag_type => 'HASH',
     p_comments => ''
 );
COMMIT;
END;
/

  9. Execute a consulta a seguir para criar um handler de solicitação GET para emp, que executa uma consulta SQL simples que retorna dados da tabela emp.

    BEGIN
 ORDS_ADMIN.DEFINE_HANDLER(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_pattern => 'emp',
     p_method => 'GET',
     p_source_type => ords.source_type_collection_feed,
     p_source => 'select * from emp',
     p_items_per_page => 25,
     p_comments => ''
 );
COMMIT;
END;
/

    A tabela emp pode ser exibida sem autenticação anexando /ordstest/demo/emp ao URL de acesso público do ORDS dos Oracle Autonomous Databases, que está disponível em Configuração da Ferramenta. Postman é usado neste tutorial.

    URL DO ORDS

    Acesso sem autorização

  10. Execute a consulta a seguir para definir um privilégio (privilegetest) para proteger o módulo demo.

    DECLARE
L_PRIV_ROLES owa.vc_arr;
L_PRIV_PATTERNS owa.vc_arr;
L_PRIV_MODULES owa.vc_arr;
BEGIN
L_PRIV_MODULES( 1 ) := 'demo';
ORDS_ADMIN.DEFINE_PRIVILEGE(
  P_Schema=> 'ordstest',
  P_PRIVILEGE_NAME => 'privilegetest',
  P_ROLES => L_PRIV_ROLES,
  P_PATTERNS =>  L_PRIV_PATTERNS,
  P_MODULES => L_PRIV_MODULES,
  P_LABEL => 'privilegetest',
  P_DESCRIPTION => 'Demonstrate controlling access with priviliges',
  P_COMMENTS=> ''
  );
COMMIT;
END;
/

    Como o módulo demo é protegido pelo privilégio privilegetest, ele não pode ser acessado sem a autorização adequada. Para ativar o acesso, você precisa criar um perfil JWT para o esquema ordstest. Isso permite que o ORDS valide tokens do portador do JWT e conceda acesso a recursos protegidos, como o módulo de demonstração.

Tarefa 2: Criar um Perfil ORDS JWT

Um perfil JWT pode ser criado em um esquema ativado para REST usando o procedimento OAUTH.CREATE_JWT_PROFILE. No entanto, somente um perfil JWT pode ser definido por esquema. Para atualizar um perfil JWT existente, ele deve primeiro ser excluído antes de criar um novo.

BEGIN
  OAUTH_ADMIN.DELETE_JWT_PROFILE(p_schema=>'ordstest');
  OAUTH_ADMIN.CREATE_JWT_PROFILE(
  p_schema => 'ordstest',
  p_issuer => 'https://idcs-123456789abcdefghijklmnopqrstuvw.identity.oraclecloud.com',
  p_audience => 'ords/ordstest/',
  p_jwk_url =>'https://idcs-123456789abcdefghijklmnopqrstuvw.identity.oraclecloud.com:443/admin/v1/SigningCert/jwk'
 );
COMMIT;
END;
/

Este perfil JWT especifica o emissor, o público e o URL JWK.

O Issuer e o JWK URI para um domínio do OCI IAM podem ser obtidos enviando uma solicitação GET para o URL de domínio do OCI IAM, anexando /.well-known/openid-configuration, conforme mostrado na imagem a seguir.

Metadados do Domínio do IAM

Para verificar a configuração do perfil JWT, faça log-in como o usuário ordstest e execute a consulta SQL a seguir.

SELECT * FROM ORDS_METADATA.USER_ORDS_JWT_PROFILE;

Esta consulta recupera os detalhes do perfil JWT, garantindo que o emissor, o público e o URL JWK estejam configurados corretamente.

Perfil do ORDS JWT

Depois que o perfil JWT é configurado, os usuários finais podem acessar recursos protegidos pelo ORDS apresentando tokens JWT emitidos por um IdP compatível com OAuth 2.0, como o domínio do OCI IAM especificado no perfil JWT. Quando um token ao portador do JWT é validado com sucesso, o ORDS aceita o seguinte:

Tarefa 3: Ativar o Acesso do ORDS ao Certificado de Assinatura do Domínio do IAM do OCI sem Autenticação

  1. Vá para a Console do OCI, navegue até Identidade e Segurança, Identidade e clique em Domínios.

  2. Clique no nome do domínio de identidades no qual deseja trabalhar. Talvez você precise alterar o compartimento para localizar o domínio desejado. Clique em Definições e Definições de domínio.

  3. Na seção Acessar certificado de assinatura, selecione Configurar acesso do cliente e clique em Salvar Alterações. Isso permite que o ORDS acesse a certificação de assinatura do domínio de identidades sem autenticação.

    Certificado de Assinatura

Tarefa 4: Configurar Servidor de Recursos e Cliente, Escopos JWT e Privilégios ORDS

Configure o IdP para emitir o JWT com um escopo que corresponda ao privilégio ORDS necessário. Se um recurso no ORDS for protegido por um privilégio, esse nome de privilégio deverá ser definido como um escopo. Esse escopo permite que o aplicativo solicite acesso em nome do usuário. O JWT emitido deve, então, incluir o escopo como uma reivindicação. Como usaremos os serviços OAuth2 do OCI IAM para impor autorização, precisamos configurar alguns servidores de recursos e clientes.

Tarefa 4.1: Criar um Aplicativo Confidencial do Tipo Servidor de Recursos com o Público e os Escopos Desejados

  1. Vá para o domínio de identidades no qual está trabalhando e clique em Aplicativos Integrados.

  2. Selecione Adicionar Aplicativo, Aplicativo Confidencial e clique em Iniciar workflow.

  3. Informe um Nome para o aplicativo (por exemplo, ORDS-SERVER) e clique em Próximo.

  4. Na seção Configuração do servidor de recursos, selecione Configurar agora este aplicativo como servidor de recursos.

  5. Configure o servidor de recursos com público-alvo principal correspondente ao perfil JWT e escopo correspondente ao privilégio ORDS.

    Configuração do Servidor de Recursos

  6. Clique em Próximo e em Concluir.

  7. Na página de visão geral do aplicativo, selecione Ativar e confirme que deseja ativar o aplicativo. O aplicativo confidencial será ativado.

Tarefa 4.2: Criar um Aplicativo Confidencial do Tipo Cliente que é Atribuído aos Escopos Desejados

  1. Vá para o domínio de identidades no qual está trabalhando e clique em Aplicativos Integrados.

  2. Selecione Adicionar Aplicativo, Aplicativo Confidencial e clique em Iniciar workflow.

  3. Informe um Nome para o aplicativo (por exemplo, ORDS-CLIENT) e clique em Próximo.

  4. Na seção Configuração do cliente, selecione Configurar este aplicativo como cliente agora.

  5. Na seção Autorização, selecione Credenciais do cliente.

    Observação: Neste tutorial, estamos usando Credenciais do Cliente como Tipos de Concessão. Você pode selecionar um tipo de concessão diferente com base em seus requisitos, como Fluxo de Código de Autorização para um cliente voltado para o usuário.

  6. Em Tipo de cliente, selecione Confidencial.

  7. Na seção Política de emissão de token, selecione Específico como Recursos autorizados.

  8. Clique em Adicionar Recursos e, em Recursos, selecione Adicionar Escopo. Selecione os escopos desejados para o servidor de recursos criado na Tarefa 4.1. Por exemplo, privilegetest.

    Configuração do Cliente

  9. Clique em Próximo e em Concluir.

  10. Na página Visão Geral do Aplicativo, selecione Ativar e confirme que deseja ativar o aplicativo. O aplicativo confidencial será ativado.

  11. Copie o ID do Cliente e o Segredo do cliente desse aplicativo cliente. Essas credenciais serão necessárias para autenticação.

Tarefa 5: Enviar Solicitações ao ORDS Usando um Token do Portador do JWT

Envie uma pós-solicitação (usando o Postman) para o ponto final do token de domínio do OCI IAM com Tipo de Concessão como client_credentials e Escopo como privilegetest, conforme mostrado na imagem a seguir.

Ponto Final do Token

Observação: O público-alvo e o escopo devem ser incluídos no campo de escopo ao solicitar o token ao portador do domínio do OCI IAM.

Credenciais do Cliente

Valide o token JWT para escopos, emissor e público-alvo.

Detalhes do Token JWT

Agora, o recurso ORDS protegido (módulo de demonstração) no esquema ordstest pode ser acessado fornecendo um token ao portador JWT válido com a solicitação get, conforme mostrado na imagem a seguir.

Acesso com JWT

O ORDS valida o token recuperando a chave pública do URL do JWK e verificando a assinatura do token. Se a assinatura for válida, o ORDS verificará se as reivindicações iss (emissor) e aud (público) correspondem às definidas no perfil JWT. Ele também verifica se a reivindicação do escopo corresponde ao privilégio de proteção do recurso. Se todas as condições forem atendidas, o usuário receberá acesso ao recurso protegido.

Confirmações

Mais Recursos de Aprendizagem

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal Oracle Learning YouTube. Além disso, visite education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.