Authentication Extraction

By default, Panoptica's API Security feature detects and extracts authentication and authorization items located in the Authorization request header. The Bearer and Basic methods are supported.

Panoptica also enables extraction of configuration-driven authentication and authorization objects. This means that you can specify custom locations to find and extract authentication and authorization items in your APIs. For example, you can extract the JWT token from various headers, then extract specific claims from the token.

Prerequisites

You need access to the Panoptica API. For details on creating an API key, see the REST API Quick Start Guide.

Upload custom extraction rules

To configure a custom authentication or authorization extraction rule, complete the following steps.

Check that you can access the /trace-analysis/authConfigurations endpoint. This endpoint returns the list of such custom authentication extraction configurations. For example, run:
curl -X GET "https://api.us1.console.panoptica.app/api/apisec/trace-analysis/authConfigurations" -H "accept: application/json" -H "Authorization: <your-API-key>"

If there is no custom authentication configuration configured, the response is just an empty list: []
Prepare a JSON object that describes your custom authentication or authorization rule and save it into a file called body.json. For examples, see the Sample extraction rules
Post a request to the /trace-analysis/authConfigurations endpoint. The body of the request must be the JSON object that you've prepared in the previous step.
curl -H "Content-Type: application/json" --data @body.json "https://api.us1.console.panoptica.app/api/apisec/trace-analysis/authConfigurations"

Create extraction rule

To create a custom authentication or authorization extraction rule, you have to create a JSON object that is appropriate for the API traffic you are monitoring with Panoptica. Follow these guidelines.

Get the ID of the API that the rule will apply to and add it to the apiId key. You can get the list of APIs from the /api/apisec/trace-analysis/apis endpoint. The response includes various data about your APIs, like their ID.
```
{
    "apiId": <API_ID>,
}
```
Set the scope of the rule. If the rule applies to every endpoint of the API, add "endpointId": "", otherwise add the path of the endpoint.
```
{
    "apiId": <API_ID>,
    "endpointId": "",
}
```
Set type of the rule: jwt

{
    "apiId": <API_ID>,
    "endpointId": "",
    "jwt": {    
    }
}

Set the locations where API Security looks for the item to extract. If you set multiple locations and multiple matches are found, the first match is used. The following locations are supported:
- cookie:<cookie-name>: Extract the token from the specified cookie. For example, cookie:jwt would extract the token from a cookie like: Cookie md.sid=s%3A3mX3_…; jwt=eyJhbGciOiJ…A8Y; SESSION=…
- req_header:token: Extract the token from the specified request header. For example, req_header:token would extract the token from a header like: token eyJhbGciOiJ…A8Y

{
        "apiId": <API_ID>,
        "endpointId": "",
        "authPriority1":"JWT",
        "authPriority2":"EXPLICITHEADERS",
        "authPriority3":"BASIC",
        "authPriority4":"REFERENCETOKEN",
        "jwt":{
            "location":["cookie:jwt"],
            "userIdAttributes":[{"legitimate": True, "name": "UserId"}]
        }
}

Extract JWT from the Cookie header

The following is a sample extraction rule that:

finds and extracts the authorization/authentication JWT token in the jwt Cookie header, and
extracts the claim called UserId from the JWT token as user id attribute.

{
        "apiId": <API_ID>,
        "endpointId": "",
        "authPriority1":"JWT",
        "authPriority2":"EXPLICITHEADERS",
        "authPriority3":"BASIC",
        "authPriority4":"REFERENCETOKEN",
        "jwt":{
            "location":["cookie:jwt"],
            "userIdAttributes":[{"legitimate": True, "name": "UserId"}]
        }
}

Extract JWT from a custom header

The following is a sample extraction rule that:

finds and extracts the authorization/authentication JWT token in the token header, and
extracts two claims called UserId and name from the JWT token as user id and custom attributes.

{
        "apiId": <API_ID>,
        "endpointId": "",
        "authPriority1":"JWT",
        "authPriority2":"EXPLICITHEADERS",
        "authPriority3":"BASIC",
        "authPriority4":"REFERENCETOKEN",
        "jwt":{
            "location":["req_header:token"],
            "userIdAttributes":[{"legitimate": True, "name": "UserId"}],
            "customAttributes":[{"legitimate": True, "name": "name"}],
        }
}