Skip to content

Securing MkDocs site with Keycloak

🔐 Configure Keycloak

1⃣ Create a Realm in Keycloak:

  • Log in to the Keycloak Admin Console at https://auth.virtomat.net/auth/admin
  • Use your admin credentials to log in.
  • In the left sidebar, click realms drop-down box and then Create Realm.
  • Enter a name for your realm (e.g., MkDocsRealm) and click Create.

2⃣ Create a Client

Note

In Keycloak, a client is an entity that interacts with Keycloak to authenticate users and request access tokens. Clients can represent different types of applications or services that require authentication and authorization. These clients can be web applications, mobile applications, APIs, or other services that need to secure resources.

  • Inside your newly created realm, navigate to Clients on the left sidebar.
  • Click on Create Client to add a new client.

General Settings

Field Value
Client Type OpenID Connect
Client ID mkdocs-client
  • Hit Next

Capability Config

Field Value Details
Client Authentication: On (to enable confidential access type)
Standard Flow Enabled: Yes
Implicit Flow Enabled: No
Direct Access Grants Enabled: No
Service Accounts Enabled: No
  • Hit Next

Login Settings

Field Value
Root URL: https://docs.virtomat.net
Home URL: https://docs.virtomat.net
Valid Redirect URIs: https://docs.virtomat.net/*
Valid Post Logout Redirect URIs: https://docs.virtomat.net/*
Web Origins: https://docs.virtomat.net
Admin URL: (optional, not needed)
  • Click Save
  • Navigate to the Credentials tab.
  • Note down the Secret.

Note

This will be used in the OAuth2-Proxy configuration.

3⃣ Create a Test User

  • In the left sidebar, click Users.
  • Click Add User and fill in the details
  • Click Save.
Field Value
Email verified: On
Username: john.doe@virtomat.net
Email: john.doe@virtomat.net
First Name: John
Last Name: Doe
  • Click on the Credentials tab.
  • Set a password for the user and make sure to disable the Temporary option.
  • Click Save.

Configure oauth2-proxy sidecar

Parameter Value Description
OAUTH2_PROXY_SKIP_PROVIDER_BUTTON true
OAUTH2_PROXY_HTTP_ADDRESS 0.0.0.0:4180
OAUTH2_PROXY_PROVIDER keycloak-oidc
OAUTH2_PROXY_CLIENT_ID mkdocs-client
OAUTH2_PROXY_CLIENT_SECRET mkdocs-client
OAUTH2_PROXY_COOKIE_SECRET secret
OAUTH2_PROXY_COOKIE_REFRESH 12h0m1s Refresh token/cookie every 12 hours
OAUTH2_PROXY_COOKIE_EXPIRE 168h0m1s One week
OAUTH2_PROXY_REDIRECT_URL https://docs.virtomat.net/oauth2/callback
OAUTH2_PROXY_OIDC_ISSUER_URL https://auth.virtomat.net/realms/MkDocsRealm
OAUTH2_PROXY_EMAIL_DOMAINS * eg. virtomat.io
OAUTH2_PROXY_CODE_CHALLENGE_METHOD S256
OAUTH2_PROXY_UPSTREAMS http://127.0.0.1:80
OAUTH2_PROXY_SESSION_COOKIE_MINIMAL false
OAUTH2_PROXY_SCOPES openid,profile,email
OAUTH2_PROXY_PASS_AUTHORIZATION_HEADER true
OAUTH2_PROXY_SESSION_STORE_TYPE redis
OAUTH2_PROXY_REDIS_CONNECTION_URL redis://redis-master:6379/0
OAUTH2_PROXY_REDIS_PASSWORD secret
INSECURE_OIDC_ALLOW_UNVERIFIED_EMAIL true ⚠ Could not yet map this field from google, so ignoring it for now