Web Protection

Web Protection API uses OAuth 2 with Proof Key for Code Exchange (PKCE) for authentication. PKCE is an additional layer in the OAuth 2.0 Authorization Code Flow and provides better security for use in applications that can not store a client secret, such as single-page applications.

Full Web Protection API documentation is available at <Need to add URL>.

With PKCE, a code verifier and a code challenge are used when exchanging the authorization code for an access token, replacing the client secret used in OAuth1. 

See https://www.rfc-editor.org/rfc/rfc7636  for more information on PKCE.

The following are the authentication steps to get an access token which can then be used to call Web Protection API endpoints. Examples shown use the Postman API client. See https://www.postman.com

• Create the three parameters required in the initial authorization call to Web Protection that are self-generated: state, code_verifier and code_challenge:

• state: This is a random 40 character string created by you. It can be generated using an online tool such as http://www.unit-conversion.info/texttools/random-string-generator.
  
  For example: 123xkYFwY2qiG7dEb7Cq1z74QNFnmioh5aNcOrRH

• code_verifier: This is a random 128 character string created by you. It can be generated using an online tool such as http://www.unit-conversion.info/texttools/random-string-generator.
  
  For example: qJainvnXruMEcECKUTf1Zt4ZnxDN0cw6MV8pXzK1EQ5Bze6YOyTyMTuQ3sWm6t0CTpWlNZGHZxvVwz23fsAfakVigCVd6jFswK9nbeQ4EuLPvdGvnw5JDmrv2esFu75S

• code_challenge: This is a SHA-256 encoded parameter generated by you using the code_verifier created in the previous step. To do this, submit the code_verifier in an online tool such as https://tonyxu-io.github.io/pkce-generator.
  
  For example: 9tanTO36l9r-gHOKK6fa_0TzCLMmMA5989OVxEugerQ

• Make the oauth2 call to Web Protection to request an access token.
  
  Format: GET https://your-API-URL.Web Protectioncloud.com:8443/restapi/oauth/authorize
  
  The following GET and Basic Auth parameters are required to make the call:
  
  

  Parameter	Description	Example
  response_type	This is always "code".	code
  client_id	This is always "2".	2
  code_challenge	An SHA-256 encoded code_verifier (see Step 1).	9tanTO36l9r-gHOKK6fa_0TzCLMmMA5989OVxEugerQ
  code_challenge_method	S256	S256
  state	This is a self-generated random 40 character string that you create (see Step 1).	123xkYFwY2qiG7dEb7Cq1z74QNFnmioh5aNcOrRH
  code_verifier	A self generated 128 character string that you create (see Step 1).	qJainvnXruMEcECKUTf1Zt4ZnxDN0cw6MV8pXzK1EQ5   Bze6YOyTyMTuQ3sWm6t0CTpWlNZGHZxvVwz23fsAf   akVigCVd6jFswK9nbeQ4EuLPvdGvnw5JDmrv2esFu75S
  redirect_uri	The exact Web Protection URL that you are calling to, with port number, followed by   /restapi/oauth/callback    See Web Protection API URLs to determine your API URL.	https://your-API-URL.Web   Protectioncloud.com:8443/restapi/oauth/callback  See Web Protection API URLs to determine your API URL.
  code (optional)	This parameter is only required if 2FA is enabled on your Web Protection. It is the 6 digit code from your authenticator app.	384 519

  
  The following Basic Auth parameters must also be passed:
  
  

  Parameter	Description	Example
  Username	Your Web Protection username	admin@yourcompany.com
  Password	Your Web Protection password	6*4iw48Xkg3M

  
  Using the examples above, the complete request looks as follows in Postman:
  
  
• An access token is returned, which displays in Postman as follows below. Select and copy the access token.

• Once copied, this can then be used for authorization when calling other endpoints. In Postman, this is specified in the Authorization tab as shown below. The token type is Bearer Token.