Skip to content

OAuth 2.0

OAuth 2.0 lets an API consumer get an access token on behalf of a user or system.

OAuth 2.0 Flows

OAuth 2.0 offers several flows suited for different types of applications. These flows are designed to ensure the security of user data, particularly Personal Identifiable Information (PII) and Protected Health Information (PHI). Some OAuth 2.0 flows, such as the Implicit Grant, are no longer recommended to secure applications.

Below are the recommended OAuth 2.0 flows for VA applications, along with examples of how these might be implemented in the context of VA services.

Authorization Code Flow

This is ideal for applications where the client (the application requesting access) can interact with the user's web browser and receive incoming requests from the web browser (like a web server). It's the recommended flow for most web applications.

Example: A web-based VA patient portal where Veterans can access their personal health records, make appointments, and communicate with healthcare providers. When Veterans log in, the application redirects them to the VA's authentication service. After login, the service redirects to the application with an authorization code, which the application then exchanges for an access token.

Authorization Code Flow with PKCE

Authorization Code Flow with PKCE (Proof Key for Code Exchange) adds a layer of security for mobile and public clients. It's especially useful for native applications and single-page apps.

Example: A mobile app Veterans use to manage their VA benefits and health services. The app starts the authorization process by generating a code verifier and a code challenge. This code challenge is sent to the VA's authentication service when the Veteran logs in. Upon successful login, the service returns an authorization code to the app, which exchanges it for an access token using the code verifier. This ensures the token exchange is secure, even if the initial authorization request was intercepted.

Client Credentials Grant

Best for machine-to-machine applications, where an application needs to access its own resources on the server. It’s less common in user-facing applications since the authentication is based on the client credentials rather than individual user credentials.

Example: An internal VA backend application that interacts with other backend services, like an application that accesses a VA database to retrieve non-personal data for reporting or analysis. The application authenticates itself to the VA API using its own credentials and receives an access token to access the required resources.

In each of these flows, the key aspect is that the access granted is limited to what is necessary for the application to function and no more, adhering to the principle of least privilege. This approach and robust implementation help protect the sensitive data VA applications handle.

Documenting OAuth 2.0

Documenting Authorization Code Flow

Below is an example of Authorization Code Flow for the fictitious ‘Rx’ API. The security scheme is called oAuth2AuthCode and the flow is authorizationCode. The authorizationUrl field contains the authorization endpoint that will be used to obtain the authorization code from the authorization server. The tokenUrl field contains the endpoint that is used by the client to obtain an access token. All supported scopes should be listed under scopes.

components: 
  securitySchemes:
    oAuth2AuthCode: # (1)
      type: oauth2
      description: This API uses OAuth 2 with the authorization code grant flow.
      flows:
        authorizationCode: # (2)
          authorizationUrl: https://api.va.gov/oauth2/authorization   
          tokenUrl: https://api.va.gov/oauth2/token
          scopes:
            prescription.read: Retrieve prescription data
...
  1. oAuth2AuthCode is the name of the security scheme.
  2. The type of flow set for this security scheme is Authorization Code Flow.

The oAuth2AuthCode security scheme is then used in the security section of the /prescriptions endpoint. This endpoint requires the scope prescription.read so it is listed below the security scheme.

paths:
  /prescriptions:
    get:
      tags:
        - prescription
      summary: Returns a list of a Veteran's prescriptions
      security: # (1)
        - oAuth2AuthCode:
          - prescription.read # (2)
...
  1. The oAuth2AuthCode security scheme is applied to this endpoint.
  2. This endpoint requires the prescription.read scope.

Documenting Client Credentials Grant

This example shows Client Credentials Grant being used in the ‘Rx’ API. The security scheme is called oAuth2ClientCredentials and the flow is clientCredentials. The tokenUrl field contains the endpoint that is used by the client to obtain an access token. All supported scopes should be listed under scopes.

components: 
  securitySchemes:
    oAuth2ClientCredentials: # (1)
      type: oauth2
      description: This API uses OAuth 2 with the client credentials grant flow.
      flows:
        clientCredentials: # (2)
          tokenUrl: https://api.va.gov/oauth2/token
          scopes:
            prescription.read: Retrieve prescription data 
...
  1. oAuth2ClientCredentials is the name of the security scheme.
  2. The type of flow set for this security scheme is Client Credentials Grant.

The oAuth2ClientCredentials security scheme is used in the security section of the /prescriptions endpoint. This endpoint requires the scope prescription.read so it is listed below the security scheme.

paths:
  /prescriptions:
    get:
      tags:
        - prescription
      summary: Returns a list of a Veteran's prescriptions
      security: # (1)
        - oAuth2ClientCredentials:
          - prescription.read # (2)
...
  1. The oAuth2ClientCredentials security scheme is applied to this endpoint.
  2. This endpoint requires the prescription.read scope.