Saiba Mais sobre Autenticação entre Aplicativos Node.js e o Oracle Identity Cloud Service

Saiba Mais Sobre Fluxos de Autenticação de Três Etapas

O Oracle Identity Cloud Service suporta o fluxo de autenticação de três etapas para o SDK Node.js. Neste fluxo, os usuários interagem diretamente com o Oracle Identity Cloud Service. Depois que um usuário acessa, o Oracle Identity Cloud Service emite um código de autorização que o SDK troca por um token de acesso do usuário. O aplicativo Web Node.js usa esse token de acesso para conceder aos usuários acesso aos recursos protegidos no aplicativo. O fluxo de três etapas usa o tipo de concessão de código de autorização.

Para maior segurança, a Oracle recomenda que você use o fluxo de três etapas para integrar seus aplicativos Web Node.js com o Oracle Identity Cloud Service para autenticação. Usando o tipo de concessão de código de autorização, você também pode acessar outros aplicativos protegidos pelo Oracle Identity Cloud Service sem precisar se autenticar novamente.

Saiba Mais Sobre os Principais Casos de Uso para Usar um SDK com um Aplicativo Node.js

O aplicativo Web Node.js implementa dois casos de uso: um para autenticar usuários e o outro para acessar informações detalhadas sobre o usuário conectado.

Os diagramas de fluxo de dados a seguir ilustram o fluxo de eventos, chamadas e respostas entre o navegador da Web, o aplicativo da Web e o Oracle Identity Cloud Service para cada caso de uso.

Caso de Uso No 1: Autenticar um Usuário

Veja a seguir a descrição da autenticação -user.png

Descrição da ilustração autenticate-user.png

O fluxo de dados acontece desta forma:

O usuário solicita um recurso protegido.
O módulo de autenticação usa o SDK para gerar um URL de código de autorização de solicitação para o Oracle Identity Cloud Service e enviar esse URL como resposta de redirecionamento para o Web browser.
O navegador da Web chama o URL.
A página Acessar do Oracle Identity Cloud Service é exibida.
O usuário envia suas credenciais de acesso ao Oracle Identity Cloud Service.
Depois que o usuário acessa, o Oracle Identity Cloud Service cria uma sessão para o usuário e emite um código de autorização.
O aplicativo web faz uma chamada de back-end (ou servidor para servidor) para trocar o código de autorização por um token de acesso.
O Oracle Identity Cloud Service emite um token de acesso e um token de id.
Uma sessão é estabelecida e o usuário é redirecionado para a Home page.
A Home page do aplicativo Web é exibida.

Caso de Uso No 2: Obter Detalhes Sobre o Usuário

A seguir, descrição de get-details-user.png

Descrição da ilustração get-details-user.png

O fluxo de dados acontece desta forma:

O usuário solicita o recurso /myProfile.
O aplicativo Web usa o SDK do Oracle Identity Cloud Service para validar o token de id.
Os dados que retornam da validação do token de id contêm detalhes do usuário no formato de um objeto JSON.
A página Meu Perfil renderiza o objeto JSON como conteúdo HTML.

Aprender sobre Métodos e Funções

O SDK Node.js é uma estratégia de passaporte Node.js que você adiciona à sua pasta Node.js modules. Esse SDK também é baseado nas promessas do Node.js.

Todas as dependências de terceiros de que o SDK Node.js precisa são definidas no arquivo package.json do SDK dentro do arquivo zip do SDK Node.js que você faz download na console do Oracle Identity Cloud Service. Você precisa usar pelo menos este conjunto de módulos no seu aplicativo Web Node.js.

"dependencies": {
    "async": "^2.1.2",
    "bunyan": "^1.8.5",
    "cache-manager": "^2.2.0",
    "json-web-token": "^2.1.3",
    "jsonwebtoken": "^8.2.1",
    "jwk-to-pem": "^1.2.6",
    "jws": "^3.1.5",
    "lru": "^3.1.0",
    "passport": "^0.4.0",
    "promise": "^8.0.1",
    "querystring": "^0.2.0",
    "request": "^2.81.0",
    "rsa-pem-to-jwk": "^1.1.3",
    "util": "^0.10.3"
  },

Um aplicativo Web Node.js foi desenvolvido usando os módulos Node.js express e express-handlebars, que implementa rotas de URL na forma de uma função app.get() para cada URL.

O SDK Node.js requer uma variável JSON carregada com informações de conexão do Oracle Identity Cloud Service. O aplicativo Web Node.js usa a variável ids para armazenar essas informações:

var ids = {
    oracle: {
    "ClientId": "123456789abcdefghij'",
    "ClientSecret": "abcde-12345-zyxvu-98765-qwerty",
    "ClientTenant": "idcs-abcd1234",
    "IDCSHost": "https://%tenant%.identity.oraclecloud.com",
    "AudienceServiceUrl" : "https://idcs-abcd1234.identity.oraclecloud.com",
    "TokenIssuer": "https://identity.oraclecloud.com/",
    "scope": "urn:opc:idm:t.user.me openid",
    "logoutSufix": "/oauth2/v1/userlogout",
    "redirectURL": "http://localhost:3000/callback",
    "LogLevel":"INFO",
    "ConsoleLog":"True"
    }
};
module.exports = ids;

Veja abaixo uma breve explicação de cada atributo necessário para este SDK:

Nome	Descrição
`ClientId`	O valor do ID do Cliente gerado depois que você registra o aplicativo Web Node.js na console do Oracle Identity Cloud Service.
`ClientSecret`	O valor do Segredo do Cliente gerado depois que você registra o aplicativo Web Node.js na console do Oracle Identity Cloud Service.
`ClientTenant`	O prefixo de domínio da sua instância do Oracle Identity Cloud Service. Esse prefixo geralmente é semelhante a `idcs-abcd1234`.
`IDCSHost`	O sufixo de domínio da sua instância do Oracle Identity Cloud Service. No runtime, o espaço reservado %tenant% é substituído pelo valor do atributo ClientTenant.
`AudienceServiceUrl`	O URL de nome de domínio totalmente qualificado da sua instância do Oracle Identity Cloud Service.
`TokenIssuer`	Para esse atributo, a Oracle recomenda que você mantenha o valor `https://identity.oraclecloud.com/`.
`scope`	O escopo controla os dados que o aplicativo pode acessar ou processar em nome do usuário do Oracle Identity Cloud Service. Se o aplicativo usar o SDK para autenticar um usuário, o escopo será `openid`. Se o aplicativo usar o SDK para obter detalhes sobre o usuário, o escopo será `urn:opc:idm:t.user.me openid`.
`ConsoleLog`	Ativa o log do SDK.
`LogLevel`	Indica o nível de log do SDK.

O aplicativo usa os atributos logoutSufix e redirectURL para evitar que esses valores sejam codificados. O SDK não os exige.

O aplicativo Node.js implementa a rota do URL /oauth/oracle. Quando um usuário faz a autenticação com o Oracle Identity Cloud Service, o Web browser faz uma solicitação GET para esse URL. Essa rota usa o SDK para gerar o URL de autorização do Oracle Identity Cloud Service.

//Loading the configurations
var auth = require('./auth.js');
 
//Route for /oauth/oracle
app.get("/auth/oracle", function(req, res){
    //Authentication Manager loaded with the configurations.
    am = new IdcsAuthenticationManager(auth.oracle);
    //Using Authentication Manager to generate the Authorization Code URL, passing the
    //application's callback URL as parameter, along with code value and code parameter.
    am.getAuthorizationCodeUrl(auth.oracle.redirectURL, auth.oracle.scope, "1234", "code")
        .then(function(authZurl){
            //Redirecting the browser to the Oracle Identity Cloud Service Authorization URL.
            res.redirect(authZurl);
        }).catch(function(err){
            res.end(err);
        })
});

Essa função carrega os parâmetros JSON para uma variável, inicializa um gerenciador de autenticação e usa a função IdcsAuthenticationManager.getAuthorizationCodeUrl() do SDK Node.js para gerar o URL do código de autorização. Esta função usa a promessa de redirecionar o navegador da Web do usuário quando o URL do código de autorização é gerado ou para gerar um erro no navegador.

Os seguintes parâmetros são usados para gerar o URL do código de autorização:

Nome	Descrição
`auth.oracle.redirectURL`	Depois que um usuário acessa, o Oracle Identity Cloud Service redireciona o Web browser do usuário para esse URL. Esse URL deve corresponder ao que você configurará para o aplicativo confiável na console do Identity Cloud Service. Consulte Registrar o Aplicativo Node.js para obter mais informações sobre como especificar um URL de redirecionamento para o aplicativo Web Node.js.
`auth.oracle.scope`	O escopo de autenticação OAuth ou OpenID Connect. Este aplicativo requer apenas autenticação `openid`.
`state`	O protocolo OAuth define esse parâmetro. O aplicativo Web Node.js de amostra usa esse código para verificar se a comunicação pode ser estabelecida com o Oracle Identity Cloud Service. Para este exemplo, o valor desse parâmetro é `1234`.
`response_type`	O parâmetro exigido pelo tipo de concessão do código de autorização. Para este exemplo, o valor desse parâmetro é `code`.

Depois que o usuário acessa, o Oracle Identity Cloud Service redireciona o navegador Web do usuário para um URL de callback, que o desenvolvedor deve implementar. O aplicativo Web Node.js usa a rota /callback para tratar essa solicitação.

//Route for /callback
app.get("/callback", function(req,res){
    //Authentication Manager loaded with the configurations.
    var am = new IdcsAuthenticationManager(auth.oracle);
    //Getting the authorization code from the "code" parameter
    var authZcode = req.query.code;
    //Using the Authentication Manager to exchange the Authorization Code to an Access Token.
    am.authorizationCode(authZcode)
        .then(function(result){
            //Getting the Access and Id Token Values to set in the session.
            req.session.access_token = result.access_token;
            req.session.id_token = result.id_token;
            res.cookie(config.IDCS_COOKIE_NAME, result.access_token);
            res.header('idcs_user_assertion', result.access_token)
            res.redirect('/auth.html');
        }).catch(function(err){
            res.end(err);
        })
});

O aplicativo Node.js usa o código de autorização para solicitar um token de acesso. O token de acesso é armazenado como um cookie, que é enviado para o navegador da Web para uso futuro.

A função IdcsAuthenticationManager.authorizationCode() do SDK Node.js também usa promessa (uma instrução then-catch) para definir o token de acesso como um cookie e redirecionar o browser para a página /auth.html.

O SDK Node.js é baseado na estrutura de passaporte Node.js. Portanto, o browser deve encaminhar o token de acesso como uma variável de cabeçalho para o handler de URL /auth e usar o método passport.authenticate() com o nome da estratégia do Oracle Identity Cloud Service como parâmetro:

//Uses passport to create a User Session in Node.js.
//Passport sets a user attribute in the request as a json object.
app.get('/auth', passport.authenticate(config.IDCS_STRATEGY_NAME, {}), function(req, res) {
   res.redirect('/home');
});

Depois que o método passport.authenticate() cria a sessão do aplicativo, a função redireciona o Web browser do usuário para um URL protegido no aplicativo /home. Além de /home, o aplicativo Web Node.js tem outro URL protegido: /myProfile.

Qualquer URL protegido precisa verificar se a sessão do usuário foi criada anteriormente. A função a seguir é usada por cada função app.get() para esses URLs.

function ensureAuthenticated(req, res, next) {
   if (req.isAuthenticated()) {
      return next();
   }
   res.redirect('/login')
}

O aplicativo Node.js trata a rota /myProfile e obtém informações definidas na sessão, da seguinte forma:

app.get("/myProfile", ensureAuthenticated, function(req,res){
   //User Manager loaded with the configurations
   var am = new IdcsAuthenticationManager(auth.oracle);
   //Validating id token to acquire information such as UserID, DisplayName, list of groups and AppRoles assigned to the user.
   am.validateIdToken(req.session['id_token'])
    .then(function(idToken){
      res.render('myProfile', {
         layout: 'privateLayout',
         title: 'My Profile',
         user: req.user,
         userInfo: JSON.stringify(idToken, null, 2)
         });
    }).catch(function(err1){
       res.end(err1);
   })
});

Depois de inicializar o objeto IdcsAuthenticationManager, o handler da rota /myProfile usa a função IdcsAuthenticationManager.validateIdToken() do SDK para adquirir informações do usuário, como nome para exibição, id do usuário e a lista de grupos e atribuições de aplicativo designados ao usuário. Em seguida, o objeto JSON é analisado como string para o arquivo myProfile.handlebars para renderização no Web browser.

Para desconectar o usuário do sign-on único entre o aplicativo e o Oracle Identity Cloud Service, o aplicativo Web Node.js implementa a rota /logout, da seguinte forma:

app.get('/logout', function(req, res){
  var id_token = req.session.id_token;
  var logouturl = auth.oracle.AudienceServiceUrl + auth.oracle.logoutSufix + '?post_logout_redirect_uri=http%3A//localhost%3A3000&id_token_hint='+ id_token;
  req.session.destroy(function(err) {
    if(err) {
      console.log(err);
    } else {
      req.logout();
      res.clearCookie();
      res.redirect(logouturl);
    }
  })
});

Essa rota invalida a sessão do aplicativo, remove qualquer objeto e cookie definidos anteriormente e, em seguida, redireciona o Web browser do usuário para o URL de log-out OAuth do Oracle Identity Cloud Service.