template.yml

AWSTemplateFormatVersion: 2010-09-09
Transform: AWS::Serverless-2016-10-31

Metadata:
  AWS::ServerlessRepo::Application:
    Name: oidc-authorizer
    Description: A high-performance token-based API Gateway authorizer Lambda that can validate OIDC-issued JWT tokens.
    Author: Luciano Mammino
    SpdxLicenseId: MIT
    LicenseUrl: LICENSE
    ReadmeUrl: README.md
    Labels: ["apigateway", "authorizer", "lambda", "oidc"]
    HomePageUrl: https://github.com/lmammino/oidc-authorizer
    SemanticVersion: 0.4.0 # x-release-please-version
    SourceCodeUrl: https://github.com/lmammino/oidc-authorizer

Parameters:
  JwksUri:
    Type: String
    Description: The URL of the OIDC provider JWKS (Endpoint providing public keys for verification).
  MinRefreshRate:
    Type: String
    Description: The minumum number of seconds to wait before keys are refreshed when the given key is not found.
    Default: "900" # 15 minutes
  JwksPreCachedFilePath:
    Type: String
    Description: |
      Optional path to a pre-cached JWKS file on disk. When set, the authorizer pre-warms its in-memory key cache from this
      file at startup, avoiding the initial network call to the JWKS endpoint. The file should contain a valid JWKS JSON
      structure matching your OIDC provider's JWKS format. If the file is missing or invalid, the authorizer logs a warning
      and starts with an empty cache (falling back to fetching from the JWKS URI on the first request). The file path should
      be accessible from the Lambda execution environment (e.g., /opt/jwks.json for Lambda layers).
    Default: ""
  LambdaLayers:
    Type: String
    Description: |
      Optional comma-separated list of Lambda layer ARNs to attach to the authorizer function.
      Use this to add a pre-cached JWKS layer (for faster cold starts, together with JwksPreCachedFilePath),
      monitoring extensions, or any other layers you need.
    Default: ""
  PrincipalIdClaims:
    Type: String
    Description: |
      A comma-separated list of claims defining the token fields that should be used to determine the principal Id
      from the token. The fields will be tested in order. If there's no match the value specified in the `DefaultPrincipalId`
      parameter will be used.
    Default: "preferred_username, sub"
  DefaultPrincipalId:
    Type: String
    Description: A fallback value for the Principal ID to be used when a principal ID claim is not found in the token.
    Default: "unknown"
  AcceptedIssuers:
    Type: String
    Description: |
      A comma-separated list of accepted values for the `iss` claim. If one of the provided values matches,
      the token issuer is considered valid. If left empty, any issuer will be accepted.
    Default: ""
  AcceptedAudiences:
    Type: String
    Description: |
      A comma-separated list of accepted values for the `aud` claim. If one of the provided values matches,
      the token audience is considered valid. If left empty, any issuer audience be accepted.
    Default: ""
  AcceptedAlgorithms:
    Type: String
    Description: |
      A comma-separated list of accepted signing algorithms. If one of the provided values matches,
      the token signing algorithm is considered valid. If left empty, any supported token signing
      algorithm is accepted.
      Supported values:
      - ES256
      - ES384
      - RS256
      - RS384
      - PS256
      - PS384
      - PS512
      - RS512
      - EdDSA
    Default: ""
  TokenValidationCel:
    Type: String
    Description: |
      A CEL (Common Expression Language) expression for custom token validation.
      The expression is evaluated against the decoded token's `header` and `claims`
      after signature verification. If the expression evaluates to `false`, the token
      is rejected. If empty, CEL validation is skipped.

      Available variables:
      - header: JWT header fields (alg, kid, typ, etc.)
      - claims: JWT payload claims (iss, sub, aud, custom claims, etc.)

      Example: claims.email_verified == true && claims.roles.exists(r, r == "admin")
    Default: ""
  AwsLambdaLogLevel:
    Type: String
    Description: |
      The log level used when executing the authorizer lambda. You can set it to DEBUG to make it very verbose if you need more information
      to troubleshoot an issue. In general you should not change this, because if you produce more logs than necessary that might have an impact on cost.
    Default: INFO
    AllowedValues:
      - TRACE
      - DEBUG
      - INFO
      - WARN
      - ERROR
  LogGroupName:
    Type: String
    Description: |
      Optional. The name or ARN of an existing CloudWatch Log Group to use for Lambda logs.
      If specified, the Lambda will log to this group instead of the auto-created one.
      When using this option, you manage the log group's retention externally.
      Cannot be used together with LogRetentionDays.
    Default: ""
  LogRetentionDays:
    Type: Number
    Description: |
      Optional. The number of days to retain logs in the auto-created CloudWatch Log Group.
      If set to 0 (default), logs are retained indefinitely.
      Cannot be used together with LogGroupName.
    Default: 0
    AllowedValues:
      - 0
      - 1
      - 3
      - 5
      - 7
      - 14
      - 30
      - 60
      - 90
      - 120
      - 150
      - 180
      - 365
      - 400
      - 545
      - 731
      - 1096
      - 1827
      - 2192
      - 2557
      - 2922
      - 3288
      - 3653
  LambdaTimeout:
    Type: Number
    Description: The timeout to give to the authorizer Lambda.
    Default: "3"
  LambdaMemorySize:
    Type: Number
    MinValue: "128"
    MaxValue: "10240"
    Description: The amount of memory (in MB) to give to the authorizer Lambda.
    Default: "128"
  StackPrefix:
    Type: String
    Description: A prefix to be used for exported outputs. Useful if you need to deploy this stack multiple times in the same account.
    Default: ""

Rules:
  MutuallyExclusiveLogConfig:
    Assertions:
      - Assert: !Or
          - !Equals [!Ref LogGroupName, ""]
          - !Equals [!Ref LogRetentionDays, "0"]
        AssertDescription: "LogGroupName and LogRetentionDays cannot both be specified. Use LogGroupName to specify an external log group, OR use LogRetentionDays to create a managed log group with retention."

Conditions:
  UseCustomLogGroup: !Not [!Equals [!Ref LogGroupName, ""]]
  CreateManagedLogGroup: !And
    - !Equals [!Ref LogGroupName, ""]
    - !Not [!Equals [!Ref LogRetentionDays, "0"]]
  ConfigureLogging: !Or
    - !Condition UseCustomLogGroup
    - !Condition CreateManagedLogGroup
  HasJwksPreCachedFilePath: !Not [!Equals [!Ref JwksPreCachedFilePath, ""]]
  HasLambdaLayers: !Not [!Equals [!Ref LambdaLayers, ""]]

Resources:
  OidcAuthorizerLogGroup:
    Type: AWS::Logs::LogGroup
    Condition: CreateManagedLogGroup
    Properties:
      LogGroupName: !Sub "/aws/lambda/${AWS::StackName}-OidcAuthorizer"
      RetentionInDays: !Ref LogRetentionDays

  OidcAuthorizer:
    Type: AWS::Serverless::Function
    Metadata:
      BuildMethod: rust-cargolambda
    Properties:
      CodeUri: .
      Handler: bootstrap
      Runtime: provided.al2023
      Timeout: !Ref LambdaTimeout
      MemorySize: !Ref LambdaMemorySize
      Architectures:
        - arm64
      Layers: !If
        - HasLambdaLayers
        - !Split [",", !Ref LambdaLayers]
        - !Ref "AWS::NoValue"
      LoggingConfig: !If
        - ConfigureLogging
        - LogGroup: !If
            - UseCustomLogGroup
            - !Ref LogGroupName
            - !Ref OidcAuthorizerLogGroup
        - !Ref "AWS::NoValue"
      Environment:
        Variables:
          AWS_LAMBDA_LOG_LEVEL: !Ref AwsLambdaLogLevel
          JWKS_URI: !Ref JwksUri
          MIN_REFRESH_RATE: !Ref MinRefreshRate
          JWKS_PRE_CACHED_FILE_PATH: !If
            - HasJwksPreCachedFilePath
            - !Ref JwksPreCachedFilePath
            - !Ref "AWS::NoValue"
          PRINCIPAL_ID_CLAIMS: !Ref PrincipalIdClaims
          DEFAULT_PRINCIPAL_ID: !Ref DefaultPrincipalId
          ACCEPTED_ISSUERS: !Ref AcceptedIssuers
          ACCEPTED_AUDIENCES: !Ref AcceptedAudiences
          ACCEPTED_ALGORITHMS: !Ref AcceptedAlgorithms
          TOKEN_VALIDATION_CEL: !Ref TokenValidationCel

Outputs:
  OidcAuthorizerArn:
    Description: The ARN of the OIDC Authorizer Lambda function
    Value: !GetAtt OidcAuthorizer.Arn
    Export:
      Name: !Sub "${StackPrefix}OidcAuthorizerArn"
  OidcAuthorizerLogGroupName:
    Description: The CloudWatch Log Group name for the OIDC Authorizer Lambda
    Value: !If
      - UseCustomLogGroup
      - !Ref LogGroupName
      - !If
        - CreateManagedLogGroup
        - !Ref OidcAuthorizerLogGroup
        - !Sub "/aws/lambda/${OidcAuthorizer}"
    Export:
      Name: !Sub "${StackPrefix}OidcAuthorizerLogGroupName"