SSOe OAuth: Token Introspect Service and Secure Token Service (STS)

These services are necessary for VA.gov API service to verify the Access Token obtained on successul login through SSOe OAuth. This verification is required to authorize API requests from the client (currently the VA Mobile App).

Overview and Terminology

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.

This integration relates to the OAuth signin pattern provided by SSOe.

Introspect Service

This service provides partners implementing an OAuth client or resource server the ability to access the Introspect endpoint to validate the access token and obtain a full set of user traits.

STS Access Token Exchange (future)

This SSOi token service offers a capability where partners can be authorized to exchange an OAuth access token for a STS SAML token.

Integration Endpoints

For Introspect and UserInfo, the following endpoint pattern is used: https:// <env> .fed.eauth.va.gov:444/ <contextroot> /sps/oauth/oauth20/ <endpoint name>

We are configured to use ContextRoot=oauthe

We currently do not integrate with the userinfo endpoint.

The fully qualified endpoint URLs for the Introspect service are as follows:

• Introspect

  • iDEV: https://int.fed.eauth.va.gov:444/oauthe/sps/oauth/oauth20/introspect

  • SQA: https://sqa.fed.eauth.va.gov:444/oauthe/sps/oauth/oauth20/introspect

  • PREPROD: https://preprod.fed.eauth.va.gov:444/oauthe/sps/oauth/oauth20/introspect

  • PROD: https://fed.eauth.va.gov:444/oauthe/sps/oauth/oauth20/introspect

The Secure Token Service uses a different pattern.

The fully qualified endpoint URLs for the STS service are as follows:

• Secure Token Exchange:

  • iDEV: https://int.services.eauth.va.gov:9301/STS/ReguestSecurityToken

  • SQA: https://sqa.services.eauth.va.gov:9301/STS/ReguestSecurityToken

  • PREPROD: https://preprod.services.eauth.va.gov:9301/STS/ReguestSecurityToken

  • PROD: https://services.eauth.va.gov:9301/STS/ReguestSecurityToken

Required Configuration

PKI Certificates are required for access to the STS and Introspect endpoints.

• The current dev/staging certificate is named Mobile_App_API_Server_Lowers.cer.

• The current production certificate is named Mobile_App_API_Server.cer.

• The private key is stored in AWS Parameter Store under /dsva-vagov/vets-api/<env>/mobile_app_api_key

• The Public Key for the certificate has been added to the SSOe KeyStore.

• This cert was acquired from the VA PKI team. See here for how to get internal certs from the VA.

You should be able to test that the certificate is functioning by running some curl commands from a fwdproxy instance.

curl -v --cert /etc/pki/tls/certs/vagov-mobile-app-api-server-lowers.pem --key /etc/pki/tls/private/vagov-mobile-app.key https://int.fed.eauth.va.gov:444/oauthe/sps/oauth/oauth20/introspect
# NOTE: without the cert and key flags you should get an html page with an error indicating the client ssl failure
#       with the approved cert and key you should get a 400 bad request (we aren't providing valid request we are just checking ssl client certs and connectivity)

curl -v --cert /etc/pki/tls/certs/vagov-mobile-app-api-server-lowers.pem --key /etc/pki/tls/private/vagov-mobile-app.key https://int.services.eauth.va.gov:9301/STS/ReguestSecurityToken
# NOTE: without the cert and key we should see an error in the ssl handshake
#       with approved cert and key we should see a successful ssl handshake and a soap response

Known External Dependencies

n/a

Troubleshooting

n/a

Outage Status and Maintenance Windows

• IAM Status Page/Dashboard

Service Level Agreement

TBD

Escalation Procedure

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

Contacts

IAM Team:

VA Mobile team:

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.