3rd Party OAuth

Overview

Most modern applications are leveraging OAuth SaaS products to manage login credentials and security. Depending on the OAuth grant type your application uses, your setup will look different.

Important: Some Grant Types can not be automated and are not suitable for CI/CD. These grant types often require human intervention during the flow. Examples of this is when a user is asked to open an app/click a button to verify it is them as they are logging in. These flows are often referred to as “Authorization Code” and “Device Authorization” flows/grants. To run HawkScan with one of these Grant Types, you must manually get a JWT Token from the service and inject it at run time. View Inject Token for instructions.

The best grant types to automate with scripting are “Client Credential” and “Resource Owner” flows.

If you are using a 3rd party service we have not listed here, we recommend starting with Injecting a Token from the service for quick setup, then explore creating your own script as needed.

Auth0

Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications. They provide 4 OAuth grant types. How you set up Authenticated Scanning for HawkScan will depend on which grant type you use.

Client Credential Flow

Used for machine-to-machine communication. This is the best grant type for automation. We have example scripts on how to pull in credentials available for this flow.

Auth0 Client Credential script and Access Token Session Management script

If you use scripts, your stackhawk.yml will look like this:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test 
  host: http://localhost:3000
  autoPolicy: true
  autoInputVectors: true
  authentication:
    loggedInIndicator: "HTTP/[0-9]+.[0-9]+\\s+([2-3][0-9][0-9])"
    loggedOutIndicator: "HTTP/[0-9]+.[0-9]+\\s+(4[0-9][0-9])"
    # authn
    script:
      name: auth0-client-credentials.js
      parameters:
        issuer: https://${YOUR_DOMAIN}/oauth/token
        audience: ${YOUR_API_IDENTIFIER}
        grant_type: client_credentials
      credentials:
        client_id: ${YOUR_CLIENT_ID}
        client_secret: ${YOUR_CLIENT_SECRET}
    # authz
    sessionScript:
      name: access-token-session.js
    testPath:
      path: /api/private
      success: '.*200.*'
hawkAddOn:
  scripts:
    - name: auth0-client-credentials.js
      type: authentication
      path: scripts
      language: JAVASCRIPT
    - name: access-token-session.js
      type: session
      path: scripts
      language: JAVASCRIPT

Resource Owner Password Flow

Highly-trusted applications can use the Resource Owner Password Flow, which requests user provided credentials and typically use an interactive form. We have example scripts on how to pull in credentials available for this flow.

Auth0 Resource Owner Password Flow script and Access Token Session Management script

If you use a script, your stackhawk.yml will look like this:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test 
  host: http://localhost:3000
  autoPolicy: true
  autoInputVectors: true
  authentication:
    loggedInIndicator: "HTTP/[0-9]+.[0-9]+\\s+([2-3][0-9][0-9])"
    loggedOutIndicator: "HTTP/[0-9]+.[0-9]+\\s+(4[0-9][0-9])"
    # authn
    script:
      name: auth0-resource-owner-password.js
      parameters:
        issuer: https://${YOUR_DOMAIN}/oauth/token
        audience: ${YOUR_API_IDENTIFIER}
        grant_type: password
      credentials:
        client_id: ${YOUR_CLIENT_ID}
        client_secret: ${YOUR_CLIENT_SECRET}
        password: ${YOUR_PASSWORD}
    # authz
    sessionScript:
      name: access-token-session.js
    testPath:
      path: /api/private
      success: '.*200.*'
hawkAddOn:
  scripts:
    - name: auth0-resource-owner-password.js
      type: authentication
      path: scripts
      language: JAVASCRIPT
    - name: access-token-session.js
      type: session
      path: scripts
      language: JAVASCRIPT

Authorization Code Flow

This grant type requires users to confirm login credentials by manually clicking a button or giving a code sent to them.

This is not suitable for CI/CD. Running HawkScan locally and Injecting a Token from Auth0 at run time is your best option.

Implicit Flow with Form Post

The Implicit flow was a simplified OAuth flow previously recommended for native apps and JavaScript apps where the access token was returned immediately without an extra authorization code exchange step.

For Auth0 the user authenticates using one of the configured login options and may see a consent page listing the permissions Auth0 will give to the app

If a user is given an additional consent page, this is not suitable for CI/CD. Running HawkScan locally and Injecting a Token from Auth0 at run time is your best option.