Understanding API AuthProviders Configuration

You can configure the following categories of AuthProviders in your configuration file:

Client Certificate
Message Based
Transport (Authorization, Basic, Bearer, Digest, and NTLM)
Transport Custom Header

You can combine AuthProvider types as needed to access the network and the API definition file or endpoint. With the exception of Transport Custom Header, however, you can only use one AuthProvider from each category.

Client Certificate

The following table describes the Client Certificate category of AuthProviders that you can configure in the scan configuration file.

Type	Description
`TRANSPORT_CERTIFICATE`	Uses certificate configuration for authentication. `TRANSPORT_CERTIFICATE` requires the following parameter: `ClientCertificate` – Specifies the certificate information and includes the following parameters: `Data` – Provides the base-64 encoded `.pfx` certificate that is password protected. Tip:* You can use the following openssl command to obtain a text version of the certificate to use as the value for `Data`: openssl base64 -A -in d:\dump\cert.pfx -out d:\dump\cert.pfx.base64 `Password` – Specifies the password for the certificate. The following sample shows the syntax for these parameters. { "Type": "TRANSPORT_CERTIFICATE", "ClientCertificate": { "Data": "<64-base_encoded_certificate>", "Password": "<Password>" }, }

Type

Description

TRANSPORT_CERTIFICATE

Uses certificate configuration for authentication. TRANSPORT_CERTIFICATE requires the following parameter:

ClientCertificate – Specifies the certificate information and includes the following parameters:
- Data – Provides the base-64 encoded *.pfx certificate that is password protected.
  Tip: You can use the following openssl command to obtain a text version of the certificate to use as the value for Data:
```
openssl base64 -A -in d:\dump\cert.pfx 
-out d:\dump\cert.pfx.base64
```
- Password – Specifies the password for the certificate.

The following sample shows the syntax for these parameters.

{
     "Type": "TRANSPORT_CERTIFICATE",
     "ClientCertificate": {
          "Data": "<64-base_encoded_certificate>",
          "Password": "<Password>"
     },
}

Message Based

The following table describes the Message Based category of AuthProviders that you can configure in the scan configuration file.

Type	Description
`MESSAGE_CERTIFICATE`	Uses certificate configuration for authentication. `MESSAGE_CERTIFICATE` requires the following parameter: `ClientCertificate` – Specifies the certificate information for the client and includes the following parameters: `Data` – Provides the base-64 encoded `.pfx` certificate that is password protected. Tip:* You can use the following openssl command to obtain a text version of the certificate to use as the value for `Data`: openssl base64 -A -in d:\dump\cert.pfx -out d:\dump\cert.pfx.base64 `Password` – Specifies the password for the certificate. `ServerCertificate` – Specifies the certificate information for the server and includes the following parameter: `Data` – Provides the base-64 encoded `.pfx` certificate that is password protected. The following sample shows the syntax for these parameters. { "Type": "MESSAGE_CERTIFICATE", "ClientCertificate": { "Data": "<64-base_encoded_certificate>" "Password": "<Password>" }, "ServerCertificate": { "Data": "<64-base_encoded_certificate>*" } }
`MESSAGE_USERNAMETOKEN`	Uses a user name and token to authenticate to the SOAP service. `MESSAGE_USERNAMETOKEN` requires the following parameters: `Username` – Identifies the user name whose credentials are used to access the SOAP service. `Password` – Specifies the password for the user name. `UsernameToken` – Provides message-level authentication for SOAP and includes the following parameters: `Type` – Specifies the type of token. Options are `TEXT` and `HASH`. `TimeStamp` – Optionally, indicates when the `usernameToken` was created and when it expires. `TimeStamp` accepts `Created`, `Full`, or `None`. `IncludeNonce` – Indicates whether nonce is enabled. Nonce is required for `HASH` tokens because it helps the server to recalculate the hash and compare it to the data the client sent. Options are `true` or `false`. `WSAddressing` - Optionally, identifies the Web Services Addressing (WS-Addressing) schema version used by the SOAP service. Options are `NONE`, `WSA_0408`, and `WSA_0508`. `To` - Optionally, identifies the URL for the Web service host. Note: SOAP services may be exposed by way of a load balancer or reverse proxy. This configuration may prevent the sensor from getting the correct information for the internal Web service host name. The `To` URL override provides the correct address into WS Addressing. The following sample shows the syntax for these parameters. { "Type": "MESSAGE_USERNAMETOKEN", "Username": "<username>", "Password": "<password>", "UsernameToken": { "Type": "TEXT", "TimeStamp": "Created", "IncludeNonce": true }, "WSAddressing": { "Version": "WSA_0408", "To": "http://webservice/wcf/service.svc/CustomSoapEndpoint" } }

Type

Description

MESSAGE_CERTIFICATE

Uses certificate configuration for authentication. MESSAGE_CERTIFICATE requires the following parameter:

ClientCertificate – Specifies the certificate information for the client and includes the following parameters:
- Data – Provides the base-64 encoded *.pfx certificate that is password protected.
  Tip: You can use the following openssl command to obtain a text version of the certificate to use as the value for Data:
```
openssl base64 -A -in d:\dump\cert.pfx 
-out d:\dump\cert.pfx.base64
```
- Password – Specifies the password for the certificate.
ServerCertificate – Specifies the certificate information for the server and includes the following parameter:
- Data – Provides the base-64 encoded *.pfx certificate that is password protected.

The following sample shows the syntax for these parameters.

{
     "Type": "MESSAGE_CERTIFICATE",
     "ClientCertificate": {
            "Data": "<64-base_encoded_certificate>"
            "Password": "<Password>"
      },
      "ServerCertificate": {
            "Data": "<64-base_encoded_certificate>"
      }
}

MESSAGE_USERNAMETOKEN

Uses a user name and token to authenticate to the SOAP service. MESSAGE_USERNAMETOKEN requires the following parameters:

Username – Identifies the user name whose credentials are used to access the SOAP service.
Password – Specifies the password for the user name.
UsernameToken – Provides message-level authentication for SOAP and includes the following parameters:
- Type – Specifies the type of token. Options are TEXT and HASH.
- TimeStamp – Optionally, indicates when the usernameToken was created and when it expires. TimeStamp accepts Created, Full, or None.
- IncludeNonce – Indicates whether nonce is enabled. Nonce is required for HASH tokens because it helps the server to recalculate the hash and compare it to the data the client sent. Options are true or false.
- WSAddressing - Optionally, identifies the Web Services Addressing (WS-Addressing) schema version used by the SOAP service. Options are NONE, WSA_0408, and WSA_0508.
- To - Optionally, identifies the URL for the Web service host.
  
  Note: SOAP services may be exposed by way of a load balancer or reverse proxy. This configuration may prevent the sensor from getting the correct information for the internal Web service host name. The To URL override provides the correct address into WS Addressing.

The following sample shows the syntax for these parameters.

{
     "Type": "MESSAGE_USERNAMETOKEN",
     "Username": "<username>",
     "Password": "<password>",
     "UsernameToken": {
          "Type": "TEXT",
          "TimeStamp": "Created",
          "IncludeNonce": true
	 },
     "WSAddressing": {
          "Version": "WSA_0408",
          "To": "http://webservice/wcf/service.svc/CustomSoapEndpoint"
     }
}

Transport

The following table describes the Transport category of AuthProviders that you can configure in the scan configuration file.

Type	Description
`TRANSPORT_AUTHORIZATION`	Uses an authorization token. `TRANSPORT_AUTHORIZATION` includes the following parameters: `Name` – Indicates the token name. `Value` – Provides the token value. The following sample shows the syntax for these parameters. { "Type": "TRANSPORT_AUTHORIZATION", "Name": "<token_name>", "Value": "<token_value>", } `TRANSPORT_AUTHORIZATION` can also use the `Fetch` parameter. For more information, see Fetching a Token Value.
`TRANSPORT_BASIC`	Uses Basic configuration for authentication. `TRANSPORT_BASIC` requires the following parameters: `Username` – Identifies the user name whose credentials are used to access the API service. `Password` – Specifies the password for the user name. The following sample shows the syntax for these parameters. { "Type": "TRANSPORT_BASIC", "Username": "<UserName>", "Password": "<Password>", }
`TRANSPORT_BEARER`	Uses a bearer token configuration for authentication. `TRANSPORT_BEARER` requires the following parameter: `Value` – Provides the JSON token, generally from a response to a login form. `Header` – Optionally, identifies a custom header name. The following sample shows the syntax for this parameter. { "Type": "TRANSPORT_BEARER", "Value":"<token>" } `TRANSPORT_BEARER` can also use the `Fetch` parameter. For more information, see Fetching a Token Value.
`TRANSPORT_DIGEST`	Uses Digest authentication. `TRANSPORT_DIGEST` requires the following parameters: `Username` – Specifies the host name and username combination whose credentials are used to access the API service. `Password` – Specifies the password for the user name. The following sample shows the syntax for these parameters. { "Type": "TRANSPORT_DIGEST", "Username": "<host_name>\\<username>", "Password": "<password>", }
`TRANSPORT_NTLM`	Uses NTLM configuration for authentication. `TRANSPORT_NTLM` requires the following parameters: `Username` – Specifies the host name and username combination whose credentials are used to access the API service. `Password` – Specifies the password for the user name. The following sample shows the syntax for these parameters. { "Type": "TRANSPORT_NTLM", "Username": "<host_name>\\<username>", "Password": "<password>", }

Transport Custom

The following table describes the Transport Custom category of AuthProviders that you can configure in the scan configuration file.

Important! Fortify recommends that you do not configure more than one custom header using the same HTTP header name.

Type	Description
`TRANSPORT_CUSTOM_HEADER`	Using this type, you can configure multiple custom headers. `TRANSPORT_CUSTOM_HEADER` includes the following parameters: `Header` – Identifies the HTTP header name. The header must be unique and cannot be `Authorization`. `Name` - Optionally, specifies the header value prefix name. `Value` – Provides the header value. The following sample shows the syntax for these parameters. { "Type": "TRANSPORT_CUSTOM_HEADER", "Header": "<header_name>", "Name": "<prefix_header_name>", "Value": "<header_value>" } The following sample shows the syntax for configuring the "X-MyCustomAuth: CustomToken value" HTTP custom header with a custom authentication token. { "Type": "TRANSPORT_CUSTOM_HEADER", "Header": "X-MyCustomAuth", "Name": "CustomToken", "Value": "<token_value>" }

Type

Description

TRANSPORT_CUSTOM_HEADER

Using this type, you can configure multiple custom headers. TRANSPORT_CUSTOM_HEADER includes the following parameters:

Header – Identifies the HTTP header name. The header must be unique and cannot be Authorization.
Name - Optionally, specifies the header value prefix name.
Value – Provides the header value.

The following sample shows the syntax for these parameters.

{
     "Type": "TRANSPORT_CUSTOM_HEADER",
     "Header": "<header_name>", 
     "Name": "<prefix_header_name>", 
     "Value": "<header_value>"								 
}

The following sample shows the syntax for configuring the "X-MyCustomAuth: CustomToken value" HTTP custom header with a custom authentication token.

{
     "Type": "TRANSPORT_CUSTOM_HEADER",
     "Header": "X-MyCustomAuth",
     "Name": "CustomToken", 
     "Value": "<token_value>"								 
}

Fetching a Token Value

The TRANSPORT_AUTHORIZATION and TRANSPORT_BEARER AuthProviders can use the fetch parameter, which generates a response from a workflow macro and uses a regular expression to capture a token for use in applying state. Fetch accepts the following parameters:

Macro – Imports a base-64 encoded text capture of the macro. The macro must include a login web form and a response with a JSON web token.

Tip: You can open the macro file in a text editor, and then copy and paste the text into the Macro field.
Search – Allows use of a custom regular expression to fetch the token value. If a match to the regular expression occurs in the response, then the value is fetched and used as a bearer token. If the regular expression contains parentheses, then the value inside the parentheses will be extracted and used as a bearer token. Only the first value inside parentheses will be used.

Important! The Search parameter must follow the Macro parameter in your JSON file.
IsolatedState – Optionally, determines how the fetch macro playback is applied. When set to true, each scan thread runs its own fetch macro playback and applies the bearer token value to the thread. When set to false, only one fetch macro playback runs for all scan threads and the single shared bearer token value is applied to all threads. The default setting is false.

The following sample shows the syntax for these parameters.

{
     "Type": "TRANSPORT_BEARER",
     "Fetch": {
          "Macro": "<base-64_encoded_text>",
          "Search": "<regular_expression>",
          "IsolatedState": "true"	
	 },
}