iserv-sso-client

An inofficial client for IServ Oauth2 / Single-Sign-On / OpenID Connect

How to use

First you'll need to create a IServ SSO Application. This is documented here

You should set Vertrauenswürdig to Ja and choose the scopes E-Mail, OpenID, Profil, Rollen

Copy the Client-ID and Client-Geheimnis you'll need this for your app.

Example App using Express

const SSOClient = require('iserv-sso-client') // Import SSO Module
const express = require('express') // Web Server
const session = require('express-session') // Needed to store codeVerifier in session
const app = express() // Create Web Server

app.use(session({
  secret: 'ENTER RANDOM LETTERS HERE',
  resave: false,
  saveUninitialized: true
})) // Activate Session

// Create new SSO Client
const ssoClient = new SSOClient({
    iserv: 'mein-iserv.de', // It is important to type the url like this without a slash at the end and no https:// in the beginning
    clientId: 'YOUR CLIENT ID HERE',
    clientSecret: 'YOUR CLIENT SECRET/GEHEIMNIS HERE',
    redirectUri: 'http://localhost/openid-granted',
})

async function main() {

await ssoClient.init() // Initialize SSO Client (IMPORTANT: Use await here)

app.get('/', (req, res) => {
    res.redirect('/login')
})

app.get('/login', (req, res) => {
    const redirector = ssoClient.getRedirector() // Get Redirector
    req.session.codeVerifier = redirector.codeVerifier // Store codeVerifier in session
    res.redirect(redirector.redirectUri) // Redirect client
})

app.get('/openid-granted', async (req, res) => {
    const codeVerifier = req.session.codeVerifier // Get codeVerifier from session

    const user = await ssoClient.fetch(req, codeVerifier) // Fetch User (IMPORTANT: Use await here)
    
    if (user === 'ERR') return res.send('An error occured') // If an error occured, return error message (IMPORTANT: If no error handling is implemented, your app will crash)
    
    res.send(`
        <h1>Hi, ${user.getUsername()}</h1>
        <p>Your email is ${user.getEmail()}</p>
        <p>Your roles are ${user.getRoles()}</p>
        <p>You'll need to refresh your access token in: ${user.getAccessTokenExpireCountdown()}ms</p>
    `) // Send UserData
})

app.listen(80, () => console.log('Listening on port 80'))

}

main()

For this script we use the callback /openid-granted so you need to set http://localhost/openid-granted as the Redirect URL in your code and your IServ SSO Application You also need to change the CLIENT ID and CLIENT SECRET

Refreshing an access token

In the callback after you've got the User I recommend to use setInterval to request an new access token every 55 Minutes

setInterval(async () => {
    await user.refreshAccessToken()
}, 55 * 60 * 1000)

Docs