This is a prototype for providing OpenID Connect-based
authentication and authorization services for all HMDA APIs and web applications
with identity requirements. This is currently implemented to support the
hmda-platform and
hmda-platform-ui projects,
though may support more in the future.
- Keycloak - Open-source identity management, with full OpenID Connect support.
- mod_auth_openidc - Open-source OpenID Connect authentication and authorization proxy.
This project has been fully Docker-ized. Docker is all you need to launch the full stack!
This project is intended to be run from hmda-platform's
Docker Compose setup, configured in hmda-platform/docker-compose.yml.
Please see the instructions in that repo for details on how to launch the system.
The Keycloak Docker image comes with the default "master" (admin) realm, and a "hmda" realm configured
for integrating with the oidc-client webapp. If you want to persist changes to "hmda", edit keycloak/import/hmda-realm.json.
This file is copied in during the Docker built, and applied to Keycloak via its
Import/Export functionality.
When experimenting with Keycloak setting, it is easier to use the admin UI to make changes. Below is an example how the automated "hmda" realm is setup.
- Login to Keycloak master realm by browsing to https://192.168.99.100:8443/auth/admin/.
- Create the HMDA realm.
- Mouse-over Master header.
- Click Add realm button.
- Add "hmda" to Name field.
- Click Create button.
- On the Email tab, fill in the following fields, and click Save:
- Host: mail_dev
- From: hmda-support@keycloak.local
- Add a hmda-api OpenID Connect client.
- Follow Clients link on left menu, and click Create.
- Set Client ID to hmda-api, and click Save.
- On the Settings tab, change the following options, and click Save:
- Standard Flow Enabled: OFF
- Implicit Flow Enabled: ON
- Direct Access Grant Enabled: OFF
- Valid Redirect URIs: http://192.168.99.100:7070
- NOTE: This is the URI for the test webapp. You will need to add additional for other apps.
- Web Origins: *
- On the Mappers tab, click Create, fill out the following, and Save.
- Name: Institutions
- Mapper Type: User Attribute
- User Attribute: institutions
- Token Claim Name: institutions
- Claim JSON Type: String
- Add to access token: ON
- Add Users
- Follow Users link on left menu.
- Click Add user.
- Fill in these fields, and click Save:
- Username, Email, First Name, Last Name
- User Enabled: ON
- Email Verified: ON
- On the Attributes tab, filling in the following, and click Add and Save.
- Key: institutions
- Value: 1,2
- On the Credentials tab:
- Fill in New Password and Password Confirmation.
- Set Temporary to OFF
- Click big red Reset Password, and then Change password buttons.
Once you've jumped through all of these setup hoops, you're ready to authenticate.
When integrating with your own app, the following are the most important configs. Defaults should work for the rest of the usual OIDC settings.
- Discovery Endpoint: https://192.168.99.100:8443/auth/realms/hmda/.well-known/openid-configuration
- Client ID: hmda-api
The following services are included in the Docker Compose config.
Keycloak acts as an OpenID Connect Identity Provider. It is available at:
Several of Keycloak's identity manangement workflows involve email confirmation. In order to test this locally, we've included the MailDev service. All emails sent by Keycloak can be viewed at:
WARNING: The Keycloak and Auth Proxy services are served over HTTPS with self-signed certificates. This can result in unexpected behavior, especially when dealing with CORS calls. To get around this, browse to each these services and accept the untrusted certs before you start using any of the other services.
- https://192.168.99.100 (Auth Proxy)
- https://192.168.99.100:8443 (Keycloak)
If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.
- Related projects