passport-keycloak-bearer

passport-keycloak-bearer

HTTP Bearer authentication strategy for Passport and Keycloak.

This module lets you authenticate HTTP requests using bearer tokens with a Keycloak authority in your Node.js applications. Bearer tokens are typically used protect API endpoints, and are often issued using OAuth 2.0.

By plugging into Passport, bearer token support can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.

Install

$ npm install passport-keycloak-bearer

Usage

KeycloakBearerStrategy uses Bearer Token protocol to protect web resource/api. It works in the following manner: User sends a request to the protected web api which contains an access_token in either the authorization header or body. Passport extracts and validates the access_token, and propagates the claims in access_token and userProfile to the verify callback and let the framework finish the remaining authentication procedure. The userProfile parameter is the result of calling keycloak REST API (/realms/{realm-name}/protocol/openid-connect/userinfo).

On successful authentication, passport adds the user information to req.user and passes it to the next middleware, which is usually the business logic of the web resource/api. In case of error, passport sends back an unauthorized response.

Sample usage

  import KeycloakBearerStrategy from 'passport-keycloak-bearer'
  ...

  passport.use(new KeycloakBearerStrategy(({
      "realm": "master",
      "host": "https://keycloak.dev.com",
      "clientId": "test-test"
  }),
    function(verifiedToken, userProfile, done) {
      const user = doSomethingWithUser(userProfile);
      return done(null, user);
    }));

5.1.1.2 Options

• host (Required)

  The endpoint where Keykloak is running.

• clientId (Required)

  The client ID of your application.

• realm (Required)

  Your realm name.

• passReqToCallback (Optional - Default: false)

  Whether you want to use req as the first parameter in the verify callback. See section 5.1.1.3 for more details.

• loggingLevel (Optional - Default: 'warn')

  Logging level. 'debug', 'info', 'warn' or 'error'.

• customLogger (Optional)

  Custom logging instance. It must be able to log the following types: 'debug', 'info', 'warn' and 'error'.

Authenticate Requests

Use passport.authenticate(), specifying the 'keycloak' strategy, to authenticate requests. Requests containing bearer verifidT do not require session support, so the session option can be set to false.

For example, as route middleware in an Express application:

app.get('/profile', 
  passport.authenticate('keycloak', { session: false }),
  function(req, res) {
    res.json(req.user);
  });

Support

Submit an issue

Contribute

Contribute usage docs

License

MIT License

Simen Haugerud Granlund © 2018

Credits

• Simen Haugerud Granlund - Author