SFTPGo OIDC with Kanidm: using service accounts or a 2-client setup

[stratself]

Hi everyone, I'd like to share my Kanidm + SFTPGo integration using two approaches. For the first, I employed Kanidm's service account feature to be SFTPGo's admin, as it helps having a limited scope access account for management.

For the second, I want myself to be both user and admin of SFTPGo. However, I don't really like implicit_roles as it allows privileged access without attesting any claims from the IDM. So instead I configure 2 client IDs for webAdmin and webClient separately, that redirects to two separate domains/bindings.

I think this approach would be better as it outsources sftpgo role management back to the IDM as the single source of truth, and it should be straightforward to implement with other software e.g. Authentik, Authelia. But honestly I'm not sure of all security implications it entails. Please share any improvements or details you may have with it, thanks!

1. Service account approach

If you'd like a dedicated admin account for SFTPGo, you should look at service accounts. They're non-human, scope-limited accounts meant to be managed by a privileged group (usually idm_service_account_admins). Members of that group can then manage the service account from their own login sessions.

graph TD
subgraph Kanidm
    user:demo-user -->|part of| group:idm_service_account_admins -.-> |manages| svc-account:sftpgo-admin -->|part of| group:sftpgo_admins
    user:demo-user -->|part of| group:sftpgo_users
end

subgraph client:SFTPGo
    group:sftpgo_users -->|claim:sftpgo_role:user| webclient
    group:sftpgo_admins -->|claim:sftpgo_role:admin| webadmin
end

Loading

The main drawback however, is that there can only be one logon password per service account. Supposedly there is also a new design proposal for better SAs OAuth2 support, but we resort to sharing the password for now.

Kanidm

First, create a service account sftpgo-admin and make it a member of the sftpgo_admins group:

# in this example, sftpgo-admin is managed by idm_service_account_admins
kanidm service-account create sftpgo-admin "SFTPGo Admin" idm_service_account_admins

kanidm group create sftpgo_admins
kanidm group add-members sftpgo_admins sftpgo-admin

Then, create an sftpgo_users group with a user (e.g. demo-user) in it:

kanidm person create demo-user "Demo user"
kanidm group add-members demo-user idm_service_account_admins #allows management of svc-acc
kanidm group create sftpgo_users
kanidm group add-members sftpgo_users demo-user

Then, create an oauth2 client and configure it as below:

kanidm system oauth2 create sftpgo "SFTPGo" https://sftpgo.example.com

# use preferred_username field instead of spn
kanidm system oauth2 prefer-short-username sftpgo
# disable PKCE as SFTPGo doesn't support it
kanidm system oauth2 warning-insecure-client-disable-pkce sftpgo

# Add the relevant redirect URL
kanidm system oauth2 add-redirect-url sftpgo  https://sftpgo.example.com/web/oidc/redirect

# allow SFTPGo to retrieve the relevant scopes (email, openid, profile) for the sftpgo_* groups
kanidm system oauth2 update-scope-map sftpgo sftpgo_users email openid profile
kanidm system oauth2 update-scope-map sftpgo sftpgo_admins email openid profile

Finally, you have to define the sftpgo_role claim for each group:

kanidm system oauth2 update-claim-map sftpgo sftpgo_role sftpgo_users user
kanidm system oauth2 update-claim-map sftpgo sftpgo_role sftpgo_admins admin
# kanidm system oauth2 enable-strict-redirect-url sftpgo

Run this to see the basic secret to be used in next step:

kanidm system oauth2 show-basic-secret sftpgo

SFTPGo

Define the env vars in SFTPGo. Note the secret taken from previous step:

# Get client secret in previous step
SFTPGO_HTTPD__BINDINGS__0__OIDC__CLIENT_SECRET="<client-secret>"
SFTPGO_HTTPD__BINDINGS__0__OIDC__CLIENT_ID="sftpgo"
SFTPGO_HTTPD__BINDINGS__0__OIDC__CONFIG_URL=https://kanidm.example.com/oauth2/openid/sftpgo
SFTPGO_HTTPD__BINDINGS__0__OIDC__REDIRECT_BASE_URL=https://sftpgo.example.com
SFTPGO_HTTPD__BINDINGS__0__OIDC__USERNAME_FIELD="preferred_username"
SFTPGO_HTTPD__BINDINGS__0__OIDC__SCOPES="openid,profile,email"
SFTPGO_HTTPD__BINDINGS__0__OIDC__ROLE_FIELD="sftpgo_role"

Restart SFTPGo. It should now work.

2. Two domains, two bindings approach

If instead, you want to be both admin and user, then consider hosting webAdmin and webClient on two different bindings, with different ports, that maps to two different domains, and has different OAuth2 client IDs. The webAdmin and webClient are now "separate" services, allowing separate sftpgo_role claims to be attested per-account.

graph TD
subgraph Kanidm
    user:demo-user -->|part of| group:sftpgo_admins
    user:demo-user -->|part of| group:sftpgo_users
    group:sftpgo_admins
    group:sftpgo_users
end

subgraph SFTPGo
    subgraph client:sftpgo-webclient
        group:sftpgo_users -->|https:\/\/sftpgo-webclient.example.com| webclient[webclient on binding 0 port 8080]
    end
    subgraph client:sftpgo-webadmin
        group:sftpgo_admins -->|https:\/\/sftpgo-webadmin.example.com| webadmin[webadmin on binding 1 port 9090]
    end
end

Loading

You can use a reverse proxy to map different ports to different domains. It's out-of-scope for this guide but should be fairly easy to do.

Kanidm

First, add our demo-user to both sftpgo_admins and sftpgo_users:

kanidm group create sftpgo_admins
kanidm group add-members sftpgo_admins demo-user
kanidm group create sftpgo_users
kanidm group add-members sftpgo_users demo-user

Then, create 2 OAuth2 clients - sftpgo_webadmin and sftpgo_webclient. Each of them will be mapped exclusively to their user groups - sftpgo_admins and sftpgo_users respectively. They'll also have different origin domains.

For sftpgo_webadmin

kanidm system oauth2 create sftpgo_webadmin "SFTPGo WebAdmin" https://sftpgo-webadmin.example.com

# use preferred_username field instead of spn
kanidm system oauth2 prefer-short-username sftpgo_webadmin
# disable PKCE as SFTPGo doesn't support it
kanidm system oauth2 warning-insecure-client-disable-pkce sftpgo_webadmin

# Add the relevant redirect URL
kanidm system oauth2 add-redirect-url sftpgo_webadmin  https://sftpgo-webadmin.example.com/web/oidc/redirect

# allow SFTPGo to retrieve the relevant scopes (email, openid, profile) for the sftpgo_* groups
kanidm system oauth2 update-scope-map sftpgo_webadmin sftpgo_admins email openid profile

# add the admin role claim for sftpgo_admins
kanidm system oauth2 update-claim-map sftpgo_webadmin sftpgo_role sftpgo_admins admin

For sftpgo_webclient

kanidm system oauth2 create sftpgo_webclient "SFTPGo WebClient" https://sftpgo-webclient.example.com

# use preferred_username field instead of spn
kanidm system oauth2 prefer-short-username sftpgo_webclient
# disable PKCE as SFTPGo doesn't support it
kanidm system oauth2 warning-insecure-client-disable-pkce sftpgo_webclient

# Add the relevant redirect URL
kanidm system oauth2 add-redirect-url sftpgo_webclient  https://sftpgo-webclient.example.com/web/oidc/redirect

# allow SFTPGo to retrieve the relevant scopes (email, openid, profile) for the sftpgo_* groups
kanidm system oauth2 update-scope-map sftpgo_webclient sftpgo_users email openid profile
# add the user role claim for sftpgo_users
kanidm system oauth2 update-claim-map sftpgo_webclient sftpgo_role sftpgo_users user

SFTPGo

Fetch the client secrets with kanidm:

kanidm system oauth2 show-basic-secret sftpgo_webclient
kanidm system oauth2 show-basic-secret sftpgo_webadmin

Configure the env vars for SFTPGo. Note the different ports and URLs.

# First binding
SFTPGO_HTTPD__BINDINGS__0__ENABLE_WEB_ADMIN=false #disable webAdmin here
SFTPGO_HTTPD__BINDINGS__0__PORT=8080
SFTPGO_HTTPD__BINDINGS__0__OIDC__CLIENT_ID="<sftpgo_webclient_secret>"
SFTPGO_HTTPD__BINDINGS__0__OIDC__CLIENT_SECRET=""
SFTPGO_HTTPD__BINDINGS__0__OIDC__CONFIG_URL=https://kanidm.example.com/oauth2/openid/sftpgo_webclient
SFTPGO_HTTPD__BINDINGS__0__OIDC__REDIRECT_BASE_URL=https://sftpgo-webclient.example.com
SFTPGO_HTTPD__BINDINGS__0__OIDC__USERNAME_FIELD="preferred_username"
SFTPGO_HTTPD__BINDINGS__0__OIDC__SCOPES="openid,profile,email"
SFTPGO_HTTPD__BINDINGS__0__OIDC__ROLE_FIELD="sftpgo_role"

# Second binding
SFTPGO_HTTPD__BINDINGS__1__ENABLE_WEB_CLIENT=false #disable webClient here
SFTPGO_HTTPD__BINDINGS__1__PORT=9090
SFTPGO_HTTPD__BINDINGS__1__OIDC__CLIENT_ID="sftpgo_webadmin"
SFTPGO_HTTPD__BINDINGS__1__OIDC__CLIENT_SECRET="<sftpgo_webadmin_secret>"
SFTPGO_HTTPD__BINDINGS__1__OIDC__CONFIG_URL=https://kanidm.example.com/oauth2/openid/sftpgo_webadmin
SFTPGO_HTTPD__BINDINGS__1__OIDC__REDIRECT_BASE_URL=https://sftpgo-webadmin.example.com
SFTPGO_HTTPD__BINDINGS__1__OIDC__USERNAME_FIELD="preferred_username"
SFTPGO_HTTPD__BINDINGS__1__OIDC__SCOPES="openid,profile,email"
SFTPGO_HTTPD__BINDINGS__1__OIDC__ROLE_FIELD="sftpgo_role"

Restart SFTPGo. The demo-user should now be able to log on with OIDC as different roles, via separate URL links for webClient and webAdmin.

[stratself]

Tip: I'm trying to get accounts to auto-create using the Event Manager, and notice that some custom claims {{IDPField<something>}} are missing in the final user fields, even though the logs says otherwise:

{"level":"debug","time":"2025-XX-XXTXX:XX:XX.XXX","sender":"httpd","message":"custom field \"sftpgo_role\" found in token claims"}

This is because kanidm by default stores the claim as an array rather than a string. To convert to strings, run this:

kanidm system oauth2 update-claim-map-join sftpgo sftpgo_role ssv

(csv would also work)

Might as well look into integration with ssh_publickeys via login hooks, and post here if anyone's interested. They're provided as an array so Event Manager won't cut it.

EDIT: It's not that hard. Follow #1072 and pass --argjson instead of --arg when you come across an array. Or use the enterprise edition as drakkan mentions

[drakkan]

Thanks for sharing. I’ve never used Kanidm myself, but it looks really impressive

This is because kanidm by default stores the claim as an array rather than a string. To convert to strings, run this:

In SFTPGo Enterprise, we've revamped the EventManager placeholder system. You can now iterate over arrays, eliminating the need to include all strings from the IDP provider, example:

...
"groups": [
    {{- $roles := .IDPFields.sftpgo_role -}}
    {{- range $i, $role := $roles -}}
        {{- if ne $i 0}},{{end}}
      {"type": {{if eq $i 0}}1{{else}}2{{end}},
      "name": {{$role | toJson}}}
    {{- end}}
    ]
....

More details can be found in the docs.