Login Start Free Trial Login Start Free Trial
 

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

Don’t see your 3rd Party Service?

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.

Your stackhawk.yml will look like this:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test 
  host: ${APP_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
    oauth:
      parameters:
        tokenEndpoint: https://${YOUR_DOMAIN}/oauth/token
        grantType: client_credentials
        additionalBodyParams:
          audience: ${YOUR_API_IDENTIFIER}
      credentials:
        clientId: ${YOUR_CLIENT_ID} #application credentials
        clientSecret: ${YOUR_CLIENT_SECRET} #application credentials
    # authz
    tokenExtraction:
      type: TOKEN_PATH
      value: access_token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer
    testPath:
      path: /api/private
      success: '.*200.*'
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.

Your stackhawk.yml will look like this:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test 
  host: ${APP_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
    oauth:
      parameters:
        tokenEndpoint: https://${YOUR_DOMAIN}/oauth/token
        grantType: password
        additionalBodyParams:
          audience: ${YOUR_API_IDENTIFIER}
      credentials:
        clientId: ${YOUR_CLIENT_ID} #application credentials
        clientSecret: ${YOUR_CLIENT_SECRET} #application credentials
        username: ${USERNAME} #user credentials
        password: ${PASSWORD} #user credentials
    # authz
    tokenExtraction:
      type: TOKEN_PATH
      value: access_token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer
    testPath:
      path: /api/private
      success: '.*200.*'
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.

Okta

Okta is a leading identity service provider with access management for a variety of use cases. When using Okta as an authentication service, your application would be leveraging one of their 7 grant types.

Client Credential Flow

The Client Credential Flow is designed for automated, machine-to-machine communication, which is ideal for scenarios like CI/CD pipelines. To configure Okta’s Client Credential Flow directly in your stackhawk.yml file:

  1. Obtain your Client ID and Client Secret from Okta.
  2. Set the ${SCOPE} value based on the permissions required by your application. Common scopes might include:
    • openid – to retrieve user identity
    • profile – to access user profile information
    • email – to access the user’s email address
    • Or any custom scope defined in Okta for specific permissions.

Here’s an example of how to configure stackhawk.yml for Okta’s Client Credential Flow:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: ${APP_HOST:http://localhost:9000}
  openApiConf:
    path: "/openapi.json"
  autoPolicy: true
  autoInputVectors: true
  authentication:
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*"
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" 
    oauth:
      parameters:
        tokenEndpoint: ${baseUrl}/v1/token
        grantType: client_credentials
        scope: ${SCOPE} 
      credentials:
        clientId: ${YOUR_CLIENT_ID} #application credentials
        clientSecret: ${YOUR_CLIENT_SECRET} #application credentials
    # authz
    tokenExtraction:
      type: TOKEN_PATH
      value: access_token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer
    testPath:
      path: /private
      success: '.*200.*'
  replacer:
    rules:
      - matchString: "User-Agent"
        replacement: "StackHawk"
        replaceOnly: false
Resource Owner Password Flow

Highly trusted applications can use the Resource Owner Password Flow to authenticate directly with a user’s credentials (username and password). This flow is ideal when the application itself needs access to user accounts, often through a form-based login.

To configure Okta’s Resource Owner Password Flow directly in your stackhawk.yml file:

  1. Obtain your Client ID and Client Secret from Okta.
  2. Add the ${USERNAME} and ${PASSWORD} for the account that HawkScan will use during the scan.
  3. Set the ${SCOPE} value based on the required permissions. Common scopes include:
  • openid – to retrieve user identity
  • profile – to access user profile information
  • email – to access the user’s email address
  • Or any custom scope defined in Okta to match your application’s needs.

Here’s an example of how to configure stackhawk.yml for Okta’s Resource Owner Password Flow:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: ${APP_HOST:http://localhost:9000}
  openApiConf:
    path: "/openapi.json"
  autoPolicy: true
  autoInputVectors: true
  authentication:
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*"
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" 
    oauth:
      parameters:
        tokenEndpoint: ${baseUrl}/v1/token
        grantType: password
        scope: ${SCOPE} 
      credentials:
        clientId: ${YOUR_CLIENT_ID} #application credentials
        clientSecret: ${YOUR_CLIENT_SECRET} #application credentials
        username: ${USERNAME} #user credentials
        password: ${PASSWORD} #user credentials
    # authz
    tokenExtraction:
      type: TOKEN_PATH
      value: access_token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer
    testPath:
      path: /private
      success: '.*200.*'
  replacer:
    rules:
      - matchString: "User-Agent"
        replacement: "StackHawk"
        replaceOnly: false
Authorization Code and Authorization Code with PKCE

These grant types require users to confirm login credentials by manually clicking a button or entering a code sent to them.

This is not suitable for CI/CD. Running HawkScan locally and Injecting a Token from Okta 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 Okta the user authenticates using one of the configured login options and may see a consent page listing the permissions Okta 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 Okta at run time is your best option.

Interaction Code Flow

The Interaction Code grant type is an OAuth 2.0 and OpenID Connect (OIDC) standard extension that is available in the Identity Engine to manage user interactions. The Interaction Code grant is typically used by native, SPA, and web client apps that want to interact directly with the user

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

SAML 2.0 Assertion Flow

The SAML 2.0 Assertion flow is intended for a client app that wants to use an existing trust relationship without a direct user approval step at the authorization server. It enables a client application to obtain an authorization from a valid, signed SAML assertion from the SAML Identity Provider.

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

KeyCloak

KeyCloak is a free and open source solution for identity and access management. It is based on standard protocols and provides support for OpenID Connect, OAuth 2.0, and SAML.

Client Credential Flow

Used for machine-to-machine communication. This is the best grant type for automation.

Your stackhawk.yml will look like this:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: ${APP_HOST:http://localhost:9000}
  openApiConf:
    path: "/openapi.json"
  autoPolicy: true
  autoInputVectors: true
  authentication:
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*"
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*"
    # authn
    oauth:
      parameters:
        tokenEndpoint: http://${YOUR_DOMAIN}/auth/realms/${REALM_NAME}/protocol/openid-connect/token
        grantType: client_credentials
      credentials:
        clientId: ${YOUR_CLIENT_ID} #application credentials
        clientSecret: ${YOUR_CLIENT_SECRET} #application credentials
    # authz
    tokenExtraction:
      type: TOKEN_PATH
      value: access_token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer
    testPath:
      path: /private
      success: '.*200.*'
Resource Owner Password Flow

Highly-trusted applications can use the Resource Owner Password Flow, which requests user provided credentials and typically uses an interactive form.

Your stackhawk.yml will look like this:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: ${APP_HOST:http://localhost:9000}
  openApiConf:
    path: "/openapi.json"
  autoPolicy: true
  autoInputVectors: true
  authentication:
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*"
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*"
    # authn
    oauth:
      name: keycloak-client-credentials.js
      parameters:
        tokenEndpoint: http://${YOUR_DOMAIN}/auth/realms/${REALM_NAME}/protocol/openid-connect/token
        grantType: client_credentials
      credentials:
        clientId: ${YOUR_CLIENT_ID} #application credentials
        clientSecret: ${YOUR_CLIENT_SECRET} #application credentials
        username: ${USERNAME} #user credentials
        password: ${PASSWORD} #user credentials
    # authz
    tokenExtraction:
      type: TOKEN_PATH
      value: access_token
    tokenAuthorization:
      type: HEADER
      value: Authorization
      tokenType: Bearer
    testPath:
      path: /private
      success: '.*200.*'
Authorization Code Flow

By default, Keycloak’s Javascript adapter uses Authorization Code Flow. With this flow the Keycloak server returns an authorization code, not an authentication token, to the application. The JavaScript adapter exchanges the code for an access token and a refresh token after the browser is redirected back to the application.

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

Implicit Flow and Device Authorization Grant

Keycloak also supports the Implicit flow where an access token is sent immediately after successful authentication with Keycloak. A Hybrid flow takes aspects of the default Authorization Code flow combining it with the Implicit flow.

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

Firebase

Firebase Authentication provides backend services, easy-to-use SDKs, and ready-made UI libraries to authenticate users to your app. It supports authentication using passwords, phone numbers, popular federated identity providers like Google, Facebook and Twitter, and more.

Firebase Authentication integrates tightly with other Firebase services, and it leverages industry standards like OAuth 2.0 and OpenID Connect, so it can be easily integrated with your custom backend.

Email And Password Based Authentication

Authenticate users with their email addresses and passwords. The Firebase Authentication SDK provides methods to create and manage users that use their email addresses and passwords to sign in. Firebase Authentication also handles sending password reset emails.

Token to Cookie Based Session Script

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

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: ${APP_HOST:http://localhost:9000}
  openApiConf:
    path: "/openapi.json"
  autoPolicy: true
  autoInputVectors: true
  authentication:
    loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*"
    loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*"
    # authn
    script:
      name: firebase-signInWithPassword-auth.js
      parameters:
        tokenEndpoint: https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?
      credentials:
        password: ${FIREBASE_USER_PASSWORD}
        additionalCreds:
          email: ${FIREBASE_USER_EMAIL}
          key: ${YOUR_FIREBASE_API_KEY}
    # authZ
    sessionScript:
      name: firebase-id-token-session.kts
    testPath:
      path: /private
      success: '.*200.*'
hawkAddOn:
    - name: firebase-id-token-session.kts
      language: KOTLIN
      type: authentication
      type: session
      path: scripts
  replacer:
    rules:
      - matchString: "User-Agent"
        replacement: "StackHawk"
        replaceOnly: false
Federated Identity Provider Integration

Authenticate users by integrating with federated identity providers. The Firebase Authentication SDK provides methods that allow users to sign in with their Google, Facebook, Twitter, and GitHub accounts.

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

Phone Number Authentication

Authenticate users by sending SMS messages to their phones.

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

Custom Auth System Integration

Connect your app’s existing sign-in system to the Firebase Authentication SDK and gain access to Firebase Realtime Database and other Firebase services.

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

Anonymous Authentication

Use features that require authentication without requiring users to sign in first by creating temporary anonymous accounts. If the user later chooses to sign up, you can upgrade the anonymous account to a regular account, so the user can continue where they left off.

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