How to enable OIDC login

Talkyard supports login with OpenID Connect (OIDC), including via Keycloak and Microsoft Azure AD. — Not yet well tested though, and the UI is a bit coarse; feedback is welcome.

This ought to work with Microsoft AD FS 2016 and later, which support OIDC — see: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios, the "Web App that signs in users" scenario, confidential client type. And see: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/development/ad-fs-openid-connect-oauth-concepts. (It'd be nice if we could write docs focusing on AD FS in particular, but we don't have access to any AD FS server.)

Here's how to enable OIDC login:

Prerequisites

• A Talkyard site, you have admin address.
• You know somewhat much about how OIDC works — you'll need to edit the OIDC JSON config in a step below.
• You have an Identity Provider service that supports OIDC that you have in mind to use.

The steps

1. As admin, go to the Admin Area, then to the Settings | Signup and Login tab.

2. Scroll down and tick the Custom OIDC or OAuth2 checkbox.

3. Click the Configure Identity Providers (IDPs) ... button (which appears once you've ticked the checkbox in the previous step).

4. Copy-paste the below JSON into the text field that should now be visible:

   {
     "id": 1,
     "protocol": "oidc",
     "alias": "keycloak_test_alias",
     "displayName": "Keycloak Test",
     "description": "OpenID Connect login test at keycloak.localhost:8113",
     "enabled": true,
     "trustVerifiedEmail": true,
     // Extra field for Azure AD — see the Azure AD section below.
     // "emailVerifiedDomains": "your.company.com",
     "syncMode": 1,
     "oauAuthorizationUrl": "http://keycloak.localhost:8113/auth/realms/ty_test_realm/protocol/openid-connect/auth",
     "oauAuthReqScope": "openid",
     "oauAccessTokenUrl": "http://keycloak.localhost:8113/auth/realms/ty_test_realm/protocol/openid-connect/token",
     "oauClientId": "ty_test_client",
     "oauClientSecret": "THE_SECRET_YOU_COPIED",
     "oauIssuer": "http://keycloak.localhost:8113/auth/realms/ty_test_realm",
     "oidcUserInfoUrl": "http://keycloak.localhost:8113/auth/realms/ty_test_realm/protocol/openid-connect/userinfo"
   }
   

5. Edit the JSON — you'll need to change almost all fields, especially the client ID and secret. And you need to know somewhat much about how OIDC works (to understand how to change the fields).

6. Save the settings.

7. Try to login, especailly as admin. You can open a new browser window in Chrome and Firefox, where're you will not be logged in, by clicking Ctrl+Shift+N and Ctrl+Shift+P respectively.

8. Optionally, enable OIDC Single Sign-On (SSO): Tick the Only your OIDC or OAuth2 checkbox.

9. If you lock yourself out: Go here: https://your talkyard site/-/admin-login and type your admin email address.

Keycloak

You use Keycloak? You can follow the steps above — in addition to that, here are step by step instructions for creating a Keycloak realm and connecting to Talkyard via OIDC:

https://github.com/debiki/talkyard/blob/master/images/keycloak/docker-compose-keycloak.yml

Azure AD

Microsoft Azure AD doesn't include any email_verified OIDC field; instead you can tell Talkyard that you've verified the email addresses by typing your email domain name in the emailVerifiedDomains value, as follows:

This: "emailVerifiedDomains": "your.company.com" makes Talkyard assume emails like someone@your.company.com have been verified — for example, if your organization hands out company email addresses to its employees only.

(Azure AD has its own non-standard OIDC email field: verified_primary_email, but the Azure docs does not make it clear if such email addresses have really been verified?)