Status as of April 7, 2020: VA.gov sign-in via SSOe is still in beta. Once fully launched, SSOe will become a hard dependency for sign-in to VA.gov.

Overview and Terminology

SSOe (SSO external) is a VA-operated authentication/identity provider service. It provides sign-in capability to a range of VA websites.

SSOe is operated by the VA Identity and Access Management (IAM) team - the same team that operates MVI. SSOe and MVI are independent systems (one might be up or down separately from the other) but they do interact with one another.

  • SSOe does not provide its own credentials; instead it federates out to VA's accepted credentials (currently ID.me, MHV, DSLogon)

  • The "external" indicates that this is geared towards external users accessing systems from off of the VA network; SSOi (internal) predominantly serves internal enterprise authentication use cases.

  • SSOe provides a variety of integration patterns; the two most common ones are via SAML reassertion (which is what VA.gov uses), and a "standard junction" where SSOe proxies all traffic for a consuming application and injects authentication headers on each request.

Monitoring

VA.gov Authentication Dashboard

IAM Status Page/Dashboard

Banners

If an SSOe maintenance window is defined, a banner will be displayed on the VA.gov sign-in modal.

Impact

When SSOe is unavailable, no users will be able to sign in to VA.gov.

SSOe is robust to MVI outages - users can authenticate and SSOe will provide a "CSP-only" payload to VA.gov consisting of identity traits from the relevant credential service provider. This would allow minimal logged-in functionality on VA.gov.

Environments

VA.gov environment

SSOe environment

SSOe URL

SSOe Metadata URL

localhost (developers)

INT

int.eauth.va.gov

https://int.eauth.va.gov/isam/saml/metadata/saml20idp

dev

INT

int.eauth.va.gov

https://int.eauth.va.gov/isam/saml/metadata/saml20idp

staging

SQA

sqa.eauth.va.gov

https://sqa.eauth.va.gov/isam/saml/metadata/saml20idp

prod

prod

eauth.va.gov

https://eauth.va.gov/isam/saml/metadata/saml20idp

All non-prod environments connect to ID.me's sandbox environment.

Integration Endpoints

VA.gov is integrated with SSOe via SAML. In SAML all requests are mediated through the users' browsers via redirects and hidden form POST requests. So at no point is there a direct network request from VA.gov to SSOe or vice versa. The endpoints to which requests are sent and at which responses are received are described below in Required Configuration.

VA.gov frontend code also makes us of a "keepalive" endpoint provided by SSOe. This endpoint is accessed via a browser fetch and accomplishes two things:

  • Allows frontend code to detect if an SSOe session is present.

  • If present, extends the duration of the SSOe session, to keep session expiry in sync between VA.gov and SSOe while a user is interacting with VA.gov.

Required Configuration

VA.gov fills the role of a SAML "Service Provider" (SP) aka application. It initiates SAML requests and receives responses after authentication completes.

The required SAML SP configuration is contained in vets-api settings.yml:

saml_ssoe:
  idp_metadata_file: "/srv/vets-api/src/config/ssoe_idp_sqa_metadata_isam.xml"
  cert_path: "/srv/vets-api/secret/vagov-ssoe-saml-staging-cert.pem"
  key_path: "/srv/vets-api/secret/vagov-ssoe-saml-staging-key.pem"
  callback_url: "https://staging-api.va.gov/v1/sessions/callback"
  issuer: "https://ssoe-sp-staging.va.gov"
  logout_url: "https://sqa.eauth.va.gov/pkmslogout?filename=vagov-logout.html"
CODE

  • idp_metadata_file: Path to SSOe's IDP metadata configuration. We configure this statically rather than fetching it from the above Metadata URLs dynamically. IAM announces metadata updates on their distribution list.

  • cert_path / key_path: Pointers to a signing/encryption keypair used to sign and encrypt/decrypt SAML requests and responses.

  • callback_url: The URL to which SSOe will send SAML responses.

  • issuer: The identifier for the VA.gov application, shows up as "entityID" in SAML requests.

  • logout_url: URL to which federated logout requests should be sent. Note this is a non-SAML logout mechanism.

Contacts

On the VA.gov side, the SSOe integration is owned by the VSP Identity team. Initial development was done by the CTO Support SSO project team.

The devops maintenance listserv (VETSGOV-DEVOPS-MAINTENANCE@listserv.gsa.gov) is confirmed as being subscribed to the SSOe notification list.

IAM Team:

Role

Name

E-mail

Architect

Damien DeAntonio

Damien.DeAntonio@va.gov

Architect

Perry Vessels

Perry.Vessels@va.gov

IAM Project Manager

Jerry Wharton

jerry.wharton@va.gov

IAM Dev Project Manager

Jeff Kindschuh

jeffrey.kindschuh@va.gov

Project Manager

LeeAnne Branum

LeeAnne.Branum@va.gov

Production Support:

IAM has a 24x7 on call rotation for production SSOe issues.

Per communications from IAM team:

If VA.gov notices a Prod issues and needs IAM support the best escalation path is to create a SNOW ticket and ask for it to be assigned to ‘AcS Tier 3’.

We were cautioned against attempting to use email for production support.

Non-Production Support

Email is a viable path for inquiries about non-production environments, but IAM also has a ticket tracking tool called LETT (IAM Lower Environment Trouble Tracker): https://dvagov.sharepoint.com/sites/OITEPMOIAM/Lists/IAM%20Environment%20Tasks/active.aspx where they prefer you file issues.