SSOe
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
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 | ||
dev | INT | ||
staging | SQA | ||
prod | prod |
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"
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 | |
---|---|---|
Architect | Damien DeAntonio | |
Architect | Perry Vessels | |
IAM Project Manager | Jerry Wharton | |
IAM Dev Project Manager | Jeff Kindschuh | |
Project Manager | LeeAnne Branum |
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.
Help and feedback
Create an issue ticket to suggest changes to this page