{"id":22268174,"url":"https://github.com/curityio/aws-phantom-token-lambda-authorizer","last_synced_at":"2026-03-16T14:06:44.098Z","repository":{"id":45065674,"uuid":"440701000","full_name":"curityio/aws-phantom-token-lambda-authorizer","owner":"curityio","description":"A lambda authorizer for the AWS API Gateway implementing the phantom token pattern","archived":false,"fork":false,"pushed_at":"2025-08-07T18:42:30.000Z","size":358,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-14T05:59:39.951Z","etag":null,"topics":["aws","aws-lambda","lambda-function","phantom-token"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/curityio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-22T01:45:24.000Z","updated_at":"2025-08-07T18:42:30.000Z","dependencies_parsed_at":"2025-03-25T14:45:44.512Z","dependency_job_id":"3d14134b-c7ee-4e1a-b909-8ef6e8c9de3b","html_url":"https://github.com/curityio/aws-phantom-token-lambda-authorizer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/curityio/aws-phantom-token-lambda-authorizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Faws-phantom-token-lambda-authorizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Faws-phantom-token-lambda-authorizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Faws-phantom-token-lambda-authorizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Faws-phantom-token-lambda-authorizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curityio","download_url":"https://codeload.github.com/curityio/aws-phantom-token-lambda-authorizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Faws-phantom-token-lambda-authorizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30583906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-16T09:53:36.164Z","status":"ssl_error","status_checked_at":"2026-03-16T09:53:29.590Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","lambda-function","phantom-token"],"created_at":"2024-12-03T11:11:48.683Z","updated_at":"2026-03-16T14:06:44.092Z","avatar_url":"https://github.com/curityio.png","language":"JavaScript","readme":"# AWS Phantom Token Lambda Authorizer\n\n[![Quality](https://img.shields.io/badge/quality-experiment-red)](https://curity.io/resources/code-examples/status/)\n[![Availability](https://img.shields.io/badge/availability-source-blue)](https://curity.io/resources/code-examples/status/)\n\nAn AWS Lambda Authorizer implementing the [Phantom Token Pattern](https://curity.io/resources/learn/phantom-token-pattern/). This Lambda Authorizer function enables a secure API solution using the AWS API Gateway.\n\n## Overview\n\nThe AWS API Gateway does not have built-in capabilities for introspecting opaque access tokens. It is however possible to extend the capabilities of the gateway with [Lambda Authorizer functions](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html).\n\nThe AWS Phantom Token Lambda Authorizer implements the Phantom Token Pattern. An opaque access token is passed in the Authorization header to the gateway. The gateway invokes the authorizer that will introspect the token using the `application/jwt` header in order to receive a JWT in the response.\n\nThe authorizer can also be configured to verify that a set of required scopes are present in the `scope` claim in the JWT or otherwise deny access to the requested API.\n\nWith a minor configuration the AWS API Gateway will forward the JWT from the introspection response in the `Authorization` header to the upstream API enabling a Zero Trust approach. The API in itself could also be leverage a Zero Trust design where the JWT holds the public key details for self-contained JWT verification as exemplified in this [Serverless API](https://github.com/curityio/serverless-zero-trust-api).\n\n## Building the Lambda Authorizer\n\n1. Clone the repository.\n2. Update `.env` with the correct parameters. See the [Configuration](#Configuration) section for details.\n3. Run `npm run package`. This will generate `aws-phantom-token-plugin.zip` in the current directory.\n\n## Deploying the Lambda Authorizer\n\nAfter building the authorizer, `aws-phantom-token-plugin.zip` can be uploaded and deployed as a Lambda Function in the AWS Console.\n\n1. Choose `Create function`\n2. Select the `Author from scratch` option, set a function name (ex. `curity-phantom-token-authorizer`), choose the `Node.js 22.x` runtime and `x86_64` as the architecture.\n3. Click `Create function` \n4. The default `Hello from Lambda` code is displayed. Choose `Upload from` and from the drop-down select `.zip file`. Browse to `aws-phantom-token-plugin.zip` and upload the file.\n5. Click `Deploy` to deploy the Lambda function\n\n## Configuration\n\nAn `.env` file is bundled with the packaged authorizer before deployment. \n\nParameter | Description |\n--------- | ----------- |\nHOST | The hostname of the Curity Identity Server\nINTROSPECTION_PATH | The introspection path (`/oauth/v2/oauth-introspect`)\nPORT | The runtime port of the Curity Identity Server\nSCOPE | Required scopes for API access (space separated string)\nCLIENT_ID | The client_id of a client with the `introspection` capability\nCLIENT_SECRET | The secret of the client with the `introspection` capability\n\n### Add JWT to Authorization header\n\nThe JWT from the introspection response should be forwarded to the upstream API. \n\nFor the API protected, go to `Integration Request`, click `Edit`, expand the `URL request headers parameters` and add a header named `Authorization` that is mapped from `context.authorizer.Authorization`.\n\n\u003cimg src=\"./doc/authorization-header.jpg\" alt=\"Authorization header\" width=\"800\"/\u003e\n\n### Enable Authorization caching\n\nThe Authorizer returns an AWS IAM Policy that allows or denies the request. The IAM Policy can be cached by the API Gateway to optimize performance. If the same opaque token is sent in the request the API Gateway will look up the cached IAM Policy and the Authorizer will not be executed resulting in no introspection call to the Curity Identity Server.\n\n\u003cimg src=\"./doc/configure-cache.jpg\" alt=\"Enable caching\" width=\"500\"/\u003e\n\n## More Information\n\n* Please visit [curity.io](https://curity.io/) for more information about the Curity Identity Server.\n* [Use API Gateway Lambda authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html)\n\nCopyright (C) 2021 Curity AB.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Faws-phantom-token-lambda-authorizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurityio%2Faws-phantom-token-lambda-authorizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Faws-phantom-token-lambda-authorizer/lists"}