Simplified SSO with AWS Application Load Balancer and Azure AD OIDC

AWS Application Loan Balancers support what I think is an underappreciated feature: the ability to authenticate requests (via OIDC) at Layer 7. This allows developers to keep almost all authentication outside of the application layer code. An ideal use-case could be an internal-only web application that requires authentication, but little if any RBAC authorization.

via AWS

This AWS blog post is as a great primer on how the feature works:

ALB Authentication works by defining an authentication action in a listener rule. The ALB’s authentication action will check if a session cookie exists on incoming requests, then check that it’s valid. If the session cookie is set and valid then the ALB will route the request to the target group with X-AMZN-OIDC-* headers set. 

ALB Authentication supports both Cognito and generic OIDC Identity Providers. For this post, I’m going to focus on integration with Azure AD’s OIDC – managed with Terraform and the Serverless Framework.

Azure AD – Enterprise App Configuration

In order to setup an OIDC integration with Azure AD, you’ll first need to configure an Enterprise Application. Microsoft already has a tutorial on how to do this manually via the UI in the Azure portal, so my focus will be on deployment using the Azure AD Terraform provider. This approach has the added benefit of automatically providing the ALB Authentication configuration inputs (for Serverless) using the resulting Terraform outputs.

Let’s start with the Azure application’s configuration:

data "azuread_application_published_app_ids" "well_known" {}

resource "azuread_service_principal" "msgraph" {
  application_id = data.azuread_application_published_app_ids.well_known.result.MicrosoftGraph
  use_existing   = true

resource "azuread_application" "app" {
  display_name               = local.app_title
  group_membership_claims    = ["SecurityGroup"]
  sign_in_audience           = "AzureADMyOrg"

  web {
    homepage_url = local.base_url
    redirect_uris = [local.reply_url]
    implicit_grant {
      access_token_issuance_enabled = false
      id_token_issuance_enabled = false

  required_resource_access {
    resource_app_id = azuread_service_principal.msgraph.application_id

    resource_access {
      id   = azuread_service_principal.msgraph.oauth2_permission_scope_ids["openid"]
      type = "Scope"

resource "azuread_service_principal" "service_principal" {
  application_id =
  tags           = ["WindowsAzureActiveDirectoryIntegratedApp"]
  app_role_assignment_required = true

resource "azuread_application_password" "app_password" {
  application_object_id =
  display_name = local.app_title

resource "azuread_service_principal_delegated_permission_grant" "delegated_grant" {
  service_principal_object_id          = azuread_service_principal.service_principal.object_id
  resource_service_principal_object_id = azuread_service_principal.msgraph.object_id
  claim_values                         = ["openid"]

A couple things to note in the Terraform code above. One, we have app_role_assignment_required set, which will require specific users to be assigned to the application in Azure in order to successfully SSO. Two, the azuread_service_principal_delegated_permission_grant resource – this will grant admin consent for the openid permission on behalf of the enterprise.

Back in Terraform, we’ll expose the resulting app configuration parameters (required for the ALB listener) to AWS with SSM:

resource "aws_ssm_parameter" "tenant_id" {
  name  = "/web-app/AZURE_TENANT_ID"
  type  = "String"
  value = data.azuread_client_config.current.tenant_id

resource "aws_ssm_parameter" "client_id" {
  name  = "/web-app/AZURE_CLIENT_ID"
  type  = "String"
  value =

resource "aws_ssm_parameter" "client_secret" {
  name  = "/web-app/AZURE_CLIENT_SECRET"
  type  = "SecureString"
  value = azuread_application_password.app_password.value

Serverless – ALB Listener

With the Azure Enterprise App created, we can move on to configuring the ALB itself.  Let’s start with defining those resources:

  # ALB Resources
    Type: AWS::EC2::SecurityGroupEgress
      CidrIp: '' # OIDC needs external egress
      GroupId: !GetAtt ALBSecurityGroup.GroupId
      IpProtocol: tcp
      FromPort: 443
      ToPort: 443
    Type: AWS::EC2::SecurityGroup
      GroupDescription: ${self:service}-${self:provider.stage}-alb-sg
      VpcId: ${self:custom.alb.vpc}
    Type: AWS::EC2::SecurityGroupIngress
      GroupId: !GetAtt ALBSecurityGroup.GroupId
      IpProtocol: tcp
      FromPort: ${self:custom.alb.port}
      ToPort: ${self:custom.alb.port}
      CidrIp: ${self:custom.alb.ingress}
    Type: AWS::Lambda::Permission
      Action: lambda:InvokeFunction
      FunctionName: !GetAtt ApiLambdaFunction.Arn # Dynamic from function
    Type: AWS::ElasticLoadBalancingV2::LoadBalancer
      Subnets: ${self:custom.alb.subnets}
      Scheme: ${self:custom.alb.scheme}
        - !GetAtt ALBSecurityGroup.GroupId
      - ALBSecurityGroup
    Type: AWS::Route53::RecordSet
      HostedZoneId: ${self:custom.alb.hostedZoneId}
      Name: ${self:custom.alb.dnsName}.
        DNSName: !GetAtt ALBElasticLoadBalancer.DNSName
        HostedZoneId: !GetAtt ALBElasticLoadBalancer.CanonicalHostedZoneID
      Type: A
    Type: AWS::ElasticLoadBalancingV2::Listener
        - CertificateArn: ${self:custom.alb.certArn}
        - Type: fixed-response
            ContentType: "text/plain"
            MessageBody: ""
            StatusCode: "404"
        Ref: ALBElasticLoadBalancer
      Port: ${self:custom.alb.port}
      Protocol: ${self:custom.alb.protocol}

Note the ALBSecurityGroupEgress resource, indicating the ALB needs external egress (even for internal-only ALBs) so it can interact with the Azure ODIC APIs.

Next, we will wire up the ALB listener rule within Serverless, starting with the ALB Authorizer configuration:

    tenantId: '${ssm:/web-app/AZURE_TENANT_ID}'
    clientId: '${ssm:/web-app/AZURE_CLIENT_ID}'
    clientSecret: '${ssm:/web-app/AZURE_CLIENT_SECRET}'
  name: aws
  runtime: python3.9
  timeout: 60
        type: oidc
        onUnauthenticatedRequest: authenticate
        clientId: ${self:custom.oidc.clientId}
        clientSecret: ${self:custom.oidc.clientSecret}

Note the references to the custom.oidc attributes, which are fetched dynamically from SSM and brought to you by the Terraform above. Next, hook up the authorizer to the ALB event on the Lambda function.

    handler: webapp.alb_handler
      - alb:
          listenerArn: !Ref LoadBalancerListener
          priority: 1
          multiValueHeaders: true
          authorizer: azureAdAuth
            path: "*"

After deploying, you’ll see something like this in the ALB’s rules UI:

K8s ALB Annotations

You can also achieve a similar configuration using ingress annotations in Kubernetes:

kind: Ingress
apiVersion: extensions/v1beta1
  name: ***REMOVED***
  namespace: ***REMOVED***
  annotations: >-
      {"secretName":"***REMOVED***","issuer":"***REMOVED***/v2.0","authorizationEndpoint":"***REMOVED***/oauth2/v2.0/authorize","tokenEndpoint":"***REMOVED***/oauth2/v2.0/token","userInfoEndpoint":""} authenticate openid AWSELBAuthSessionCookie '604800' oidc

OIDC Headers

After authenticating a request, the ALB adds additional headers containing the user claims before forwarding it to the target. The linked doc has an example of decoding the x-amzn-oidc-data header – I’ve adapted it a bit to cache the public key, add logging, and verify the issuer:

AWS_REGION = os.getenv("AWS_REGION", "us-east-1")
OIDC_ISSUER = os.getenv("OIDC_ISSUER", "")
PUB_KEY = None

def decode_jwt(encoded_jwt):
    log ="DecodeJwt")

    global PUB_KEY
    if not PUB_KEY:
        log.debug("Initializing ALB public key")

        # Step 1: Get the key id from JWT headers (the kid field)
        jwt_headers = encoded_jwt.split(".")[0]
        decoded_jwt_headers = base64.b64decode(jwt_headers)
        decoded_jwt_headers = decoded_jwt_headers.decode("utf-8")
        decoded_json = json.loads(decoded_jwt_headers)
        kid = decoded_json["kid"]

        # Step 2: Get the public key from regional endpoint
        url = f"https://public-keys.auth.elb.{AWS_REGION}{kid}"
        req = requests.get(url)
        PUB_KEY = req.text
        log.debug("Using cached public key")

    # Step 3: Get the payload
    log.debug("Decoding JWT...")
    payload = jwt.decode(encoded_jwt, PUB_KEY, issuer=OIDC_ISSUER, algorithms=["ES256"])

    log.debug("Decoded JWT", payload=payload)
    return payload

And here’s an example decoded claims payload from Azure AD:

  "sub": "***REMOVED***",
  "name": "Randy Westergren",
  "family_name": "Westergren",
  "given_name": "Randolph",
  "picture": "$value",
  "email": "[email protected]***REMOVED***.com",
  "exp": 1665076372,
  "iss": "***REMOVED***/v2.0"

You can use this for anything from logging user requests, to expanding the app to add authorization rules.


Now when you visit your protected paths, you’ll first be redirected to the Azure AD sign-in:

Azure AD Login

After successful login, subsequent requests will have the AWSELBAuthSessionCookie cookie set.

Share this: Facebooktwitterlinkedin