HMDA Platform Auth

Archived

Active development moved to https://github.com/cfpb/hmda-platform/tree/master/auth

Former README

This project provides OpenID Connect-based authentication and authorization services for all HMDA APIs and web applications with identity requirements. This currently includes 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 are the steps used when creating the "hmda" realm and its "hmda-api" client.

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. Select the Add realm button.
   3. Add "hmda" to Name field.
   4. Select the Create button.
   5. On the Login tab, set the following and select Save:
      1. User registration: ON
      2. Email as username: ON
      3. Edit username: OFF
      4. Forgot password: ON
      5. Remember Me: OFF
      6. Verify email: ON
      7. Login with email: ON
      8. Require ssl: all requests
   6. On the Email tab, set following and click Save:
      1. Host: mail_dev
      2. From: noreply@cfpb.gov
   7. On the Themes tab, set following and select Save:
      1. Login Theme: hmda
      2. Email Theme: hmda
   8. On the Tokens tab, set the following and select Save:
      1. Login action timeout: 60 (Minutes)
      2. User-Initiated Action Lifespan: 60 (Minutes)
   9. On the Security Defenses / Brute Force Detection tab, set the following and select Save:
      1. Enabled: ON
      2. Permanent Lockout: ON
3. Configure the realm's Authentication settings:
   1. Select the Authentication link on the left menu:
   2. On the Flows tab:
      1. Select Registration from the dropdown.
      2. Select the Copy button.
      3. Enter "registration - hmda" in the New Name field, and select OK.
      4. Select Add Execution action for Registration - Hmda Registration Form.
      5. Select Institution Validation for Provider, and select Save.
      6. Select Delete action for Recaptcha.
      7. Select REQUIRED for Institution Validation.
   3. On the Bindings tab, set the following and select Save:
      1. Set Registration Flow to registration - hmda.
   4. On the Password Policy tab, set these policies and select Save:
      1. Expire Password: 90
      2. Minimum Length: 12
      3. Not Recently Used: 10
      4. Uppercase Characters: 1 (Default)
      5. Lowercase Characters: 1 (Default)
      6. Digits: 1 (Default)
      7. Special Characters: 1 (Defaul)
      8. Not Username (No value to set here)
      9. Hashing Iterations: 27500 (Default)
4. Add a hmda-api OpenID Connect client.
   1. Select the Clients link on left menu, and select Create.
   2. On the Add Client screen, set the following and Save:
      • Client ID: hmda-api
   3. On the Settings tab, change the following and Save:
      • Standard Flow Enabled: OFF
      • Implicit Flow Enabled: ON
      • Direct Access Grant Enabled: OFF
      • Valid Redirect URIs:
        • https://192.168.99.100
        • https://192.168.99.100/oidc-callback
        • https://192.168.99.100/silent_renew.html
      • Web Origins: *
   4. On the Mappers tab, click Create, set the following, and Save:
      • Name: Institutions
      • Consent Required: OFF
      • Mapper Type: User Attribute
      • User Attribute: institutions
      • Token Claim Name: institutions
      • Claim JSON Type: String
      • Add to ID token: ON
      • Add to access token: ON
      • Add to userinfo: ON
      • Multivalued: OFF

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/

Auth Proxy

Secure API Gateway protecting HMDA APIs with auth requirements

• https://192.168.99.100:4443 - Auth Proxy Status
• https://192.168.99.100:4443/hmda/ - Protected HMDA Filing API

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:

• https://192.168.99.100:8443/mail/

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