Enterprise Single Sign-On (SSO)¶

OpenID Connect¶

GovReady-Q can be configured to use OpenID for authentication and authorization.

{
     "authorization_endpoint": "https://issuer.domain.name",
     "userinfo_signing_alg": "RS256",
     "jwks_uri": "https://issuer.domain.name/token",
     "token_endpoint": "https://issuer.domain.name/token",
     "userinfo_endpoint": "https://issuer.domain.name/userinfo",
     "scopes_supported": "openid profile",
     "client_id": "MyClientId",
     "client_secret": "MyClientSecret",
     "roles_map": {
         "admin": "GroupNameThatMapsToAdminUser",
         "normal": "GroupNameThatMapsToRegularUser"
     },
     "claims_map": {
         "email": "email",
         "groups": "groups",
         "first_name": "given_name",
         "last_name": "family_name",
         "username": "preferred_username"
     }
 }

Key	Description
authorization_endpoint	Issuer domain for your application
jwks_uri	JWKS Endpoint
token_endpoint	Token Endpoint
userinfo_endpoint	User Info endpoint
scopes_supported	Supported Scopes; should be a space delimited string ex: “openid profile”
userinfo_signing_alg	User Info signing Algorithm
client_id	OIDC app’s client id
client_secret	OIDC app’s client secret
roles_map	This map is meant to map OIDC User Groups to the application groups.
claims_map	This map is meant to map OIDC Claims to the application’s User model columns.

This object should be set under the oidc section of the environments.json.

Note: Deployment will slightly differ by setting this under OIDC.

Okta OpenID Connect¶

GovReady-Q can be configured to use Okta OpenID for authentication and authorization.

{
     "domain": "https://XXX.okta.com",
     "client_id": "MyClientId",
     "client_secret": "MyClientSecret",
     "roles_map": {
         "admin": "GroupNameThatMapsToAdminUser",
         "normal": "GroupNameThatMapsToRegularUser"
     },
     "claims_map": {
         "email": "email",
         "groups": "groups",
         "first_name": "given_name",
         "last_name": "family_name",
         "username": "preferred_username"
     }
 }

Key	Description
domain	Okta domain for your application
client_id	Okta app’s client id
client_secret	Okta app’s client secret
roles_map	This map is meant to map Okta User Groups to the application groups.
claims_map	This map is meant to map Okta Claims to the application’s User model columns.

This object should be set under the okta section of the environments.json.

Note: Deployment will slightly differ by setting this under OKTA.

Proxy Authentication Server¶

GovReady-Q can be deployed behind a reverse proxy that authenticates users and passes the authenticated user’s username and email address in HTTP headers. In this configuration:

The user points their browser to the reverse proxy authentication server.
The proxy authenticates users and proxies the request to GovReady-Q if and only if the user is authenticated and authorized to access GovReady-Q. The proxy passes the user’s username and email address in HTTP headers of the proxy’s choosing.
GovReady-Q will create a user account for a new user or treat the user as logged in as soon as the user requests a page. Therefore, there is no sign-up or log-in process within GovReady-Q when a proxy authentication server is used.
All other authentication methods to GovReady-Q are disabled when proxy authentication is enabled. Therefore you should ensure that the Django admin’s username matches the admin’s username as provided by the proxy server. Otherwise, you will lose access to the admin page. However, if there is a mismatch, you may disable proxy authentication, log in to the Django admin with your admin username and password, and change your admin username to match the username sent by the proxy server.
GovReady-Q must be run at a private address that cannot be accessed except through the proxy server.

To activate reverse proxy authentication, add the header names used by the proxy e.g.:

In Development set the trust-user-authentication-headers key following Developer Environment

{
  "trust-user-authentication-headers": {
    "username": "X-Authenticated-User-Username",
    "email": "X-Authenticated-User-Email"
  },
}

In Production see: Production Deployment

The proxy server must be configured to proxy to GovReady-Q’s private address. But the address settings in GovReady-Q must reflect the host and protocol used in the URL the end user uses to access GovReady-Q. They do not need to match the address that the proxy server uses to reach the GovReady-Q server.

Per the Django Documentation on authentication using REMOTE_USER, you must be sure that your proxy server always sets or strips the special username and email headers, including headers that normalize to the same Django key (in particular headers with underscores), from the client request and does not permit an end-user to submit a fake (or “spoofed”) header value.

We have an example reverse proxy authentication server, simple_iam_proxy_server, which can be used for debugging purposes. Some users have also reported success in using mitmproxy for setting HTTP headers.