Configure with OIDC - SSO integration

[lknite]

Goal

OpenID Connect integration

Summary

OpenID Connect (OIDC) is the latest standard for Single Sign on integration (SSO). It essentially replaces an older standard SAML, though it was never designed to replace SAML (and SAML still provides some functionality that OpenID Connect doesn't). However, due to the popularity, and easy of configuration, it has become the dominate standard.

By implementing SSO using OIDC a user may log in once to an application and then have access to multiple applications without an additional login. OIDC handles login, providing access token & refresh tokens, as well as claims such as username and group membership. By using OIDC, if configured at deployment, all users of a group or any logged in user will be able to access their own heimdall dashboard automatically, if a user is in a group configured as an administrator group, then they will have administrator access enabled by default.

Requirements

• OIDC configuration
• option: ability to onboard a username via sso (most would default this to true)
• option: ignore tls verification between heimdall server and the oidc server (useful if using a local certificate authority and newly configuring heimdall app, or oidc server)
• option: configure admins via groups claim

Milestones

1. Implement bearer token recognition (may be skipped, and oidc fully implemented from the start, see milestone 2)

• Configure oauth2-proxy in front of heimdall. oauth2-proxy can be placed in front of an app requiring a user to login to an unprotected app. oauth2-proxy can restrict access using groups claims. However, this sort of protection doesn't pass along user information to the app by default. It can however be enabled to pass along an 'authorization' header which contains a 'bearer token'. The bearer token can be examined at a website such as jwt.io, where you can see the username being passed along as well as groups the user is a member of.
• After setting up oauth2-proxy and passing along a bearer token, heimdall will be able to see the 'authorization' header and know what user is accessing the website. At this point a php library can be used to verify the bearer token is recognized as valid by checking with a configured oidc server, such as 'keycloak'.
• Add the configuration of the oidc server somewhere, such as a json file, however heimdall does configuration
• Add a flag somewhere to indicate the heimdall server will use the bearer token when provided, if valid
• Add a flag to onboard users via the bearer token, this is typical with many apps, but it may not be desired to always add a user just because they were able to log in successfully. Some may only want to onboard users if they are a member of a certain group for example, but for now just add a flag to onboard or not if they've successfully logged in
• At this point point a major milestone has been achieved, by using oauth2-proxy and using the bearer token it provides oidc integration has been successfully implemented and will be usable by more technical folks. This is the method implemented by the kubernetes dashboard. (see https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/ and search for bearer token)

2. Full oidc implementation (configuration file)

• create method to configure oidc using a configuration file such as json, using gitops this is the preferred method to configure (vs using a gui)
• add flag to require a bearer token for access
• implement the ability to redirect to an sso server to gather up a bearer token, if one is not provided

3. Full oidc implementation (gui)

• implement ability to login with an administrator account if oidc is not configured (so the admin can configure oidc or manual user onboarding)
• implement gui which allows for the configuration of oidc with an application already running

Ideas for implementation

Harbor has a nice gui to configure oidc that we might want to copy:

Configuring harbor oidc using json which we might want to copy:

    configOverwriteJson: |
      {
        "auth_mode": "oidc_auth",
        "oidc_name": "keycloak",
        "oidc_endpoint": "https://keycloak.vc-prod.k.home.net/auth/realms/home",
        "oidc_groups_claim": "groups",
        "oidc_admin_group": "k-prod-app-harbor-admin",
        "oidc_client_id": "k.vc-prod.harbor",
        "oidc_client_secret": "E9mxn6cXBTuq7OZBhVLBLPworafuUVLP",
        "oidc_scope": "openid,email,profile,offline_access",
        "oidc_verify_cert": "false",
        "oidc_auto_onboard": "true",
        "oidc_user_claim": "preferred_username"
      }

Many apps will have a main screen with an option to login in with a configured identity provider, or admin (in case an identity provider is not configured, or folks have decided to use a local user db), here's a screenshot from argocd:

Additional notes

By using oidc we'd get pretty much all desired implementations. Using keycloak for example, as the identity provider, means the keycloak admin can configure LDAP as the user federation source meaning LDAP, or github, or many others, can be used behind the scene with keycloak providing the login gui. Keycloak is redhat's upstream SSO solution. Microsoft Azure can also be used with OIDC, as well as pretty much all other identity providers.

[lknite]

Several libraries exist to ease implementation, maybe we could use:
https://github.com/jumbojett/OpenID-Connect-PHP

Or maybe one of these:
https://oauth.net/code/php/

Am available to assist maintainer with getting keycloak & oauth2-proxy working up to the point of providing a bearer token to heimdall.

[lknite]

In summary, as I write this to tempt the maintainer, once you are at the heimdall main page and have a bearer token, you also have the username of the person logged in and groups they are a member of.

Seems it wouldn't take too much at that point to create a user account for the user and recognize they are logged in. (That's where I'm at now, looking at the php code and seeing how to add the username that was passed in. Not sure I'm the right person to add this. Haven't used php in quite awhile.)

The other part of oidc / oauth is seeing there is no bearer token and redirecting them to the identity server. The oidc php library will do this automatically, letting you know who the person is or redirecting them to login and letting you know who the person is when they get back.

[lknite]

Maybe we can already do this by configuring laravel?
https://github.com/maicol07/laravel-oidc-client
https://github.com/robsontenorio/laravel-keycloak-guard
https://github.com/mariovalney/laravel-keycloak-web-guard

Posted as a feature request issue:
#899
#900

[lknite]

With the latest heimdall release I've been able to get a couple OIDC plugins to work. Upon visiting a page I'm redirected to keycloak and prompted for a login. After logging in I am redirected back to the original page ... at this point I'm showing as the default user. So, essentially the tested setup just requires a valid username and password to access the site. The pages need to accept the token passed in and use the username and groups that are provided.

Features will needed to be added besides just the OIDC authentication. I'm not sure all of what is required but know of a few:

• need to implement the idea of an 'admin', with regular users not having admin access
• ability to handle groups, if user is a member of the admin group they should get admin privileges, if not then no admin privileges
• ability to handle a user, onboarding the user upon first authentication
• since we will not be creating users or editing them, those pages need to be adjusted if OIDC is in use ... this is good as the identity provider will take care of timing out a login and requiring a re-login after awhile, as well as other maintenance such as handling someone forgetting their password
• if desired, the ability to display a default, or selected dashboard, if no user has logged in.
• others?

[lknite]

Made a video for those considering implementing OIDC in their application:

OIDC for contributors

[huslage]

Hi @lknite has there been any progress with this? I can't find any info in the docs.

[lknite]

I would really like to have oidc working with heimdall. Seems someone with a little more experience than me with php and the underlying laravel technology should be able to get it working with very little effort. So I put a lot of effort into describing oidc for folks new to it.

I tried to get it to work myself but I guess I'm just not interested enough to do it myself, I'm not interested in learning the underlying heimdall architecture or becoming a maintainer. I'd be more likely to rewrite heimdall using flutter and implement oidc from the start... actually, not a terrible idea. Maybe I could make it handle heimdall's application library.

The maintainer doesn't have the time or interest to do it himself, but he does welcome code pull requests.

[Smith-fms]

heimdall with OIDC SSO would be perfect for family and company use.
I manage a volunteer network and heimdall as central dashboard would be perfect!

[EHRETic]

If I can upvote this functionality, I'd like to integrate Heimdall with Authentik too 🙂

[andrewmeyer]

unfortunately it does not appear that there is much interest in this feature (I type while trying to resurrect it, haha). Remote user management would be amazing for home labers as well as small orgs who want dashboards for teams to use for daily operations. If this gets added I will likely switch back to Heimdall as my browser start page. I'll keep my fingers crossed that this gets some traction!

[lknite]

I think the interest is there, it's just there seems to be one maintainer and at least a couple years ago he didn't have the time. I'll see if I can find him again and check in.

[ricklambrechts]

This Laravel Package is also available. minvws/openid-connect-php-laravel.
It uses the jumbojett/OpenID-Connect-PHP.

With that package you should be able to easily handle the userinfo response and do your own logic.

There is also a Socialite provider for Keycloak.
https://socialiteproviders.com/Keycloak/

[Stizzy-98]

Gents its 2025 and I really would like this for company and home use lol