Callout Authenticator rule

Authenticates the client by calling out to a REST service that validates a token and retrieves information about the user. This rule is an alternative to the other authentication policies.

Rule execution order

The Callout Authenticator rule executes after validation rules, such as the IP Restriction rule.

Authentication rule requirement

All Authentication rules require the Authorize by Role rule rule to authorize the caller correctly. For example, you can configure the Callout Authenticator rule to add the role “admin” to the client and then configure the Authorize By Role rule to authorize admin users.


Field	Description
When this rule should be applied	An expression that defines one or more conditions that must be true for the rule to execute. Default value: True Example: The expression `request.method == "POST"` causes the rule to execute only on `POST` requests.
Extract into $token	Required. Specifies the location to find the key in the request. If one of the given locations is not found, this rule passes the request through to the next rule.
Custom Header Keys	The names of the headers that can contain the key. If more than one header is given, they will all be checked. Click to add more custom header keys.
Key	The name of the custom header key. Default value: N/A Example: `X-Token`
Custom Query String Parameters	The names of the query parameters that can contain the key. If more than one name is provided, they will all be checked. Click to add more custom query string parameters.
Key	The name of the custom query string parameter. Default value: N/A Example: `token`
Authorization Header Type	If the key is in the Authorization header, this value is used as the “type” to check. Default value: `token` Example: N/A
Callout Request #1-4	Required. These sections describe the HTTP GET requests this rule should make to validate the token and get information about a user. Note: Client Request #2 through #4 are optional.
HTTP Method	Select one of the following HTTP methods: GET, POST, PUT, PATCH. Default value: `GET` Example: `POST`
Trust all certificates	Trust all certificates for expired or self-assigned certificates. Enabling this option bypasses the certificate validation process. The request will successfully proceed if the upstream URL provides an invalid certificate (expired or self-assigned) during the SSL handshake. Default status: Deselected Example: Selected
Request Body	The contents of the request that is sent to the client. Click to select a function from the dropdown menu. Default value: N/A Example: `{ "description" : "test message", "required" : "true" }`
Target Path	The location to store the result of the request in the working object, as a JSON-Path. CAUTION: If you leave this field blank, the URL is not called. Default value: N/A Example: `$user`
URL	The destination for the request. Default value: N/A Example: `https://idp.example.com/validate`
Query Parameters	The query parameters to add into the URL. Click to add more query parameters. Default value: N/A Example: `?src=encode`
Name	Name of the query parameter. Default value: N/A Example: `?src`
Value	Value for the query parameter. Default value: N/A Example: `encode`
Headers	The headers to include in the request. Click to add more headers. Default value: N/A Example: `x-content-type=application/json`
Name	Name of the header parameter. Default value: N/A Example: `x-content-type`
Value	Value for the header parameter. Default value: N/A Example: `application/json`
Response Handler	Specifies how the response must be handled. Default value: N/A Example: N/A
Extract User Info	Required. Specifies how to extract information about the user from the working object. Default value: N/A Example: N/A
User ID Expression	Required. An expression that returns a string to be used as the user ID. Default value: N/A Example: `$user.email`
Roles Expression	Required. An expression that returns the list of roles this user is in. Default value: N/A Example: `$user.groups.map(group => group.name)`
Time-To-Live in Seconds	Required. The number of seconds for which the token is valid before it is re-validated. Default value: `600` (10 minutes) Example: `700`

Important:

Although this rule supports different HTTP request methods, the endpoint must support the method configured in the rule. For example, if you select PUT in this rule, but the endpoint does not support the PUT method, the rule is not executed.

Troubleshooting

The Callout Authenticator rule logs information for debugging. You can retrieve errors from rule violations in the Snaplex logs. From these logs, you can determine why a request failed and find out how much time lapsed between the request and the failure.

Important:

Consult your CSM to troubleshoot rule violation errors. You must be a System Administrator to access the Snaplex JCC logs.