OIDC-based strong authentication setup

Introduction

This document describes how to activate OIDC-based strong authentication on a Linux server.

Preconfigured setups are provided for Signicat, Telia and Elisa.

Other service providers can also be configured, provided their OIDC implementation is compatible.

Typographic conventions

<this> denotes a variable value that must be replaced with your environment-specific information.

Requirements

• SSH access and root privileges on the server (on both nodes in a clustered environment)
• Access to D-Center with permissions for the instance being configured
• At least 3.24.0-1 version for SecAtGW-plugins and SecAtGW packages
  • Use rpm -q SecAtGW SecAtGW-plugins to check the versions
• Basic Linux command line knowledge

Clustered environment instructions

If you are running a clustered environment, only execute the steps on the ACTIVE node, unless otherwise instructed. To check the current status of the node, run the d3status command. If the command outputs PASSIVE, switch to the ACTIVE node before proceeding.

1. Basic setup

1.1. Edit /etc/postmantis.conf:

Add the following configuration under section ## ::Envelope Policy Section:

modify RCPT /\.GenericOIDC>/ /.s>/

Add the following configuration under section ## ::Other rules section::

if ($policy /GenericOIDC/) add HEADER:X-Policy GenericOIDC

1.2 Edit /etc/sysconfig/nftables.conf:

Add the following lines at the end of the file

# for GenericOIDC
add rule filter output ip daddr <testserverIPaddress> tcp dport 443 ct state new accept
add rule filter output ip daddr <productionserverIPaddress> tcp dport 443 ct state new accept

1.3 Restart services

systemctl restart d3policy
systemctl restart nftables 

2. Set up instance configurations:

2.1 Edit /server/<instance>/config/config.cfg

Edit the file to match the configurations below

• In case other plugins are already defined, separate with a comma: genericoidc,telia
• Add any preferred languages to GENERICOIDCLANG

PLUGINS genericoidc
USEPLUGINS 1
GENERICOIDCLANG fi,sv,no

2.2 Create configuration directories

Run the following commands

mkdir -p /server/<instance>/config/plugins/genericoidc
chown d3web.d3 /server/<instance>/config/plugins/genericoidc
chmod 755 /server/<instance>/config/plugins/genericoidc
cd /server/<instance>/config/plugins/genericoidc
cp -p /opt/Sec\@GW/plugins/genericoidc/config/* .

3. Make a contract with an identity provider

In this section, prepare files to be sent to the chosen identity provider

1. Make a contract with your preferred identity provider

2. Provide OIDC return URL https://<fqdn>/redirect.cgi as part of the contract or in a provided management interface

3. Run the following commands to set up keys for encrypted communication between your server and the identity provider

cd /server/<instance>/config/plugins/genericoidc
openssl genrsa -out key.pem 4096
openssl rsa -in key.pem -outform PEM -pubout -out public_encryption.pem
openssl genrsa -out sign.pem 4096
openssl rsa -in sign.pem -outform PEM -pubout -out public_signing.pem
chmod 660 key.pem sign.pem && chown d3sync:d3 key.pem sign.pem

4. Convert the PEM files public_encryption.pem and public_signing.pem to JWK format using an online tool, for example: https://8gwifi.org/jwkconvertfunctions.jsp

5. Pick your identity provider from below and follow the guide for setting up provider-side OIDC configurations

{
    "keys": [
        {"use":"enc","kty":"RSA","e":"AQAB","kid":"39fda53e-b7eb-4216-af27-df68e8c2cc41","n":"4GnGex0x1KxInyh7EAQv-svo5wwn8Agbqpes17rfI5m9Nx8TV3a1MQoC9yqaTb-uezJ3gzljox8kNtGxkc1jy3WOTXm2JQcSRcXP4t2kOcgMraPZsAPHIkPwxikejMV8NL_tZ8ApTwq3pfbxEB8gujmEIwI3AzRU118MeweroLjo-sCm5kSNrzRNkzpSkZrRQ14EN27x9AyMSwfEpC_RL851fe7zPdBTHjkPdpZsnrxlLEoga_FAByV_XPfGt1QJQBU4JVukzKhfBD-c2KwHG9Lx8s5ZzxSpNRtgf8mEM28kcI99E9uWnDPl2S8jaFH4soSRXfZpPE4iSx4uOTqrwx8CI52Xocg7xlRONgJmLksG6rVuZTv8mk5JdO8v9w2TgQ452qU5OURk2DtJzj07gyV3APVUwmZ-LFanOtZWLz0G3JegM-UTuQiWGsM12YofsLr6wdcuquBss6JcR5hNjCnFgx-BVCPTsrgn3j84F3Z8eooUmlN86OBXss4zqH7iU_9SOmxlXqQC1l1qqMTZmVnXIn2jl_9zlPFwNsm71HxUrpOEIkBFBnjkU9JD-H1VJ_N7Fq0xvwbOv2e2WxZwg_MT8i3jFmpSDjQ0nrOQKmNmCBOIionGQCNbdEYK5lmWx3BMz6GL4MlVc_ik8zoZzA2w-yw6Xvfoqynam2XGxA8"},
        {"use":"sig","kty":"RSA","e":"AQAB","kid":"8f78ef3b-ae93-45a7-8f7a-5b6fee81dcb4","n":"w1SNwesCzz3qZbKf0V2qEKg_cE7hLdSLUs1pu9CIYLwcSG_APU1ZRUcXCqiSC5g71gpJB4ngW_l6D_1T4g1OYak32xo4UHzdWWIKJ8tvxPluvqY9vvD7uY_V1XqGRSzqY50gklCUg07HwxwWWFhELoJQBEJFTHBK1jQ4dX_4lq59rsc_yJNsrLQdf09NDVCUj6PEc02uxIO9gSAQZbZh_nYoV5CyHidFeg1ygMgQBq37Pv5HnC3NbpnNTn5c08tA6k5MnHQMD6zfppMNL6Mmq72tdbDzrBJx_rn-sCw_M1t5DD6WaG9W1SoackN6fUsh8Hi0PaEl9A9ENcUma2Irui2_kCMIzOtyOUbk9IDGce0TJyDUAAdmh2CaNf-zVa7F9UUH2_u_iwD2z2NgB4NwKqr8PMgaTVQJEOI6Dpu2cI1iY8RCXWX29EgfW77970IPJ9HTncoAS1bn1TfbG0HTxk0RV3QEfNdCVFoUbog94qafe0viMgzVvSinvBABRa__7i_1WubZ116cjzdYq4WzQB1A2jWBM5MCqHuXdmO5z53kU7KW7V1GiT8LyxUxTaMhYTVPooZmEDtlJ6xJvRDXm7nUB_gvKFrme7zK6_g-z2zFxvLM_1PdpsPdpsQm_By694FMf3bQbHW3WO8W91OmeCQEMOY8UyjNuXNhIFNLjc8"}
    ]
}

6. After completing the identity provider specific actions, run the following commands to remove unneeded files from the folder:

cd /server/<instance>/config/plugins/genericoidc
rm public_encryption.pem public_signing.pem

7. Sync key.pem and sign.pem to the other node, if environment is clustered.

# Check the current node number with d3status command
d3status
# If the current ACTIVE node is "node 1", run the command as is. If current ACTIVE node is "node 2", then change s2 to s1 in the command.
rsync key.pem sign.pem d3sync@s2:/server/<instance>/config/plugins/genericoidc/

4. Activating OIDC

This section covers the following

• Edit the OIDC configurations and enable the preferred settings
• Disable testmode and debugmode, and go into production (at this time, testing is only possible within the production environment.)

1. Edit /server/<instance>/config/plugins/genericoidc/genericoidc.cfg
Find testmode and debugmode and set both to 0

testmode = 0
debugmode = 0

2. Find templates_form, <provider>_jwt_privatekey and <provider>_jwt_signkey and replace deltagon from the paths with the instance name. Also, make sure privatekey and signkey configuration values match the .pem files in the server disk

templates_form = /server/<instance>/config/plugins/genericoidc/genericoidc_form.html
<provider>_jwt_privatekey = "/server/<instance>/config/plugins/genericoidc/key.pem"
<provider>_jwt_signkey = "/server/<instance>/config/plugins/genericoidc/sign.pem"

3. Choose which identifications are enabled by editing the banks row. Remove the identification methods you are not using

banks = ubilogin identityserver signicat telia

4. Edit <provider>_client_id, <provider>_client_secret for the chosen identification methods with the <client id> and <secret key> provided by the identity provider

<provider>_client_id = <client id>
<provider>_client_secret = <secret key>

5. Repeat for all chosen identification methods

<provider>_servicename = "Signicat OIDC"

proxy = proxyaddress:8080

5. Using OIDC in products

This section provides product-specific setup instructions. Follow the steps for the products where you want to enable strong authentication.