passport-cortex
v0.1.0
Published
PassportJS authentication for Palo Alto Networks Cortex
Downloads
3
Maintainers
Readme
passport-cortex
A PassportJS strategy for Palo Alto Networks Cortex
This library makes it easy for any express, koa, or other NodeJS app using Passport to perform OAuth2 authentication with Palo Alto Networks Cortex. This authentication grants the app access to logs stored in the Cortex Data Lake.
Install
npm install --save passport-cortex
Simple example
Single datalake, just to get things working quickly
Create two API endpoints in your app, one for auth redirection and one for the auth callback.
Here's an example using express:
const express = require('express')
const passport = require('passport')
const CortexStrategy = require('passport-cortex').CortexStrategy
const app = express()
// other express setup here
passport.use(new CortexStrategy(
{
clientID: PAN_CLIENT_ID,
clientSecret: PAN_CLIENT_SECRET,
callbackURL: 'https://<myserver>/cortex-callback',
scope: 'logging-service:read',
instanceId: PAN_INSTANCE_ID,
},
(accessToken, refreshToken, params, profile, done) => {
// Here you can see the `accessToken`, `refreshToken`,
// and `params.expireIn` (seconds until the accessToken expires).
// This is a good time to store these tokens somewhere secure.
return done(null, {})
}
))
app.get('/cortex-activate', passport.authenticate('cortex', { session: false }))
app.get('/cortex-callback', passport.authenticate('cortex', { session: false }))
In this example, when a user navigates to the /cortex-activate
endpoint, call
passport.authenticate
. Use { session: false }
since this is authentication
does not represent the application user, but a connection to a datalake.
After the redirect and the user approval, Cortex will redirect back to the
callback endpoint with a code
parameter. The verify callback
function you passed into the CortexStrategy
constructor provides the accessToken
and
refreshToken
so you can do any needed verification and store the tokens
somewhere secure. Call done(null, {})
once the tokens are stored.
The instanceId
is passed in the CortexStrategy
constructor. Therefore, all
passport.authenticate()
calls will use this instance ID, unless you specify
otherwise in the call. This is an easy setup for a single tenant app for a specific datalake.
State validation
More secure through extra validation
While the simple example above is great to get started, you'll want to enable state validation in production. This requires express-session to store the state between OAuth2 stages.
If you haven't already, enable sessions in Express and Passport:
// This goes in your imports at the top of the file
const session = require('express-session')
// This goes somewhere in your express app setup
// Change the settings here for your app.
app.use(session({ secret: 'changeme', resave: false, saveUninitialized: true }))
app.use(passport.initialize())
app.use(passport.session())
Now tell the Cortex Passport strategy to validate the OAuth2 state:
passport.use(new CortexStrategy(
{
clientID: PAN_CLIENT_ID,
clientSecret: PAN_CLIENT_SECRET,
callbackURL: 'https://<myserver>/cortex-callback',
scope: 'logging-service:read',
instanceId: PAN_INSTANCE_ID,
state: true // <---- add this to enable state validation. That's it!
},
(accessToken, refreshToken, params, profile, done) => {
return done(null, {})
}
))
All the state validation happens under the hood. If the state is invalid, authentication will fail.
Multi-datalake
Query logs from multiple datalakes
The previous examples connect to one Cortex datalake. For a multi-tenant or
multi-datalake app, you can pass the instanceId
in at the time of
authentication. You'll also want to save this instanceId
somewhere so when you get the
tokens, you'll know which datalake they are for. In this example, the instanceId
is saved in req.session.datalake
, then used inside the validate callback to
associate the tokens with the datalake.
passport.use(new CortexStrategy(
{
clientID: PAN_CLIENT_ID,
clientSecret: PAN_CLIENT_SECRET,
callbackURL: 'https://<myserver>/cortex-callback',
scope: 'logging-service:read',
state: true,
passReqToCallback: true // <-- Add this and add `req` to the callback below
},
(req, accessToken, refreshToken, profile, done) => {
// Here you can see the `accessToken`, `refreshToken`,
// and `params.expireIn` (seconds until the accessToken expires).
// Now you can also see `req.session.datalake` so you know which
// datalake in the database these tokens belong to.
// This is a good time to store these tokens in the database.
return done(null, {})
}
))
app.get('/cortex-activate', (req, res, next) => {
// URL is accessed like this: /cortex-activate?datalake=20837298375297345
// Save the datalake from the a query parameter to the session
// Note: you should validate the datalake parameter here, too.
req.session.datalake = req.query.datalake
passport.authenticate('cortex', {
session: false,
instanceId: req.query.datalake
})(req, res, next)
})
app.get('/cortex-callback', passport.authenticate('cortex', { session: false }))
This is just one way to associate the tokens with the datalake instance. You may
prefer to use another method for your app. passport-cortex
does not prescribe
any specific way to associate the tokens to the datalake.
Log Queries
Now that you've authenticated to Palo Alto Networks Cortex, you can make
queries. Queries are outside the scope of this passport-cortex
, so use the
pancloud library to make the queries. Simply pass it the refreshToken
and accessToken
when making queries and it will handle the query polling and
token refresh for you.