ApiAuthenticationConfig

Configure authentication for API requests.

Tree gateway uses passportjs to handle authentication.

The Authentication configuration object must be included in the API config and supports the following properties:

Property	Type	Description	Required
strategy	MiddlewareConfig	The middleware that construct the strategy for authentication.	false
group	string[]	A list of group names that should be authenticated by this authenticator. If not provided, everything will be authenticated.	false
disableStats	boolean	If true, disable the statistical data recording for authentication events.	false
statsConfig	StatsConfig	Configurations for the authentication stats.	false
use	string	Import a configuration from gateway config session	false

You must provide one of strategyor useproperty.

Pre defined Authentications

Tree gateway provides some middlewares already installed for most common authentication strategies:

• Basic
• JWT
• Local

It is possible to use one of the pre defined authentication strategies, or to define your own, using a middleware.

Example (Custom):

{
    "authentication": [{
        "strategy": {
            "name": "myJwtStrategy",
            "options": {
                "secret": "secret"
            }
        }
    }]
}

or

{
    "authentication": [{
        "use": "my-custom-strategy"
    }]
}

The custom example above will use a middleware named myJwtStrategy, that must be installed to perform the authentication. The object configurated will be passed as parameter to the middleware initialization function:

{
    "secret": "secret"
}

Note that you can pass anything you need here.

Basic

Configure a authentication to use the http basic strategy.

It support the following option properties:

Property	Type	Description	Required
verify	MiddlewareConfig	A middleware that check the credentials and call done with the authenticated user object.	true

The verify middleware should receive the following parameters:

• userid: The username.
• password: The password.
• done: is a passport error first callback accepting arguments done(error, user, info)

Example:

{
    "authentication": [{
        "strategy": {
            "name": "basic",
            "options": {
                "verify": {
                    "name": "verifyBasicUser"
                }
            }
        },
        "group": ["Group1"]        
    }]
}

Local

Configure a authentication to use the local strategy.

It support the following properties:

Property	Type	Description	Required
verify	MiddlewareConfig	A middleware that check the credentials and call done with the authenticated user object.	true
usernameField	string	The name of the form field that informs the username. Defaults to 'username'	false
passwordField	string	The name of the form field that informs the password. Defaults to 'password'	false

The verify middleware should receive the following parameters:

• userid: The username.
• password: The password.
• done: is a passport error first callback accepting arguments done(error, user, info)

Example:

{
    "authentication": [{
        "strategy": {
            "name": "local", 
            "options": {
                "usernameField": "userid",
                "passwordField": "passwd",
                "verify": {
                    "name": "verifyBasicUser"
                }
            }
        }    
    }]
}

JWT

Configure a authentication to use the JWT strategy.

It support the following properties:

Property	Type	Description	Required
secretOrKey	string	Is a string containing the secret (symmetric) or PEM-encoded public key (asymmetric) for verifying the token's signature.	true
extractFrom	JWTRequestExtractor	Defines how the JWT token will be extracted from request.	false
issuer	string	If defined the token issuer (iss) will be verified against this value.	false
audience	string	If defined, the token audience (aud) will be verified against this value.	false
algorithms	string[]	List of strings with the names of the allowed algorithms. For instance, ["HS256", "HS384"].	false
ignoreExpiration	boolean	If true do not validate the expiration of the token.	false
verify	MiddlewareConfig	A middleware that check the credentials and call done with the authenticated user object.	false

The verify middleware should receive the following parameters:

• request: The user request.
• jwt_payload: Is an object literal containing the decoded JWT payload.
• done: Is a passport error first callback accepting arguments done(error, user, info)

JWTRequestExtractor

Configure how the JWT token will be extracted from request.

It support the following properties:

Property	Type	Description	Required
header	string	The name of the header that contains the token.	false
queryParam	string	The name of the param that contains the token.	false
authHeader	string	The name of shcema used in Authorization header. Ex: 'JWT'.	false
bodyField	string	The name of the form param that contains the token.	false
cookie	string	The name of the cookie that contains the tolen.	false

Example:

{
    "authentication": [{
        "strategy": {
            "name": "jwt",
            "options": {
                "extractFrom": {
                    "authHeader": "Bearer",
                    "queryParam": "jwt"
                },
                "secretOrKey": "secret",
                "algorithms": ["HS256", "HS384"],
                "ignoreExpiration": true,
                "verify": {
                    "name": "verifyJwtUser"
                }
            }
        } 
    }]
}