User documentation on pam-keycloak-oidc

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started#

Download the precompiled binary file for the corresponding operating system from Github, save it to the Linux server, e.g., as /opt/pam-keycloak-oidc/pam-keycloak-oidc. In case the platform is not amd64 or arm64, compile this golang application for the appropriate architecture.

chmod +x /opt/pam-keycloak-oidc/pam-keycloak-oidc

Create the configuration file at the same directory, with the same filename as the binary plus a .tml file extension. e.g.:
```
vim /opt/pam-keycloak-oidc/pam-keycloak-oidc.tml
```
Set parameters at the configuration file, refering to the config for specific IdP server and described details.

Configuration file

Mon, 01 Jan 0001 00:00:00 +0000

Configuration file#

Example:

# name of the dedicated OIDC client at Keycloak
client-id="demo-pam"
# the secret of the dedicated client
client-secret="561319ba-700b-400a-8000-5ab5cd4ef3ab"
# special callback address for no callback scenario
redirect-url="urn:ietf:wg:oauth:2.0:oob"
# OAuth2 scope to be requested, which contains the role information of a user
scope="pam_roles"
# name of the role to be matched, only Keycloak users who is assigned with this role could be accepted
vpn-user-role="demo-pam-authentication"
# retrieve from the meta-data at https://keycloak.example.com/auth/realms/demo-pam/.well-known/openid-configuration
endpoint-auth-url="https://keycloak.example.com/auth/realms/demo-pam/protocol/openid-connect/auth"
endpoint-token-url="https://keycloak.example.com/auth/realms/demo-pam/protocol/openid-connect/token"
# 1:1 copy, to `fmt` substituion is required
username-format="%s"
# to be the same as the particular Keycloak client
access-token-signing-method="RS256"
# a key for XOR masking. treat it as a top secret
xor-key="scmi"
# use only otp code for auth
otp-only=false

Development environment

Mon, 01 Jan 0001 00:00:00 +0000

Development environment#

Documentation#

The outline of this documentation is too complex to fit into a single README.md.

Hugo is used to render the static website hosted at Github Pages, and Hugo Book is chosen as the theme. A Github Actions workflow is configured to automatically build and publish the changes merged to the main branch.

Please follow the instructions to setup the local development environment.

Mon, 01 Jan 0001 00:00:00 +0000

Keycloak 12.x#

Create a new Role at Keycloak, e.g. demo-pam-authentication. (Assuming the server is at https://keycloak.example.com)
Create a new Client Scope, e.g. pam_roles:
- Protocol: openid-connect
- Display On Consent Screen: OFF
- Include in Token Scope: ON
- Mapper:
  - Name: e.g. pam roles
  - Mapper Type: User Realm Role
  - Multivalued: ON
  - Token Claim Name: pam_roles (the name of the Client Scope)
  - Claim JSON Type: String
  - Add to ID token: OFF
  - Add to access token: ON
  - Add to userinfo: OFF
- Scope:
  - Effective Roles: demo-pam-authentication (the name of the Role)
Create a new Keycloak Client: