README
¶
AWS APIGatewayv2 Authorizers
Table of Contents
Introduction
API Gateway supports multiple mechanisms for controlling and managing access to your HTTP API. They are mainly classified into Lambda Authorizers, JWT authorizers and standard AWS IAM roles and policies. More information is available at Controlling and managing access to an HTTP API.
HTTP APIs
Access control for Http Apis is managed by restricting which routes can be invoked via.
Authorizers and scopes can either be applied to the api, or specifically for each route.
Default Authorization
When using default authorization, all routes of the api will inherit the configuration.
In the example below, all routes will require the manage:books
scope present in order to invoke the integration.
import "github.com/aws/aws-cdk-go/awscdk"
issuer := "https://test.us.auth0.com"
authorizer := awscdk.NewHttpJwtAuthorizer(jsii.String("DefaultAuthorizer"), issuer, &HttpJwtAuthorizerProps{
JwtAudience: []*string{
jsii.String("3131231"),
},
})
api := apigwv2.NewHttpApi(this, jsii.String("HttpApi"), &HttpApiProps{
DefaultAuthorizer: authorizer,
DefaultAuthorizationScopes: []*string{
jsii.String("manage:books"),
},
})
Route Authorization
Authorization can also configured for each Route. When a route authorization is configured, it takes precedence over default authorization.
The example below showcases default authorization, along with route authorization. It also shows how to remove authorization entirely for a route.
GET /books
andGET /books/{id}
use the default authorizer settings on the apiPOST /books
will require the [write:books] scopePOST /login
removes the default authorizer (unauthenticated route)
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"
issuer := "https://test.us.auth0.com"
authorizer := awscdk.NewHttpJwtAuthorizer(jsii.String("DefaultAuthorizer"), issuer, &HttpJwtAuthorizerProps{
JwtAudience: []*string{
jsii.String("3131231"),
},
})
api := apigwv2.NewHttpApi(this, jsii.String("HttpApi"), &HttpApiProps{
DefaultAuthorizer: authorizer,
DefaultAuthorizationScopes: []*string{
jsii.String("read:books"),
},
})
api.AddRoutes(&AddRoutesOptions{
Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")),
Path: jsii.String("/books"),
Methods: []httpMethod{
apigwv2.*httpMethod_GET,
},
})
api.AddRoutes(&AddRoutesOptions{
Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIdIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")),
Path: jsii.String("/books/{id}"),
Methods: []*httpMethod{
apigwv2.*httpMethod_GET,
},
})
api.AddRoutes(&AddRoutesOptions{
Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")),
Path: jsii.String("/books"),
Methods: []*httpMethod{
apigwv2.*httpMethod_POST,
},
AuthorizationScopes: []*string{
jsii.String("write:books"),
},
})
api.AddRoutes(&AddRoutesOptions{
Integration: awscdk.NewHttpUrlIntegration(jsii.String("LoginIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")),
Path: jsii.String("/login"),
Methods: []*httpMethod{
apigwv2.*httpMethod_POST,
},
Authorizer: apigwv2.NewHttpNoneAuthorizer(),
})
JWT Authorizers
JWT authorizers allow the use of JSON Web Tokens (JWTs) as part of OpenID Connect and OAuth 2.0 frameworks to allow and restrict clients from accessing HTTP APIs.
When configured, API Gateway validates the JWT submitted by the client, and allows or denies access based on its content.
The location of the token is defined by the identitySource
which defaults to the http Authorization
header. However it also
supports a number of other options.
It then decodes the JWT and validates the signature and claims, against the options defined in the authorizer and route (scopes).
For more information check the JWT Authorizer documentation.
Clients that fail authorization are presented with either 2 responses:
401 - Unauthorized
- When the JWT validation fails403 - Forbidden
- When the JWT validation is successful but the required scopes are not met
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"
issuer := "https://test.us.auth0.com"
authorizer := awscdk.NewHttpJwtAuthorizer(jsii.String("BooksAuthorizer"), issuer, &HttpJwtAuthorizerProps{
JwtAudience: []*string{
jsii.String("3131231"),
},
})
api := apigwv2.NewHttpApi(this, jsii.String("HttpApi"))
api.AddRoutes(&AddRoutesOptions{
Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")),
Path: jsii.String("/books"),
Authorizer: Authorizer,
})
User Pool Authorizer
User Pool Authorizer is a type of JWT Authorizer that uses a Cognito user pool and app client to control who can access your Api. After a successful authorization from the app client, the generated access token will be used as the JWT.
Clients accessing an API that uses a user pool authorizer must first sign in to a user pool and obtain an identity or access token.
They must then use this token in the specified identitySource
for the API call. More information is available at using Amazon Cognito user
pools as authorizer.
import cognito "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"
userPool := cognito.NewUserPool(this, jsii.String("UserPool"))
authorizer := awscdk.NewHttpUserPoolAuthorizer(jsii.String("BooksAuthorizer"), userPool)
api := apigwv2.NewHttpApi(this, jsii.String("HttpApi"))
api.AddRoutes(&AddRoutesOptions{
Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")),
Path: jsii.String("/books"),
Authorizer: Authorizer,
})
Lambda Authorizers
Lambda authorizers use a Lambda function to control access to your HTTP API. When a client calls your API, API Gateway invokes your Lambda function and uses the response to determine whether the client can access your API.
Lambda authorizers depending on their response, fall into either two types - Simple or IAM. You can learn about differences here.
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"
// This function handles your auth logic
var authHandler function
authorizer := awscdk.NewHttpLambdaAuthorizer(jsii.String("BooksAuthorizer"), authHandler, &HttpLambdaAuthorizerProps{
ResponseTypes: []httpLambdaResponseType{
awscdk.HttpLambdaResponseType_SIMPLE,
},
})
api := apigwv2.NewHttpApi(this, jsii.String("HttpApi"))
api.AddRoutes(&AddRoutesOptions{
Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")),
Path: jsii.String("/books"),
Authorizer: Authorizer,
})
IAM Authorizers
API Gateway supports IAM via the included HttpIamAuthorizer
and grant syntax:
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"
var principal anyPrincipal
authorizer := awscdk.NewHttpIamAuthorizer()
httpApi := apigwv2.NewHttpApi(this, jsii.String("HttpApi"), &HttpApiProps{
DefaultAuthorizer: authorizer,
})
routes := httpApi.AddRoutes(&AddRoutesOptions{
Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")),
Path: jsii.String("/books/{book}"),
})
routes[0].GrantInvoke(principal)
WebSocket APIs
You can set an authorizer to your WebSocket API's $connect
route to control access to your API.
Lambda Authorizer
Lambda authorizers use a Lambda function to control access to your WebSocket API. When a client connects to your API, API Gateway invokes your Lambda function and uses the response to determine whether the client can access your API.
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"
// This function handles your auth logic
var authHandler function
// This function handles your WebSocket requests
var handler function
authorizer := awscdk.NewWebSocketLambdaAuthorizer(jsii.String("Authorizer"), authHandler)
integration := awscdk.NewWebSocketLambdaIntegration(jsii.String("Integration"), handler)
apigwv2.NewWebSocketApi(this, jsii.String("WebSocketApi"), &WebSocketApiProps{
ConnectRouteOptions: &WebSocketRouteOptions{
Integration: *Integration,
Authorizer: *Authorizer,
},
})
Documentation
¶
Index ¶
- func NewHttpIamAuthorizer_Override(h HttpIamAuthorizer)
- func NewHttpJwtAuthorizer_Override(h HttpJwtAuthorizer, id *string, jwtIssuer *string, ...)
- func NewHttpLambdaAuthorizer_Override(h HttpLambdaAuthorizer, id *string, handler awslambda.IFunction, ...)
- func NewHttpUserPoolAuthorizer_Override(h HttpUserPoolAuthorizer, id *string, pool awscognito.IUserPool, ...)
- func NewWebSocketLambdaAuthorizer_Override(w WebSocketLambdaAuthorizer, id *string, handler awslambda.IFunction, ...)
- type HttpIamAuthorizer
- type HttpJwtAuthorizer
- type HttpJwtAuthorizerProps
- type HttpLambdaAuthorizer
- type HttpLambdaAuthorizerProps
- type HttpLambdaResponseType
- type HttpUserPoolAuthorizer
- type HttpUserPoolAuthorizerProps
- type WebSocketLambdaAuthorizer
- type WebSocketLambdaAuthorizerProps
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewHttpIamAuthorizer_Override ¶
func NewHttpIamAuthorizer_Override(h HttpIamAuthorizer)
Experimental.
func NewHttpJwtAuthorizer_Override ¶
func NewHttpJwtAuthorizer_Override(h HttpJwtAuthorizer, id *string, jwtIssuer *string, props *HttpJwtAuthorizerProps)
Initialize a JWT authorizer to be bound with HTTP route. Experimental.
func NewHttpLambdaAuthorizer_Override ¶
func NewHttpLambdaAuthorizer_Override(h HttpLambdaAuthorizer, id *string, handler awslambda.IFunction, props *HttpLambdaAuthorizerProps)
Initialize a lambda authorizer to be bound with HTTP route. Experimental.
func NewHttpUserPoolAuthorizer_Override ¶
func NewHttpUserPoolAuthorizer_Override(h HttpUserPoolAuthorizer, id *string, pool awscognito.IUserPool, props *HttpUserPoolAuthorizerProps)
Initialize a Cognito user pool authorizer to be bound with HTTP route. Experimental.
func NewWebSocketLambdaAuthorizer_Override ¶
func NewWebSocketLambdaAuthorizer_Override(w WebSocketLambdaAuthorizer, id *string, handler awslambda.IFunction, props *WebSocketLambdaAuthorizerProps)
Experimental.
Types ¶
type HttpIamAuthorizer ¶
type HttpIamAuthorizer interface { awsapigatewayv2.IHttpRouteAuthorizer // Bind this authorizer to a specified Http route. // Experimental. Bind(_options *awsapigatewayv2.HttpRouteAuthorizerBindOptions) *awsapigatewayv2.HttpRouteAuthorizerConfig }
Authorize HTTP API Routes with IAM.
Example:
import "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" var principal anyPrincipal authorizer := awscdk.NewHttpIamAuthorizer() httpApi := apigwv2.NewHttpApi(this, jsii.String("HttpApi"), &HttpApiProps{ DefaultAuthorizer: authorizer, }) routes := httpApi.AddRoutes(&AddRoutesOptions{ Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")), Path: jsii.String("/books/{book}"), }) routes[0].GrantInvoke(principal)
Experimental.
type HttpJwtAuthorizer ¶
type HttpJwtAuthorizer interface { awsapigatewayv2.IHttpRouteAuthorizer // Bind this authorizer to a specified Http route. // Experimental. Bind(options *awsapigatewayv2.HttpRouteAuthorizerBindOptions) *awsapigatewayv2.HttpRouteAuthorizerConfig }
Authorize Http Api routes on whether the requester is registered as part of an AWS Cognito user pool.
Example:
import "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" issuer := "https://test.us.auth0.com" authorizer := awscdk.NewHttpJwtAuthorizer(jsii.String("BooksAuthorizer"), issuer, &HttpJwtAuthorizerProps{ JwtAudience: []*string{ jsii.String("3131231"), }, }) api := apigwv2.NewHttpApi(this, jsii.String("HttpApi")) api.AddRoutes(&AddRoutesOptions{ Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")), Path: jsii.String("/books"), Authorizer: Authorizer, })
Experimental.
func NewHttpJwtAuthorizer ¶
func NewHttpJwtAuthorizer(id *string, jwtIssuer *string, props *HttpJwtAuthorizerProps) HttpJwtAuthorizer
Initialize a JWT authorizer to be bound with HTTP route. Experimental.
type HttpJwtAuthorizerProps ¶
type HttpJwtAuthorizerProps struct { // A list of the intended recipients of the JWT. // // A valid JWT must provide an aud that matches at least one entry in this list. // Experimental. JwtAudience *[]*string `field:"required" json:"jwtAudience" yaml:"jwtAudience"` // The name of the authorizer. // Experimental. AuthorizerName *string `field:"optional" json:"authorizerName" yaml:"authorizerName"` // The identity source for which authorization is requested. // Experimental. IdentitySource *[]*string `field:"optional" json:"identitySource" yaml:"identitySource"` }
Properties to initialize HttpJwtAuthorizer.
Example:
import "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" issuer := "https://test.us.auth0.com" authorizer := awscdk.NewHttpJwtAuthorizer(jsii.String("BooksAuthorizer"), issuer, &HttpJwtAuthorizerProps{ JwtAudience: []*string{ jsii.String("3131231"), }, }) api := apigwv2.NewHttpApi(this, jsii.String("HttpApi")) api.AddRoutes(&AddRoutesOptions{ Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")), Path: jsii.String("/books"), Authorizer: Authorizer, })
Experimental.
type HttpLambdaAuthorizer ¶
type HttpLambdaAuthorizer interface { awsapigatewayv2.IHttpRouteAuthorizer // Bind this authorizer to a specified Http route. // Experimental. Bind(options *awsapigatewayv2.HttpRouteAuthorizerBindOptions) *awsapigatewayv2.HttpRouteAuthorizerConfig }
Authorize Http Api routes via a lambda function.
Example:
import "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" // This function handles your auth logic var authHandler function authorizer := awscdk.NewHttpLambdaAuthorizer(jsii.String("BooksAuthorizer"), authHandler, &HttpLambdaAuthorizerProps{ ResponseTypes: []httpLambdaResponseType{ awscdk.HttpLambdaResponseType_SIMPLE, }, }) api := apigwv2.NewHttpApi(this, jsii.String("HttpApi")) api.AddRoutes(&AddRoutesOptions{ Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")), Path: jsii.String("/books"), Authorizer: Authorizer, })
Experimental.
func NewHttpLambdaAuthorizer ¶
func NewHttpLambdaAuthorizer(id *string, handler awslambda.IFunction, props *HttpLambdaAuthorizerProps) HttpLambdaAuthorizer
Initialize a lambda authorizer to be bound with HTTP route. Experimental.
type HttpLambdaAuthorizerProps ¶
type HttpLambdaAuthorizerProps struct { // Friendly authorizer name. // Experimental. AuthorizerName *string `field:"optional" json:"authorizerName" yaml:"authorizerName"` // The identity source for which authorization is requested. // Experimental. IdentitySource *[]*string `field:"optional" json:"identitySource" yaml:"identitySource"` // The types of responses the lambda can return. // // If HttpLambdaResponseType.SIMPLE is included then // response format 2.0 will be used. // See: https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html#http-api-lambda-authorizer.payload-format-response // // Experimental. ResponseTypes *[]HttpLambdaResponseType `field:"optional" json:"responseTypes" yaml:"responseTypes"` // How long APIGateway should cache the results. // // Max 1 hour. // Disable caching by setting this to `Duration.seconds(0)`. // Experimental. ResultsCacheTtl awscdk.Duration `field:"optional" json:"resultsCacheTtl" yaml:"resultsCacheTtl"` }
Properties to initialize HttpTokenAuthorizer.
Example:
import "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" // This function handles your auth logic var authHandler function authorizer := awscdk.NewHttpLambdaAuthorizer(jsii.String("BooksAuthorizer"), authHandler, &HttpLambdaAuthorizerProps{ ResponseTypes: []httpLambdaResponseType{ awscdk.HttpLambdaResponseType_SIMPLE, }, }) api := apigwv2.NewHttpApi(this, jsii.String("HttpApi")) api.AddRoutes(&AddRoutesOptions{ Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")), Path: jsii.String("/books"), Authorizer: Authorizer, })
Experimental.
type HttpLambdaResponseType ¶
type HttpLambdaResponseType string
Specifies the type responses the lambda returns. Experimental.
const ( // Returns simple boolean response. // Experimental. HttpLambdaResponseType_SIMPLE HttpLambdaResponseType = "SIMPLE" // Returns an IAM Policy. // Experimental. HttpLambdaResponseType_IAM HttpLambdaResponseType = "IAM" )
type HttpUserPoolAuthorizer ¶
type HttpUserPoolAuthorizer interface { awsapigatewayv2.IHttpRouteAuthorizer // Bind this authorizer to a specified Http route. // Experimental. Bind(options *awsapigatewayv2.HttpRouteAuthorizerBindOptions) *awsapigatewayv2.HttpRouteAuthorizerConfig }
Authorize Http Api routes on whether the requester is registered as part of an AWS Cognito user pool.
Example:
import cognito "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" userPool := cognito.NewUserPool(this, jsii.String("UserPool")) authorizer := awscdk.NewHttpUserPoolAuthorizer(jsii.String("BooksAuthorizer"), userPool) api := apigwv2.NewHttpApi(this, jsii.String("HttpApi")) api.AddRoutes(&AddRoutesOptions{ Integration: awscdk.NewHttpUrlIntegration(jsii.String("BooksIntegration"), jsii.String("https://get-books-proxy.myproxy.internal")), Path: jsii.String("/books"), Authorizer: Authorizer, })
Experimental.
func NewHttpUserPoolAuthorizer ¶
func NewHttpUserPoolAuthorizer(id *string, pool awscognito.IUserPool, props *HttpUserPoolAuthorizerProps) HttpUserPoolAuthorizer
Initialize a Cognito user pool authorizer to be bound with HTTP route. Experimental.
type HttpUserPoolAuthorizerProps ¶
type HttpUserPoolAuthorizerProps struct { // Friendly name of the authorizer. // Experimental. AuthorizerName *string `field:"optional" json:"authorizerName" yaml:"authorizerName"` // The identity source for which authorization is requested. // Experimental. IdentitySource *[]*string `field:"optional" json:"identitySource" yaml:"identitySource"` // The user pool clients that should be used to authorize requests with the user pool. // Experimental. UserPoolClients *[]awscognito.IUserPoolClient `field:"optional" json:"userPoolClients" yaml:"userPoolClients"` // The AWS region in which the user pool is present. // Experimental. UserPoolRegion *string `field:"optional" json:"userPoolRegion" yaml:"userPoolRegion"` }
Properties to initialize HttpUserPoolAuthorizer.
Example:
// The code below shows an example of how to instantiate this type. // The values are placeholders you should change. import "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" var userPoolClient userPoolClient httpUserPoolAuthorizerProps := &HttpUserPoolAuthorizerProps{ AuthorizerName: jsii.String("authorizerName"), IdentitySource: []*string{ jsii.String("identitySource"), }, UserPoolClients: []iUserPoolClient{ userPoolClient, }, UserPoolRegion: jsii.String("userPoolRegion"), }
Experimental.
type WebSocketLambdaAuthorizer ¶
type WebSocketLambdaAuthorizer interface { awsapigatewayv2.IWebSocketRouteAuthorizer // Bind this authorizer to a specified WebSocket route. // Experimental. Bind(options *awsapigatewayv2.WebSocketRouteAuthorizerBindOptions) *awsapigatewayv2.WebSocketRouteAuthorizerConfig }
Authorize WebSocket Api routes via a lambda function.
Example:
import "github.com/aws/aws-cdk-go/awscdk" import "github.com/aws/aws-cdk-go/awscdk" // This function handles your auth logic var authHandler function // This function handles your WebSocket requests var handler function authorizer := awscdk.NewWebSocketLambdaAuthorizer(jsii.String("Authorizer"), authHandler) integration := awscdk.NewWebSocketLambdaIntegration(jsii.String("Integration"), handler) apigwv2.NewWebSocketApi(this, jsii.String("WebSocketApi"), &WebSocketApiProps{ ConnectRouteOptions: &WebSocketRouteOptions{ Integration: *Integration, Authorizer: *Authorizer, }, })
Experimental.
func NewWebSocketLambdaAuthorizer ¶
func NewWebSocketLambdaAuthorizer(id *string, handler awslambda.IFunction, props *WebSocketLambdaAuthorizerProps) WebSocketLambdaAuthorizer
Experimental.
type WebSocketLambdaAuthorizerProps ¶
type WebSocketLambdaAuthorizerProps struct { // The name of the authorizer. // Experimental. AuthorizerName *string `field:"optional" json:"authorizerName" yaml:"authorizerName"` // The identity source for which authorization is requested. // // Request parameter match `'route.request.querystring|header.[a-zA-z0-9._-]+'`. // Staged variable match `'stageVariables.[a-zA-Z0-9._-]+'`. // Context parameter match `'context.[a-zA-Z0-9._-]+'`. // Experimental. IdentitySource *[]*string `field:"optional" json:"identitySource" yaml:"identitySource"` }
Properties to initialize WebSocketTokenAuthorizer.
Example:
// The code below shows an example of how to instantiate this type. // The values are placeholders you should change. import "github.com/aws/aws-cdk-go/awscdk" webSocketLambdaAuthorizerProps := &WebSocketLambdaAuthorizerProps{ AuthorizerName: jsii.String("authorizerName"), IdentitySource: []*string{ jsii.String("identitySource"), }, }
Experimental.
Source Files
¶
- HttpIamAuthorizer.go
- HttpIamAuthorizer__checks.go
- HttpJwtAuthorizer.go
- HttpJwtAuthorizerProps.go
- HttpJwtAuthorizer__checks.go
- HttpLambdaAuthorizer.go
- HttpLambdaAuthorizerProps.go
- HttpLambdaAuthorizer__checks.go
- HttpLambdaResponseType.go
- HttpUserPoolAuthorizer.go
- HttpUserPoolAuthorizerProps.go
- HttpUserPoolAuthorizer__checks.go
- WebSocketLambdaAuthorizer.go
- WebSocketLambdaAuthorizerProps.go
- WebSocketLambdaAuthorizer__checks.go
- main.go