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
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.
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.*"
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, 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.
Okta Resource Owner Password Flow 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.*"
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.