Repository files navigation

There is an inherent risk in maintaining and storing permanent credentials. In their lifetime, they are bound to be shared, compromised, and lost. When shared, it is often among a broader audience than initially intended. They can also be lost and found, sometimes by the wrong person. And when any of this occurs, it can put your systems, data or even organization at risk.

Workloads running on AWS can communicate with each other or with AWS services without the need of storing permanent credentials by assuming roles or instance profiles. However, if one of the workloads lives outside of AWS, AWS principals can no longer be used for authentication.

An alternative to authenticating with external workloads is to use short-lived credentials issued by a trusted party, the issuer, that the target system can accept. JWTs (JSON Web Tokens), as used by the OIDC (OpenID Connect) standard, are an example of such credentials. JWTs are short-lived credentials that can be signed and verified using a public key in what is known as public-key cryptography.

Exchanging credentials from on form to the other is done with a Secure Token Service (STS) function. AWS also provides STS functions not the one we need. Only the other way around: to exchange a JWT to IAM Session which is calledAssumeRoleWithWebIdentity.This repo contains a CDK Construct which will deploy a new function which adds the function to exchange an AWS IAM (Session) credential with a signed JWT.

The solution provides 2 endpoints; an OIDC discovery endpoint and a token endpoint. The OIDC discovery endpoint can be used to establish a trust between te STS function and a resource. The token endpoint can be used by client in AWS to exchange their IAM credentials to a JWT.

When a client wants to retrieve a JWT key, it will invoke the token API via the API GW. The backing lambda creates a JWT based on the invoking IAM identity and invokes KMS to sign the token.

On time based events, EventBridge will trigger a Step function rotation flow. This flow triggers a lambda which in subsequent steps will create a new KMS signing key. Based on that signing key a JWKS is generated and stored in S3 together with discovery files.

1. Init a new typescript CDK projectcdk init app --language typescript
2. Config npm to retrieve packages from github package repositoryecho @alliander-opensource:registry=https://npm.pkg.github.com > .npmrc
3. Install the aws-jwt-sts constructnpm install @alliander-opensource/aws-jwt-sts
4. Edit lib/my-sts-stack.ts to add the construct to the stackSee the comments in the code for possible options

import*ascdkfrom'aws-cdk-lib';import{Construct}from'constructs';import{AwsJwtSts,wafUsage}from'@alliander-opensource/aws-jwt-sts'exportclassMyStsStackextendscdk.Stack{constructor(scope:Construct,id:string,props?:cdk.StackProps){super(scope,id,props);newAwsJwtSts(this,'sts',{/*      * Mandatory:      *      * Set the default aud claim in the jwt, when not specified in the GET param      */defaultAudience:'api://resourceAudience',/*      * Optional: when using a custom domain      *      * The construct can run on a custom domain, for this the following properties need to be added      * Ensure a hosted zone is present in the account where the sts function will be deployed      * Both needed to be set to use the custom domain      */hostedZoneName:'test.example.com',// domain name of the zonehostedZoneId:'ZXXXXXXXXXXXXXXXXXXXX',// zoneId of the zone/*      * Optional; when using a custom domain the subdomains of the endpoints can optionally be set      */oidcSubdomain:'oidc',// default 'oidc' for the discovery endpoint (cloudfront)tokenSubdomain:'token',// default 'token' for the the token api gw endpoint/*      * Optional:      *      * AWS WAF can be applied to the API GW      * apiGwWaf acceptes the folling values:      * wafUsage.ConstructProvided to use the WAF defined by the contruct      * wafUsage.ProvideWebAclArn in combination with the apiGwWafWebAclArn param to specify an already deployed webAcl      *      * By not setting apiGwWaf, no WAF will be deployed      */apiGwWaf:wafUsage.ProvideWebAclArn,/*      * Optional; only applicable if apiGwWaf is set to: wafUsage.ProvideWebAclArn      *      * Specify the WebAcl to use for the API GW      */apiGwWafWebAclArn:'arn:aws:wafv2:{REGION}:{ACCOUNTID}:regional/webacl/{WebAclName}/{WebAclId}',/*      * Optional:      *      * When used in a multi account structure with AWS Organizations specify the organization ID.      * This sets a resource policy on the API GW Stage so that the whole org may access it      * When not specified no policy is places on the API GW Stage and it will only allow access from within that account      */orgId:'o-xxxxxxxxxx'})}}

5. Deploy the stackcdk deploy

The stack outputs the urls of the endpoints. So if no custom domain is provided observe the CDK Stack output.

A token from the STS function can be obained by invoking the token endpoint.GET https://$host/tokenoptionally an audience can be provided if this needs to be different than the installed defaultGET https://$host/token?aud=api://myAudience

Note: The IAM Role / User invoking the endpoint must haveexecute-api:Invoke permissions

In CDK these permission is added as followed:

role.addToPolicy(newiam.PolicyStatement({actions:['execute-api:Invoke'],resources:['*']}))

Note: keep in mind thatresource '*' should only be used if no other API GW's with IAM auth are used in that account.

1. Ensure the AWS IAM Role / User invoking the token endpoint has execute-api permissions. If you are using administrator access then that is more than sufficient.
2. Use a shell with AWS cli logged in, you can use your cli with which you deployed the stack or use cloudshell for this.
3. Install awscurl for authenticationpip3 install awscurl
4. Install jwt-cli for jwt formattingnpm install -g jwt-cli
5. Invoke the apiawscurl {your_token_endpoint}/token --service execute-api --region {your_region} | jq -r .token | jwt decode –
6. Observe the JWT