Skip to content

SAML2 authentication

Jump to bottom
jbrown-xentity edited this page Apr 26, 2022 · 11 revisions

We use MAX.gov for authenticating agency staff on most of our data.gov applications and migrating to Login.gov.

SAML2 SSO primer

Here's a quick overview of how SAML2 single sign-on works. You might want to get into more detail here. If you need to debug one of the SAML2 libraries, you'll probably want to dig deeper into the SAML2 spec.

Data.gov acts as a Service Provider (SP) and MAX.gov/Login.gov is the Identity Provider (IdP).

SPs and IdPs need to know some basic information about each other which is provided in the form of XML metadata. This designates which endpoints to use and how to communicate with those endpoints (e.g. POST vs redirect).

When the SP needs to authenticate a user (subject), it makes an AuthnRequest to the IdP and requests specific attributes about the subject. The process is asynchronous, so when the SP initiates the request, it records some information about its request, and then when it receives the SAML response, it can record the session as authenticated.

Working with Login.gov

Login.gov has a self-service application dashboard where you can configure your SAML2 sandbox applications. Login.gov also supports OpenID Connect, but we are currently only using SAML2 authentication.

Before applications move from the sandbox to production, Assertion Encryption must be enabled. Contact the Login.gov team to promote your sandbox application to production.

Login.gov rotates their credentials every year in March. They usually send out notifications when it is time to update our config. For all of our SAML2 applications:

  • Update the IdP metadata
  • Update the IdP certificate (if applicable)
  • Rotate our SP certificate/key

Here listed login.gov SAML certificate rotation steps.

CKAN applications

For catalog and inventory, SAML2 authentication is provided by ckanext-saml2. There are a handful of places that need to be configured.

  • sp_config.py in ckanext-saml2 provides the SP configuration passed directly to pysaml2. This co
  • attributemaps provide a mapping

Certificates

In most cases, it is okay to use a self-signed certificate for the Service Provider since certificates are shared out-of-band through metadata.

Generate a new certificate and key with a 2-year expiration.

$ openssl req -newkey rsa:4096 -nodes -keyout key.pem -x509 -days 730 -out certificate.pem

The attributes of the certificate are not critical, but helpful to tell certificates apart.

Country Name (2 letter code) []:US
State or Province Name (full name) []:DC
Locality Name (eg, city) []:Washington
Organization Name (eg, company) []:GSA
Organizational Unit Name (eg, section) []:TTS
Common Name (eg, fully qualified host name) []:Data.gov (development)
Email Address []:datagovhelp@gsa.gov
Clone this wiki locally