Nightly Pocket Measurement

    passport-keycloak-oauth2-oidc

    1.0.5 • Public • Published

    passport-keycloak-oauth2-oidc

    Passport strategy for authenticating with Keycloak using the OAuth2/OIDC API.

    This module lets you authenticate using Keycloak in your Node.js applications. By plugging into Passport, Keycloak authentication can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.

    Install

    $ npm install passport-keycloak-oauth2-oidc

    Usage

    Create an Application

    Before using passport-keycloak-oauth2-oidc, you must create a realm and client with your Keycloak.

    Configure Strategy

    The Keycloak authentication strategy authenticates requests by delegating to your Keycloak server using the OpenID Connect (OIDC/OAuth 2.0) protocol.

    When using this strategy, it's AuthorizationURL and TokenURL options are generated based on the authServerURL and realm options. You can find these two option values from the Applications->Installation section, or from the OAuth Clients->Installation section in your keycloak realm.

    Applications must supply a verify callback which accepts an accessToken, refreshToken and service-specific profile, and then calls the done callback supplying a user, which should be set to false if the credentials are not valid. If an exception occured, err should be set.

    Options:

    • realm Name of your KeyCloak realm (set to master by default).
    • authServerURL Base URL for you Realm authorization endpoint.
    • publicClient If your Keycloak client's Access Type is set to public (publicClient set to true by default).
    • clientID This will match your Application Name, resource or OAuth Client Name.
    • clientSecret If your Keycloak client's Access Type is set to confidential this is required (publicClient set to false).
    • callbackURL URL to which KeyCloak will redirect the user after granting authentication.
    • sslRequired requires SSL for (all|external|none) requests (set to external by default).

    Examples:

      var KeyCloakStrategy = require('passport-keycloak-oauth2-oidc').Strategy;
      passport.use(new KeyCloakStrategy({
          clientID: 'myOauthClient',
          realm: 'MyKeyCloakRealm',
          publicClient: 'false',
          clientSecret: '6ee0f303-faef-42d7-ba8e-00cdec755c42',
          sslRequired: 'external',
          authServerURL: 'https://keycloak.example.com/auth',
          callbackURL: 'https://www.example.com/keycloak/callback'
        },
        function(accessToken, refreshToken, profile, done) {
          User.findOrCreate(..., function err, user) {
            done(err, user);
          });
        }
      });

    Authenticate Requests

    Use passport.authenticate(), specifying the 'keycloak' strategy, to authenticate requests.

    For example, as route middleware in an Express application:

    app.get('/auth/keycloak',
      passport.authenticate('keycloak', { scope: ['profile'] }));
    
    app.get('/auth/keycloak/callback', 
      passport.authenticate('keycloak', { failureRedirect: '/login' }),
      function(req, res) {
        // Successful authentication, redirect home.
        res.redirect('/');
      });

    How to get Roles

    By default, Keycloak returns Roles information within AccessToken.

    If you are wondering to fetch Roles (e.g. realm_access roles, resource_access roles etc) within UserInfo endpoint, please make sure that Keycloak returns those claims .

    To add these claims to the UserInfo endpoint, edit the roles settings in the Client Scopes:

    Clients Scopes -> roles -> settings:

    • name: roles
    • Include In Token Scope: enable

    and in the client roles mappers settings, an example mapping :

    • name: client roles
    • mapper type: user client role
    • multivalued: on
    • token claim name: roles.resource_access.${client_id}.roles
    • claim JSON type: string
    • add to userinfo: enabled

    License

    The MIT License

    Install

    npm i passport-keycloak-oauth2-oidc

    DownloadsWeekly Downloads

    764

    Version

    1.0.5

    License

    MIT

    Unpacked Size

    16.1 kB

    Total Files

    10

    Last publish

    Collaborators

    • louie007