Auth

Overview

Th AuthWorkEntryExecutor class is designed to provide a generic authentication mechanism that can be used as needed.

To use, an authentication executable must be defined on a Task. Typically, this task is not directly executed from a chain step. Instead, it is more likely linked to another task that requires authentication, a token, or both. For example, the following service executable has an authTask parameter that points to an instance of an authentication executable.

Authentication tasks are chained to perform authentication, token requests, or other authentication methods using multiple calls, if necessary. The response from one task can be forwarded to the next task in the chain. There is no limit to the number of tasks that can be chained.

Custom token

The SERVICE_CALL requires a token, which in turn requires authentication, so the tasks are chained as follows:

SERVICE_CALL -> REST_TOKEN -> AUTHENTICATE

The SERVICE_CALL calls an authTask REST_TOKEN.

The REST_TOKEN will invoke the restSecurityToken endpoint to get a token. However, this endpoint requires authentication before it can be invoked, so the task chains to AUTHENTICATE.

AUTHENTICATE does not have a specified chainedTask parameter, so it is the end of the authentication chain. This specifies the q:j_password, q:j_username, and URL to log into the application. The q: parameters are sent as request parameters in the HTTP call. An expectedResponse (303) parameter is also defined that is checked after the call. Multiple responses can be specified as a comma-delimited list. For example, 302,303. The task will fail if the response code does not match the expectedResponse defined value.

The AUTHENTICATE call will forward the set-cookie response headers to the REST_TOKEN task for its token request. For example, the response headers for JSESSIONID.

The REST_TOKEN executable will use the cookies from the call to AUTHENTICATE to make its call to restSecurityToken. Its executable Code Block defines the additional values for its token request.

The code block uses forwardedHeader and lifeTimeSeconds. In this example, the header value is specified using variable syntax {h:Security-Token}, which means it will be extracted from the Security-Token response header that resulted from the call to the restSecurityToken endpoint. For more information about these parameters, see Code blocks.

OAuth token

If the service requires an OAuth token, which would typically be the case in a SaaS environment, a single authTask should work if a client credentials or password grant is used. This DUMMY_TASK below invokes a service at http://localhost:9090, and it requires an OAuth token, which the AUTH_LOGIN authentication task provides.

As shown below, the AUTH_LOGIN task calls http://localhost:1234/oauthToken and specifies the base64 encoded basic credentials in the h:Authorization parameter.

The executable for this needs to specify the request body and other details in its code blocks.

In the example above, the requestBody specifies a grant type of client_credentials, which is a typical two-legged OAuth flow. The client id and secret for this call will be supplied in the authorization parameter on the Task.

The second code block defines the two forwardedHeader values, Authorization and Cache-Control, which are to be extracted from the access_token JSON response body and cache-control response header, respectively. The headers are then forwarded to their respective request headers to the original SERVICE_CALL task. The lifetimeSeconds is set to the expires_in value from the token call’s response body.

Parameters

The following parameters are supported:

ParameterDescription
chainedTask

Specify the task to chain to in order to invoke another task as part of the authentication process. The chained task will be invoked before this task, and the set-cookie headers from the chained task will be set in the request headers of this task before it invokes its service.

If a chainedTask parameter is not specified, this task will be the final authentication task.

expectedResponses

Comma-delimited list of expected HTTP response codes. The following are the possible values:

  • 200 — OK
  • 201 — no content
  • 302 or 303 — redirect response

If the expectedResponses parameter is specified, it must include all expected response codes, including 200, if applicable.

Default: 200

urlDefines the complete URL for the authentication task.

Mandatory: No
h:<header>Specifies the request headers.

Header names are usually case-insensitive. For example, h:Content-Type and h:content-type are equivalent.
q:<request parameter>Specifies the request parameters.

For example, to send the user ID and password on a j_security_check login, specify q:j_username and q:j_password with the values. The query parameters would be added to the HTTP call, similar to when done manually using the following: http://server:port/j_security_check?j_username=SYSUSER&j_password=sysuser00.

Code blocks

The auth executable accepts additional configuration settings in its code blocks. One or more code blocks can be used to logically group or describe the settings, or everything can be defined in a single code block. It does not affect the functionality of the auth executable. A setting has the form “name = value”, where name can be one of the following:

ParameterDescription
requestBody

Defines the body of the request.

For example, an OAuth token request would contain a grant_type parameter. An example of a password grant is grant_type=password&username=SYSUSER&password=sysuser00&scope=dev.

Variables can be injected into the value by enclosing the variable name in {}. See Variables for more information.

forwardedHeader

Specifies the HTTP request header that will be set on the call that the original service makes.


Multiple forwardedHeaders can be specified in a single code block or over multiple code blocks.


For example, if a task is a token request, it most likely expects the token to be a Bearer token in its Authorization header. In such cases, forwardedHeader = Authorization: Bearer {j:$.access_token} can be specified. The value between curly brackets is a JSON path expression defined as a variable. See Variables for more information.

lifeTimeSecondsNumber of seconds that the token will be considered valid. A new chained authentication request will be made when this expires. This value can be set to a hard-coded value as in this example, or it could be extracted from the response body using JSON path syntax. For example {j:$.expires_in} will extract the expires_in field from the JSON response.

Variables

The value of a setting can be explicit, such as requestBody = grant_type=client_credentials, or it could include {…} variables, such as requestBody = grant_type={#grantType}.

The {#grantType} is a parameter variable described in Common executable features. Any task parameter can be injected into these values by prefixing the parameter name with # and surrounding it with {}. In this example, the {#grantType} string will be replaced by the value for the grantType parameter at runtime.

Internal variables can also be added, although these are mostly migration-specific and not useful in an authentication context.

Any response header or portion of a response body can also be injected. Some examples are:

  • forwardedHeader = Authorization: Bearer {j:$.access_token}
  • forwardedHeader = Cache-Control: {h:cache-control}
  • forwardedHeader = OUAF-Security-Token: {h:OUAF-Security-Token}
  • lifetimeSeconds = {j:$.expires_in}

The h: prefix references a response header.

The j: prefix references a JSON response body. The j: should be followed by a JSON path expression to extract the required value from the JSON response.