Advanced Authentication Flows

How to configure advanced authentication flows such as Http Basic Authentication, Login Forms, OAuth2, or SAML for your application

What is Application Authentication?

Many web applications rely on some sort of login mechanism to authenticate users. A full security scan of the application is in most cases only useful if the whole application (including all internal areas) is scanned. This article explains the different authentication methods to enable a scan of the whole web application:

  • Simple Authentication Methods
  • Scripting Authentication Flows
  • Advanced Authentication Methods

Simple Authentication Methods

HTTP Basic Authentication

HTTP Basic authentication (also known as .htaccess protection) is an authentication method where an authorisation header with a base64 encoded username and password is sent to the server. To use this login method, configure the username and password on the project preferences page in the section System Authentication.

Login Form Authentication

When you need to enter username and password in a HTML login form, also provide the information on the project preferences page. Therefore, use the section Application Authentication and also provide the URL, where the login form is located.image16

Parameter authentication

This setting allows you to configure HTTP headers, GET parameters, or (session) cookies for authentication.

If you would like to get more guidance on how to set up an API for scans, please check out this wiki article.

Screenshot 2019-02-15 at 16.35.57

Scripting Authentication Flows

It is possible to send a payload via Webhook or API which contains authentication data. This data will be used to configure your project before starting the scan. Please note that previous user credentials will be overwritten and the credentials will be stored for the next scan. To send a webhook request with payload data you may use the following request:

curl --data '{
"system_authentication": {
"basic_auth": {
"username": "username",
"password": "password"
}
},
"application_authentication": [
{
"username": "username",
"password": "password",
"url": "example.com/login"
}
],
"parameter_authentication": [
{
"type": "HEADER",
"key": "Authentication",
"value": "Bearer 12345678"
}
]
}' -X POST https://api.crashtest.cloud/webhook/SECRET_HASH

Manual Login Flow

Let's assume that you have an REST API at https://example.com/api/v1 which uses JWT Tokens for authentication. The token is generated by a POST request to /login with the username 'username' and the password 'password'.

$ curl --data '{"username": "username", "password": "password"}' -X POST https://example.com/api/v1/login

{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "ABCDEF",
"refresh_token": "ABCDEF",
"concurrent_sessions": 1,
"max_current_sessions": 40,
}

You may use this to generate a script which logs you in before starting the security scan. The token generated by the login request is then used for the security scan.

ACCESS_TOKEN=`curl --data '{"username": "username", "password": "password"}' -X POST https://example.com/api/v1/login | jq -r '.access_token`
curl --data "{
\"parameter_authentication\": [
{
\"type\": \"HEADER\",
\"key\": \"Authentication\",
\"value\": \"Bearer $ACCESS_TOKEN\"
}
]
}" -X POST https://api.crashtest.cloud/webhook/SECRET_HASH

Responses

The following json responses inform you about the result of the webhook call:

{"message": "webhook_scan_started", "data": {"scanId": SCAN_ID}}    # Success Case
{"message": "Scan is already running"} # Failure Case

Advanced Authentication Methods

For the advanced authentication methods, you need to implement the login using a custom script to retrieve the authentication information such as a session ID stored in a cookie or a JWT token.

SAML

SAML (Security Assertion Markup Language) is a XML Framework to exchange authentication and authorisation information. When using a SAML workflow, you need a script (CLIENT) to log in using your identity provider (IDP) and generate a session with the application that shall be scanned, the service provider (SP) and handover the credentials to the Crashtest Security Suite.

When writing your login script, you need to handle the following steps:

  1. CLIENT visits the IDP login page for the SP.
  2. CLIENT provides credentials to the IDP.
  3. IDP generates the SAML response and sends it to the CLIENT
  4. CLIENT posts the SAML response message to the SP
  5. SP authenticates the user based on the assertion and provides session information (e.g. session cookie)
  6. CLIENT sends a request to the Crashtest Security Suite to start a security scan including the session information 

To check out, how to send the information to the Crashtest Security Suite (step 6) have a look at the Using Webhooks article. You can also set the session manually for a project:

Screenshot 2019-02-15 at 16.35.57

OAuth 2

OAuth 2 (Open Authorisation) is a protocol, which offers a secure and standardised way for API authentication. With an OAuth 2.0 workflow, a client gets an access token from an authorisation server (AS) that is used to authenticate with the software that shall be scanned. For OAuth 2, there exist several different authentication flows that can be used. A simple one is the Resource Owner Password Credentials Grant flow. Create a login script (CLIENT) that does the following:

  1. CLIENT sends a requests to the AS to generate an access token
  2. AS sends an access token to the CLIENT
  3. CLIENT sends a request to the Crashtest Security Suite to start a security scan including the access token

To check out, how to send the information to the Crashtest Security Suite (step 6) have a look at the Using Webhooks article. You can also set the session manually for a project.

If you have any questions, for example on how to handle Single-Sign-On (SSO) authentication, please don't hesitate to contact us.