OpenID Connect for OPNsense

This package will allow you and your administrators to login to the OPNsense dashboard with a OpenID Connect provider.

Installation

Download the package from releases and install on your opnsense via the console:

pkg add os-oidc-1.0.pkg

Configuration

Provider Url

This is a link to the provider. The URL will need to have /.well-known/openid-configuration available for discovery.

Client ID

The provided ID from your OIDC provider

Client Secret

The secret from your OIDC provider

Username Claim

The field from the user payload that contains the username.

Scopes

Scopes to request form the OIDC Provider. For example, openid, email, profile.

Automatic user creation

When a user logins and does not have a matching user account in the local database, this will create a new user. This is to be used in conjunction with Default Groups

Warning

It is recommended to keep this disabled. Your firewall isn't a service that should readily accept new users.

Default Groups

When a new user is created, these groups will be assigned to them.

Icon Url

An optional URL that will be proxied for the login button. You can access it at /api/oidc/auth/icon?provider=<name>

Custom Button

When provided, the button will be replaced with the custom one. There are several templates available:

• %name% Name of the provider
• %url% URL that will start the auth flow
• %icon% The proxied icon image (useful to avoid CORS).

As an example, here is one that makes a nice big icon next to the login button

<a href="%url%" class="btn btn-primary"><img src="%icon%" style="height: 2em"> Login with %name%</a> 
<style>.login-sso-link-container { display: flex; justify-content: end; margin-top: 15px; margin-right: 9px; }</style>

Before	After

Mapping

Users being logged in are mapped against the preferred_name claim and is checked against the local database's username and email fields.

There is no group maaping at this stage.

Provider Setup

All Providers

Property	Value
Callback	https://<ip of opnsense>>/api/oidc/auth/callback

PocketID

provider:

Property	Value
Public Client	false
PKCE	false
Requires Re-Authentication	false

client (opnsense):

Setting	Value
Username claim	preferred_username

Authentik

WIP

Development

VScode

To get VSCode to behave correctly with the OPNSense PHP, we will need to tell the language server where to find the classes we use. I use Intelephense for work, and this is easy to configure with the includePaths setting.

There are several parts we need:

1. opnsense/core
   • This handles all the core functionality with OPNSense
2. phalcon/ide-stubs
   • OPNSense uses the Phalcon framework, and this is a stubs library specifically for this use case.

Once these are cloned into a repository, you can configure Intelephense to use them:

{
    "intelephense.environment.includePaths": [
        "D:\\projects\\opnsense\\core\\src\\opnsense\\mvc",
        "D:\\projects\\opnsense\\core\\src\\etc\\inc",
        "D:\\projects\\opnsense\\core\\src\\www",
        "D:\\projects\\opnsense\\ide-stubs\\src"
    ],
    "explorer.compactFolders": false,
    "files.associations": {
        "*.inc": "php",
    }
}

Setup on OPNSense

Here are the steps i have gotten to work with setup.

1. Clone opnsense/plugins to /usr/plugins

2. Clone opnsense/tools to /usr/tools

3. cd /usr/tools and make update

4. make plugins (this might not be required. This will take a long time and tends to crash at libpam. I abort at this time )

5. Clone your project to ~/project-name

6. Copy the project's content to /usr/plugins/devel/project-name

7. Build with cd /usr/plugins/devel/project-name && make package

8. Install pkg add /usr/plugins/devel/project-name/work/pkg/*.pkg