Single Sign-on External (SSOe)

Last Updated: May 5, 2025

This page describes the Single Sign-on External (SSOe) service. VA.gov applications teams can refer to this documentation for details about how to integrate with the SSOe authentication service and monitor its performance.

Overview

Single Sign-on External (SSOe) is an enterprise authentication solution for external users (Veterans, caregivers, etc.) to access VA.gov applications from outside the VA network.

SSOe provides federated single sign-on through integrated Credential Service Providers (CSPs), including Login.gov, ID.me, and DS Logon. VA.gov applications leveraging the SSOe service use the SAML integration pattern.

SSOe is operated by the VA Identity and Access Management (IAM) Team, which is the same team that operates the Master Person Index (MPI). SSOe and MPI are independent systems that interact with each other.

Monitoring

The following dashboards are available to monitor SSOe performance:

Banners

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

Impact

When SSOe is unavailable, the Identity Platform Team enables Sign-in Service (SiS) for all authentication attempts. Details of this policy are documented on GitHub.

When MPI is unavailable, users can sign in and SSOe provides a "CSP-only" payload to VA.gov with identity traits from the relevant CSP. During this time, users only have access to minimal logged-in functionality.

Environments

VA.gov environment	SSOe environment	SSOe URL	SSOe metadata URL
localhost (developers)	INT	https://int.eauth.va.gov/accessva/	https://int.eauth.va.gov/isam/saml/metadata/saml20idp
dev	INT	https://int.eauth.va.gov/accessva/	https://int.eauth.va.v/isam/saml/metadata/saml20idp
staging	SQA	https://sqa.eauth.va.gov/accessva/	https://sqa.eauth.va.gov/isam/saml/metadata/saml20idp
prod	prod	https://eauth.va.gov/accessva/	https://eauth.va.gov/isam/saml/metadata/saml20idp

Integration endpoints

VA.gov is integrated with SSOe via SAML. In SAML, all requests are mediated through the users' browser 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 the required configuration section.

VA.gov frontend code also uses 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, it extends the duration of the SSOe session to keep session expiry in sync between VA.gov and SSOe.

Required configuration

VA.gov fills the role of a SAML service provider (SP), or application. It initiates SAML requests and receives responses after authentication completes.

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

CODE

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 sends 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.

Support

Identity Platform Team

On the VA.gov side, the SSOe integration is owned by the Identity Platform Team. For assistance, reach out via the #identity-support Slack channel.

Production support

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

To request IAM Team support for issues on production servers, submit a ticket via ServiceNow (requires VA network access).

Non-production support

To request IAM Team support for non-production issues, use the JIRA service desk (requires PIV authentication).

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.