HMDA Platform Auth

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.

Technologies

• Keycloak - Open-source identity management, with full OpenID Connect support.
• mod_auth_openidc - Open-source OpenID Connect authentication and authorization proxy.

Dependencies

This project has been fully Docker-ized. Docker is all you need to launch the full stack!

• Docker
• Docker Compose

Installation

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.

Config

Automated

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.

Manual

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.

1. Login to Keycloak master realm by browsing to https://192.168.99.100:8443/auth/admin/.
2. Create the HMDA realm.
   1. Mouse-over Master header.
   2. Click Add realm button.
   3. Add "hmda" to Name field.
   4. Click Create button.
   5. On the Email tab, fill in the following fields, and click Save:
      1. Host: mail_dev
      2. From: hmda-support@keycloak.local
3. Add a hmda-api OpenID Connect client.
   1. Follow Clients link on left menu, and click Create.
   2. Set Client ID to hmda-api, and click Save.
   3. On the Settings tab, change the following options, and click Save:
      1. Standard Flow Enabled: OFF
      2. Implicit Flow Enabled: ON
      3. Direct Access Grant Enabled: OFF
      4. 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.
      5. Web Origins: *
   4. On the Mappers tab, click Create, fill out the following, and Save.
      1. Name: Institutions
      2. Mapper Type: User Attribute
      3. User Attribute: institutions
      4. Token Claim Name: institutions
      5. Claim JSON Type: String
      6. Add to access token: ON
4. Add Users
   1. Follow Users link on left menu.
   2. Click Add user.
   3. Fill in these fields, and click Save:
      1. Username, Email, First Name, Last Name
      2. User Enabled: ON
      3. Email Verified: ON
   4. On the Attributes tab, filling in the following, and click Add and Save.
      1. Key: institutions
      2. Value: 1,2
   5. On the Credentials tab:
      1. Fill in New Password and Password Confirmation.
      2. Set Temporary to OFF
      3. Click big red Reset Password, and then Change password buttons.

Use it!

Once you've jumped through all of these setup hoops, you're ready to authenticate.

Integrate your own app

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

Services

The following services are included in the Docker Compose config.

Keycloak

Keycloak acts as an OpenID Connect Identity Provider. It is available at:

• https://192.168.99.100:8443/auth/

Email

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:

• http://192.168.99.100:1080/

Self-signed Certs

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)

Getting help

If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.

Getting involved

CONTRIBUTING

Open source licensing info

1. TERMS
2. LICENSE
3. CFPB Source Code Policy

Credits and references

1. Related projects

• https://github.com/cfpb/hmda-platform
• https://github.com/cfpb/hmda-platform-ui