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) {
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