OAuth Proxy for AWS API Gateway

The OAuth Proxy is an extension to your API gateway that you need when your single page applications (SPAs) call OAuth-secured APIs using the Token Handler pattern. The SPA sends an encrypted proxy cookie that transports an access token. The OAuth Proxy plugin decrypts the cookie to extract the access token.

When the OAuth Proxy work completes, your AWS API gateway routes the request to the target API, which uses the access token to implement its OAuth security.

Download the OAuth Proxy

You get the OAuth Proxy by downloading the latest ZIP file version from the Curity Developer Portal, with a filename of the following form:

curity-token-handler-proxy-aws-<version>.zip

Unzip the file to get its contents, which include a README with detailed deployment instructions and an inner zip file. This zip file contains a Java 17 lambda function that you deploy to the AWS API gateway and configure as a lambda authorizer. The inner zip file has a name of the following form:

curity-token-handler-proxy-authorizer-<version>.zip

Prepare Decryption

You need an asymmetric keypair as part of your overall token handler deployment. To create one, follow the instructions in the Configure Cryptographic Keys section of the Create a Token Handler tutorial. This results in a PKCS#8 file with an encrypted private key, and also a private key password.

Deploy the OAuth Proxy

You must deploy the OAuth Proxy to a gateway that runs in your SPA's backend for frontend domain. If a deployment uses the following URLs, the OAuth Proxy executes in a gateway at https://bff.product.example:

• SPA Web Origin: https://www.product.example
• Backend for Frontend Base URL: https://bff.product.example
• Target API Base URL: https://api.example.com

You can deploy the lambda using the AWS CLI by running the following command. You must create an IAM Role that assigns permissions to the lambda function. For example, you can enable the function to output log information to CloudWatch. Then, assign the identifier of your role to the role-arn parameter.

aws lambda create-function --function-name ExampleAuthorizer \
--runtime java17 --handler io.curity.identityserver.tokenhandler.proxy.aws.ProcessCookie \
--environment "Variables={TOKEN_HANDLER_COOKIE_KEY=<key>,TOKEN_HANDLER_COOKIE_KEY_PASSWORD=<pass>}" \
--role <role-arn> \
--zip-file fileb://token-handler-proxy-authorizer-<version>.zip

You must also supply configuration values for the OAuth Proxy. Supply the cookie decryption key using the content of the PKCS#8 file, and the PKCS#8 file's password. If the OAuth Agent uses a different prefix for cookie names than the default value th-, you should also provide a TOKEN_HANDLER_COOKIE_PREFIX that matches the value from the OAuth Agent.

The README file contains further details on deployment, including a full deployment example implemented using the AWS Cloud Development Kit (CDK).

Configure API Routes

You must configure the OAuth Proxy for all API routes that the SPA calls. Also, add a route such as /oauthuserinfo if the SPA calls the authorization server's OpenID Connect userinfo endpoint.

You must enable CORS to instruct the browser to allow requests with cookies from the SPA's web origin, and deny access to untrusted origins. Enable settings such as these, so that your SPA can send cross-origin JSON requests:

allowOrigins: ['https://www.product.example'],
allowCredentials: true,
allowHeaders: ["Content-Type"],
allowMethods: [CorsHttpMethod.ANY],
maxAge: 86400

OAuth Proxy Output

At runtime, the OAuth Proxy processes cookies in incoming requests from SPAs and writes a policy result.

On success, the OAuth Proxy returns an allow result and provides the access token in the context output, in context.authorizer.accessToken and context.authorizer.authorizationHeader (which includes the Bearer prefix). You can then route the access token to the target API, which uses it for authorization.

On failure, the OAuth Proxy returns a deny result. By default, the gateway will then return an HTTP error with a 403 status code to your SPA. If you prefer, you can customize the gateway error responses.

Conclusion

The OAuth Proxy is part of your API gateway. It enables your SPAs to use the correct browser security and also make direct calls to API URLs. The OAuth Proxy plugin deals with the cookie complexity so that you do not need to implement it in your API code.