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.
If an SSOe maintenance window is defined, a banner will be displayed on the VA.gov sign-in modal.
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.
SSOe Metadata URL
All non-prod environments connect to ID.me's sandbox environment.
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.
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.
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 Project Manager
IAM Dev Project Manager
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.
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.