Skip to content

API.md

Latest commit

 

History

History
2059 lines (1276 loc) · 75 KB

API.md

File metadata and controls

2059 lines (1276 loc) · 75 KB
Raw

API Reference

Constructs

GithubActionsIdentityProvider

Github Actions as OpenID Connect Identity Provider for AWS IAM. There can be only one (per AWS Account).

Use fromAccount to retrieve a reference to existing Github OIDC provider.

Uses the native CloudFormation resource AWS::IAM::OIDCProvider (no Lambda functions).

https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services

Initializers 

import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'

new GithubActionsIdentityProvider(scope: Construct, id: string, props?: GithubActionsIdentityProviderProps)
Name Type Description
scope constructs.Construct CDK Stack or Construct to which the provider is assigned to.
id string CDK Construct ID given to the construct.
props GithubActionsIdentityProviderProps optional properties for the provider.
scopeRequired
  • Type: constructs.Construct

CDK Stack or Construct to which the provider is assigned to.

idRequired
  • Type: string

CDK Construct ID given to the construct.

propsOptional

optional properties for the provider.

Methods

Name Description
toString Returns a string representation of this construct.
with Applies one or more mixins to this construct.
applyCrossStackReferenceStrength Override the cross-stack reference strength for this resource.
applyRemovalPolicy Apply the given removal policy to this resource.
toString 
public toString(): string

Returns a string representation of this construct.

with 
public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

mixinsRequired
  • Type: ...constructs.IMixin[]
applyCrossStackReferenceStrength 
public applyCrossStackReferenceStrength(strength: ReferenceStrength): void

Override the cross-stack reference strength for this resource.

When set, any cross-stack reference to this resource will use the specified mechanism instead of the global default determined by the @aws-cdk/core:defaultCrossStackReferences context key. This is useful for selectively weakening specific references to avoid the "deadly embrace" problem without changing the app-wide default.

strengthRequired
  • Type: aws-cdk-lib.ReferenceStrength

The reference strength to use for this resource.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
fromOidcProviderArn Imports an Open ID connect provider from an ARN.
fromAccount Retrieve a reference to existing Github OIDC provider in your AWS account.
isConstruct 
import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'

GithubActionsIdentityProvider.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'

GithubActionsIdentityProvider.isOwnedResource(construct: IConstruct)

Returns true if the construct was created by CDK, and false otherwise.

constructRequired
  • Type: constructs.IConstruct
isResource 
import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'

GithubActionsIdentityProvider.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
fromOidcProviderArn 
import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'

GithubActionsIdentityProvider.fromOidcProviderArn(scope: Construct, id: string, oidcProviderArn: string)

Imports an Open ID connect provider from an ARN.

scopeRequired
  • Type: constructs.Construct

The definition scope.

idRequired
  • Type: string

ID of the construct.

oidcProviderArnRequired
  • Type: string

the ARN to import.

fromAccount 
import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'

GithubActionsIdentityProvider.fromAccount(scope: Construct, id: string)

Retrieve a reference to existing Github OIDC provider in your AWS account.

An AWS account can only have single Github OIDC provider configured into it, so internally the reference is made by constructing the ARN from AWS Account ID & Github issuer URL.

Example

GithubActionsIdentityProvider.fromAccount(scope, "GithubProvider");
scopeRequired
  • Type: constructs.Construct

CDK Stack or Construct to which the provider is assigned to.

idRequired
  • Type: string

CDK Construct ID given to the construct.

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.interfaces.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
oidcProviderArn string The Amazon Resource Name (ARN) of the Native IAM OpenID Connect provider.
oidcProviderIssuer string The issuer for the Native OIDC Provider.
oidcProviderRef aws-cdk-lib.interfaces.aws_iam.OIDCProviderReference A reference to a OIDCProvider resource.
oidcProviderThumbprints string The thumbprints configured for this provider.
openIdConnectProviderArn string Alias for oidcProviderArn to maintain backwards compatibility for constructs which accept iam.IOpenIdConnectProvider.
openIdConnectProviderIssuer string Alias for oidcProviderIssuer to maintain backwards compatibility for constructs which accept `iam.IOpenIdConnectProvider.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.interfaces.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed in a Stack (those created by creating new class instances like new Role(), new Bucket(), etc.), this is always the same as the environment of the stack they belong to.

For referenced resources (those obtained from referencing methods like Role.fromRoleArn(), Bucket.fromBucketName(), etc.), they might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

oidcProviderArnRequired 
public readonly oidcProviderArn: string;
  • Type: string

The Amazon Resource Name (ARN) of the Native IAM OpenID Connect provider.

oidcProviderIssuerRequired 
public readonly oidcProviderIssuer: string;
  • Type: string

The issuer for the Native OIDC Provider.

oidcProviderRefRequired 
public readonly oidcProviderRef: OIDCProviderReference;
  • Type: aws-cdk-lib.interfaces.aws_iam.OIDCProviderReference

A reference to a OIDCProvider resource.

oidcProviderThumbprintsRequired 
public readonly oidcProviderThumbprints: string;
  • Type: string

The thumbprints configured for this provider.

openIdConnectProviderArnRequired 
public readonly openIdConnectProviderArn: string;
  • Type: string

Alias for oidcProviderArn to maintain backwards compatibility for constructs which accept iam.IOpenIdConnectProvider.

Use oidcProviderArn instead. This property exists for backward compatibility with existing constructs as migrating between the 2 constructs (OpenIdConnectProvider and OidcProviderNative) is not reasonably feasible as it requires a manual step (cdk import) since the resource type is changing between OpenIdConnectProvider and OidcProviderNative.

openIdConnectProviderIssuerRequired 
public readonly openIdConnectProviderIssuer: string;
  • Type: string

Alias for oidcProviderIssuer to maintain backwards compatibility for constructs which accept `iam.IOpenIdConnectProvider.

Use oidcProviderIssuer instead. This property exists for backward compatibility with existing constructs as migrating between the 2 constructs (OpenIdConnectProvider and OidcProviderNative) is not reasonably feasible as it requires a manual step (cdk import) since the resource type is changing between OpenIdConnectProvider and OidcProviderNative.

Constants

Name Type Description
PROPERTY_INJECTION_ID string Uniquely identifies this class.
issuer string No description.
PROPERTY_INJECTION_IDRequired 
public readonly PROPERTY_INJECTION_ID: string;
  • Type: string

Uniquely identifies this class.

issuerRequired 
public readonly issuer: string;
  • Type: string

GithubActionsRole

Define an IAM Role that can be assumed by Github Actions workflow via Github OpenID Connect Identity Provider.

Besides GithubConfiguration, you may pass in any iam.RoleProps except assumedBy which will be defined by this construct (CDK will fail if you do).

Example

const uploadRole = new GithubActionsRole(scope, "UploadRole", {
  provider: GithubActionsIdentityProvider.fromAccount(scope, "GithubProvider"),
  owner: 'octo-org',
  repo: 'octo-repo',
  filter: 'ref:refs/tags/v*',
  roleName: 'MyUploadRole',
});

myBucket.grantWrite(uploadRole);

Initializers 

import { GithubActionsRole } from 'aws-cdk-github-oidc'

new GithubActionsRole(scope: Construct, id: string, props: GithubActionsRoleProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props GithubActionsRoleProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
with Applies one or more mixins to this construct.
applyCrossStackReferenceStrength Override the cross-stack reference strength for this resource.
applyRemovalPolicy Skip applyRemovalPolicy if role synthesis is prevented by customizeRoles.
addManagedPolicy Attaches a managed policy to this role.
addToPolicy Add to the policy of this principal.
addToPrincipalPolicy Adds a permission to the role's default policy document.
attachInlinePolicy Attaches a policy to this role.
grant Grant the actions defined in actions to the identity Principal on this resource.
grantAssumeRole Grant permissions to the given principal to assume this role.
grantPassRole Grant permissions to the given principal to pass this role.
withoutPolicyUpdates Return a copy of this Role object whose Policies will not be updated.
toString 
public toString(): string

Returns a string representation of this construct.

with 
public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

mixinsRequired
  • Type: ...constructs.IMixin[]
applyCrossStackReferenceStrength 
public applyCrossStackReferenceStrength(strength: ReferenceStrength): void

Override the cross-stack reference strength for this resource.

When set, any cross-stack reference to this resource will use the specified mechanism instead of the global default determined by the @aws-cdk/core:defaultCrossStackReferences context key. This is useful for selectively weakening specific references to avoid the "deadly embrace" problem without changing the app-wide default.

strengthRequired
  • Type: aws-cdk-lib.ReferenceStrength

The reference strength to use for this resource.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Skip applyRemovalPolicy if role synthesis is prevented by customizeRoles.

Because in this case, this construct does not have a CfnResource in the tree.

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy

RemovalPolicy.

addManagedPolicy 
public addManagedPolicy(policy: IManagedPolicy): void

Attaches a managed policy to this role.

policyRequired
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy

The the managed policy to attach.

addToPolicy 
public addToPolicy(statement: PolicyStatement): boolean

Add to the policy of this principal.

statementRequired
  • Type: aws-cdk-lib.aws_iam.PolicyStatement
addToPrincipalPolicy 
public addToPrincipalPolicy(statement: PolicyStatement): AddToPrincipalPolicyResult

Adds a permission to the role's default policy document.

If there is no default policy attached to this role, it will be created.

statementRequired
  • Type: aws-cdk-lib.aws_iam.PolicyStatement

The permission statement to add to the policy document.

attachInlinePolicy 
public attachInlinePolicy(policy: Policy): void

Attaches a policy to this role.

policyRequired
  • Type: aws-cdk-lib.aws_iam.Policy

The policy to attach.

grant 
public grant(grantee: IPrincipal, actions: ...string[]): Grant

Grant the actions defined in actions to the identity Principal on this resource.

granteeRequired
  • Type: aws-cdk-lib.aws_iam.IPrincipal
actionsRequired
  • Type: ...string[]
grantAssumeRole 
public grantAssumeRole(identity: IPrincipal): Grant

Grant permissions to the given principal to assume this role.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IPrincipal
grantPassRole 
public grantPassRole(identity: IPrincipal): Grant

Grant permissions to the given principal to pass this role.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IPrincipal
withoutPolicyUpdates 
public withoutPolicyUpdates(options?: WithoutPolicyUpdatesOptions): IRole

Return a copy of this Role object whose Policies will not be updated.

Use the object returned by this method if you want this Role to be used by a construct without it automatically updating the Role's Policies.

If you do, you are responsible for adding the correct statements to the Role's policies yourself.

optionsOptional
  • Type: aws-cdk-lib.aws_iam.WithoutPolicyUpdatesOptions

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
customizeRoles Customize the creation of IAM roles within the given scope.
fromLookup Lookup an existing Role.
fromRoleArn Import an external role by ARN.
fromRoleName Import an external role by name.
isRole Return whether the given object is a Role.
isConstruct 
import { GithubActionsRole } from 'aws-cdk-github-oidc'

GithubActionsRole.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { GithubActionsRole } from 'aws-cdk-github-oidc'

GithubActionsRole.isOwnedResource(construct: IConstruct)

Returns true if the construct was created by CDK, and false otherwise.

constructRequired
  • Type: constructs.IConstruct
isResource 
import { GithubActionsRole } from 'aws-cdk-github-oidc'

GithubActionsRole.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
customizeRoles 
import { GithubActionsRole } from 'aws-cdk-github-oidc'

GithubActionsRole.customizeRoles(scope: Construct, options?: CustomizeRolesOptions)

Customize the creation of IAM roles within the given scope.

It is recommended that you do not use this method and instead allow CDK to manage role creation. This should only be used in environments where CDK applications are not allowed to created IAM roles.

This can be used to prevent the CDK application from creating roles within the given scope and instead replace the references to the roles with precreated role names. A report will be synthesized in the cloud assembly (i.e. cdk.out) that will contain the list of IAM roles that would have been created along with the IAM policy statements that the role should contain. This report can then be used to create the IAM roles outside of CDK and then the created role names can be provided in usePrecreatedRoles.

Example

declare const app: App;
iam.Role.customizeRoles(app, {
  usePrecreatedRoles: {
    'ConstructPath/To/Role': 'my-precreated-role-name',
  },
});
scopeRequired
  • Type: constructs.Construct

construct scope to customize role creation.

optionsOptional
  • Type: aws-cdk-lib.aws_iam.CustomizeRolesOptions

options for configuring role creation.

fromLookup 
import { GithubActionsRole } from 'aws-cdk-github-oidc'

GithubActionsRole.fromLookup(scope: Construct, id: string, options: RoleLookupOptions)

Lookup an existing Role.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
optionsRequired
  • Type: aws-cdk-lib.aws_iam.RoleLookupOptions
fromRoleArn 
import { GithubActionsRole } from 'aws-cdk-github-oidc'

GithubActionsRole.fromRoleArn(scope: Construct, id: string, roleArn: string, options?: FromRoleArnOptions)

Import an external role by ARN.

If the imported Role ARN is a Token (such as a CfnParameter.valueAsString or a Fn.importValue()) and the referenced role has a path (like arn:...:role/AdminRoles/Alice), the roleName property will not resolve to the correct value. Instead it will resolve to the first path component. We unfortunately cannot express the correct calculation of the full path name as a CloudFormation expression. In this scenario the Role ARN should be supplied without the path in order to resolve the correct role resource.

scopeRequired
  • Type: constructs.Construct

construct scope.

idRequired
  • Type: string

construct id.

roleArnRequired
  • Type: string

the ARN of the role to import.

optionsOptional
  • Type: aws-cdk-lib.aws_iam.FromRoleArnOptions

allow customizing the behavior of the returned role.

fromRoleName 
import { GithubActionsRole } from 'aws-cdk-github-oidc'

GithubActionsRole.fromRoleName(scope: Construct, id: string, roleName: string, options?: FromRoleNameOptions)

Import an external role by name.

The imported role is assumed to exist in the same account as the account the scope's containing Stack is being deployed to.

scopeRequired
  • Type: constructs.Construct

construct scope.

idRequired
  • Type: string

construct id.

roleNameRequired
  • Type: string

the name of the role to import.

optionsOptional
  • Type: aws-cdk-lib.aws_iam.FromRoleNameOptions

allow customizing the behavior of the returned role.

isRole 
import { GithubActionsRole } from 'aws-cdk-github-oidc'

GithubActionsRole.isRole(x: any)

Return whether the given object is a Role.

xRequired
  • Type: any

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.interfaces.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
assumeRoleAction string When this Principal is used in an AssumeRole policy, the action to use.
grantPrincipal aws-cdk-lib.aws_iam.IPrincipal The principal to grant permissions to.
grants aws-cdk-lib.aws_iam.RoleGrants Collection of grant methods for a Role.
policyFragment aws-cdk-lib.aws_iam.PrincipalPolicyFragment Returns the role.
roleArn string Returns the ARN of this role.
roleId string Returns the stable and unique string identifying the role.
roleName string Returns the name of the role.
roleRef aws-cdk-lib.interfaces.aws_iam.RoleReference A reference to a Role resource.
assumeRolePolicy aws-cdk-lib.aws_iam.PolicyDocument The assume role policy document associated with this role.
permissionsBoundary aws-cdk-lib.aws_iam.IManagedPolicy Returns the permissions boundary attached to this role.
principalAccount string The AWS account ID of this principal.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.interfaces.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed in a Stack (those created by creating new class instances like new Role(), new Bucket(), etc.), this is always the same as the environment of the stack they belong to.

For referenced resources (those obtained from referencing methods like Role.fromRoleArn(), Bucket.fromBucketName(), etc.), they might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

assumeRoleActionRequired 
public readonly assumeRoleAction: string;
  • Type: string

When this Principal is used in an AssumeRole policy, the action to use.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

The principal to grant permissions to.

grantsRequired 
public readonly grants: RoleGrants;
  • Type: aws-cdk-lib.aws_iam.RoleGrants

Collection of grant methods for a Role.

policyFragmentRequired 
public readonly policyFragment: PrincipalPolicyFragment;
  • Type: aws-cdk-lib.aws_iam.PrincipalPolicyFragment

Returns the role.

roleArnRequired 
public readonly roleArn: string;
  • Type: string

Returns the ARN of this role.

roleIdRequired 
public readonly roleId: string;
  • Type: string

Returns the stable and unique string identifying the role.

For example, AIDAJQABLZS4A3QDU576Q.

roleNameRequired 
public readonly roleName: string;
  • Type: string

Returns the name of the role.

roleRefRequired 
public readonly roleRef: RoleReference;
  • Type: aws-cdk-lib.interfaces.aws_iam.RoleReference

A reference to a Role resource.

assumeRolePolicyOptional 
public readonly assumeRolePolicy: PolicyDocument;
  • Type: aws-cdk-lib.aws_iam.PolicyDocument

The assume role policy document associated with this role.

permissionsBoundaryOptional 
public readonly permissionsBoundary: IManagedPolicy;
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy

Returns the permissions boundary attached to this role.

principalAccountOptional 
public readonly principalAccount: string;
  • Type: string

The AWS account ID of this principal.

Can be undefined when the account is not known (for example, for service principals). Can be a Token - in that case, it's assumed to be AWS::AccountId.

Constants

Name Type Description
PROPERTY_INJECTION_ID string Uniquely identifies this class.
PROPERTY_INJECTION_IDRequired 
public readonly PROPERTY_INJECTION_ID: string;
  • Type: string

Uniquely identifies this class.

Structs

GithubActionsIdentityProviderProps

Initializer 

import { GithubActionsIdentityProviderProps } from 'aws-cdk-github-oidc'

const githubActionsIdentityProviderProps: GithubActionsIdentityProviderProps = { ... }

Properties

Name Type Description
removalPolicy aws-cdk-lib.RemovalPolicy The removal policy for the provider.
removalPolicyOptional 
public readonly removalPolicy: RemovalPolicy;
  • Type: aws-cdk-lib.RemovalPolicy
  • Default: cdk.RemovalPolicy.DESTROY

The removal policy for the provider.

GithubActionsRoleProps

Props that define the IAM Role that can be assumed by Github Actions workflow via Github OpenID Connect Identity Provider.

Besides GithubConfiguration, you may pass in any iam.RoleProps except assumedBy which will be defined by this construct (CDK will fail if you do).

Example

{
  provider: GithubActionsIdentityProvider.fromAccount(scope, "GithubProvider"),
  owner: 'octo-org',
  repo: 'octo-repo',
  filter: 'ref:refs/tags/v*',
  roleName: 'MyDeployRole',
}

Initializer 

import { GithubActionsRoleProps } from 'aws-cdk-github-oidc'

const githubActionsRoleProps: GithubActionsRoleProps = { ... }

Properties

Name Type Description
owner string Repository owner (organization or username).
provider IGithubActionsIdentityProvider Reference to Github OpenID Connect Provider configured in AWS IAM.
repo string Repository name (slug) without the owner.
filter string Subject condition filter, appended after repo:${owner}/${repo}: string in IAM Role trust relationship.
ownerId string Numeric Github ID of the repository owner (organization or user), which makes the subject immutable.
repoId string Numeric Github ID of the repository, which makes the subject immutable.
description string A description of the role.
externalIds string[] List of IDs that the role assumer needs to provide one of when assuming this role.
inlinePolicies {[ key: string ]: aws-cdk-lib.aws_iam.PolicyDocument} A list of named policies to inline into this role.
managedPolicies aws-cdk-lib.aws_iam.IManagedPolicy[] A list of managed policies associated with this role.
maxSessionDuration aws-cdk-lib.Duration The maximum session duration that you want to set for the specified role.
path string The path associated with this role.
permissionsBoundary aws-cdk-lib.aws_iam.IManagedPolicy AWS supports permissions boundaries for IAM entities (users or roles).
roleName string A name for the IAM role.
ownerRequired 
public readonly owner: string;
  • Type: string

Repository owner (organization or username).

Example

'octo-org'
providerRequired 
public readonly provider: IGithubActionsIdentityProvider;

Reference to Github OpenID Connect Provider configured in AWS IAM.

Either pass an construct defined by new GithubActionsIdentityProvider or a retrieved reference from GithubActionsIdentityProvider.fromAccount. There can be only one (per AWS Account).

repoRequired 
public readonly repo: string;
  • Type: string

Repository name (slug) without the owner.

Example

'octo-repo'
filterOptional 
public readonly filter: string;
  • Type: string
  • Default: '*' You may use this value to only allow Github to assume the role on specific branches, tags, environments, pull requests etc.

Subject condition filter, appended after repo:${owner}/${repo}: string in IAM Role trust relationship.

With ownerId & repoId given, appended after repo:${owner}@${ownerId}/${repo}@${repoId}: instead.

https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#examples

Example

'ref:refs/tags/v*'
'ref:refs/heads/demo-branch'
'pull_request'
'environment:Production'
ownerIdOptional 
public readonly ownerId: string;
  • Type: string
  • Default: subject refers to the owner and repository by name

Numeric Github ID of the repository owner (organization or user), which makes the subject immutable.

Must be given together with repoId.

https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims

Example

'123456'
repoIdOptional 
public readonly repoId: string;
  • Type: string
  • Default: subject refers to the owner and repository by name

Numeric Github ID of the repository, which makes the subject immutable.

Must be given together with ownerId.

https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims

Example

'456789'
descriptionOptional 
public readonly description: string;
  • Type: string
  • Default: No description.

A description of the role.

It can be up to 1000 characters long.

externalIdsOptional 
public readonly externalIds: string[];
  • Type: string[]
  • Default: No external ID required

List of IDs that the role assumer needs to provide one of when assuming this role.

If the configured and provided external IDs do not match, the AssumeRole operation will fail.

inlinePoliciesOptional 
public readonly inlinePolicies: {[ key: string ]: PolicyDocument};
  • Type: {[ key: string ]: aws-cdk-lib.aws_iam.PolicyDocument}
  • Default: No policy is inlined in the Role resource.

A list of named policies to inline into this role.

These policies will be created with the role, whereas those added by addToPolicy are added using a separate CloudFormation resource (allowing a way around circular dependencies that could otherwise be introduced).

managedPoliciesOptional 
public readonly managedPolicies: IManagedPolicy[];
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy[]
  • Default: No managed policies.

A list of managed policies associated with this role.

You can add managed policies later using addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName)).

maxSessionDurationOptional 
public readonly maxSessionDuration: Duration;
  • Type: aws-cdk-lib.Duration
  • Default: Duration.hours(1)

The maximum session duration that you want to set for the specified role.

This setting can have a value from 1 hour (3600sec) to 12 (43200sec) hours.

Anyone who assumes the role from the AWS CLI or API can use the DurationSeconds API parameter or the duration-seconds CLI parameter to request a longer session. The MaxSessionDuration setting determines the maximum duration that can be requested using the DurationSeconds parameter.

If users don't specify a value for the DurationSeconds parameter, their security credentials are valid for one hour by default. This applies when you use the AssumeRole* API operations or the assume-role* CLI operations but does not apply when you use those operations to create a console URL.

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

pathOptional 
public readonly path: string;
  • Type: string
  • Default: /

The path associated with this role.

For information about IAM paths, see Friendly Names and Paths in IAM User Guide.

permissionsBoundaryOptional 
public readonly permissionsBoundary: IManagedPolicy;
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy
  • Default: No permissions boundary.

AWS supports permissions boundaries for IAM entities (users or roles).

A permissions boundary is an advanced feature for using a managed policy to set the maximum permissions that an identity-based policy can grant to an IAM entity. An entity's permissions boundary allows it to perform only the actions that are allowed by both its identity-based policies and its permissions boundaries.

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html

roleNameOptional 
public readonly roleName: string;
  • Type: string
  • Default: AWS CloudFormation generates a unique physical ID and uses that ID for the role name.

A name for the IAM role.

For valid values, see the RoleName parameter for the CreateRole action in the IAM API Reference.

IMPORTANT: If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name.

If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template's capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

GithubConfiguration

Github related configuration that forms the trust policy for this IAM Role.

Initializer 

import { GithubConfiguration } from 'aws-cdk-github-oidc'

const githubConfiguration: GithubConfiguration = { ... }

Properties

Name Type Description
owner string Repository owner (organization or username).
provider IGithubActionsIdentityProvider Reference to Github OpenID Connect Provider configured in AWS IAM.
repo string Repository name (slug) without the owner.
filter string Subject condition filter, appended after repo:${owner}/${repo}: string in IAM Role trust relationship.
ownerId string Numeric Github ID of the repository owner (organization or user), which makes the subject immutable.
repoId string Numeric Github ID of the repository, which makes the subject immutable.
ownerRequired 
public readonly owner: string;
  • Type: string

Repository owner (organization or username).

Example

'octo-org'
providerRequired 
public readonly provider: IGithubActionsIdentityProvider;

Reference to Github OpenID Connect Provider configured in AWS IAM.

Either pass an construct defined by new GithubActionsIdentityProvider or a retrieved reference from GithubActionsIdentityProvider.fromAccount. There can be only one (per AWS Account).

repoRequired 
public readonly repo: string;
  • Type: string

Repository name (slug) without the owner.

Example

'octo-repo'
filterOptional 
public readonly filter: string;
  • Type: string
  • Default: '*' You may use this value to only allow Github to assume the role on specific branches, tags, environments, pull requests etc.

Subject condition filter, appended after repo:${owner}/${repo}: string in IAM Role trust relationship.

With ownerId & repoId given, appended after repo:${owner}@${ownerId}/${repo}@${repoId}: instead.

https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#examples

Example

'ref:refs/tags/v*'
'ref:refs/heads/demo-branch'
'pull_request'
'environment:Production'
ownerIdOptional 
public readonly ownerId: string;
  • Type: string
  • Default: subject refers to the owner and repository by name

Numeric Github ID of the repository owner (organization or user), which makes the subject immutable.

Must be given together with repoId.

https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims

Example

'123456'
repoIdOptional 
public readonly repoId: string;
  • Type: string
  • Default: subject refers to the owner and repository by name

Numeric Github ID of the repository, which makes the subject immutable.

Must be given together with ownerId.

https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims

Example

'456789'

RoleProps

Properties for defining an IAM Role.

These are copied fron

Initializer 

import { RoleProps } from 'aws-cdk-github-oidc'

const roleProps: RoleProps = { ... }

Properties

Name Type Description
description string A description of the role.
externalIds string[] List of IDs that the role assumer needs to provide one of when assuming this role.
inlinePolicies {[ key: string ]: aws-cdk-lib.aws_iam.PolicyDocument} A list of named policies to inline into this role.
managedPolicies aws-cdk-lib.aws_iam.IManagedPolicy[] A list of managed policies associated with this role.
maxSessionDuration aws-cdk-lib.Duration The maximum session duration that you want to set for the specified role.
path string The path associated with this role.
permissionsBoundary aws-cdk-lib.aws_iam.IManagedPolicy AWS supports permissions boundaries for IAM entities (users or roles).
roleName string A name for the IAM role.
descriptionOptional 
public readonly description: string;
  • Type: string
  • Default: No description.

A description of the role.

It can be up to 1000 characters long.

externalIdsOptional 
public readonly externalIds: string[];
  • Type: string[]
  • Default: No external ID required

List of IDs that the role assumer needs to provide one of when assuming this role.

If the configured and provided external IDs do not match, the AssumeRole operation will fail.

inlinePoliciesOptional 
public readonly inlinePolicies: {[ key: string ]: PolicyDocument};
  • Type: {[ key: string ]: aws-cdk-lib.aws_iam.PolicyDocument}
  • Default: No policy is inlined in the Role resource.

A list of named policies to inline into this role.

These policies will be created with the role, whereas those added by addToPolicy are added using a separate CloudFormation resource (allowing a way around circular dependencies that could otherwise be introduced).

managedPoliciesOptional 
public readonly managedPolicies: IManagedPolicy[];
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy[]
  • Default: No managed policies.

A list of managed policies associated with this role.

You can add managed policies later using addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName)).

maxSessionDurationOptional 
public readonly maxSessionDuration: Duration;
  • Type: aws-cdk-lib.Duration
  • Default: Duration.hours(1)

The maximum session duration that you want to set for the specified role.

This setting can have a value from 1 hour (3600sec) to 12 (43200sec) hours.

Anyone who assumes the role from the AWS CLI or API can use the DurationSeconds API parameter or the duration-seconds CLI parameter to request a longer session. The MaxSessionDuration setting determines the maximum duration that can be requested using the DurationSeconds parameter.

If users don't specify a value for the DurationSeconds parameter, their security credentials are valid for one hour by default. This applies when you use the AssumeRole* API operations or the assume-role* CLI operations but does not apply when you use those operations to create a console URL.

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html

pathOptional 
public readonly path: string;
  • Type: string
  • Default: /

The path associated with this role.

For information about IAM paths, see Friendly Names and Paths in IAM User Guide.

permissionsBoundaryOptional 
public readonly permissionsBoundary: IManagedPolicy;
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy
  • Default: No permissions boundary.

AWS supports permissions boundaries for IAM entities (users or roles).

A permissions boundary is an advanced feature for using a managed policy to set the maximum permissions that an identity-based policy can grant to an IAM entity. An entity's permissions boundary allows it to perform only the actions that are allowed by both its identity-based policies and its permissions boundaries.

https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html

roleNameOptional 
public readonly roleName: string;
  • Type: string
  • Default: AWS CloudFormation generates a unique physical ID and uses that ID for the role name.

A name for the IAM role.

For valid values, see the RoleName parameter for the CreateRole action in the IAM API Reference.

IMPORTANT: If you specify a name, you cannot perform updates that require replacement of this resource. You can perform updates that require no or some interruption. If you must replace the resource, specify a new name.

If you specify a name, you must specify the CAPABILITY_NAMED_IAM value to acknowledge your template's capabilities. For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

Protocols

IGithubActionsIdentityProvider

Describes a Github OpenID Connect Identity Provider for AWS IAM.

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.interfaces.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
oidcProviderRef aws-cdk-lib.interfaces.aws_iam.OIDCProviderReference A reference to a OIDCProvider resource.
oidcProviderArn string The Amazon Resource Name (ARN) of the IAM OpenID Connect provider.
oidcProviderIssuer string The issuer for OIDC Provider.
openIdConnectProviderArn string Alias for oidcProviderArn to maintain backwards compatibility for constructs which accept iam.IOpenIdConnectProvider.
openIdConnectProviderIssuer string Alias for oidcProviderIssuer to maintain backwards compatibility for constructs which accept `iam.IOpenIdConnectProvider.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.interfaces.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed in a Stack (those created by creating new class instances like new Role(), new Bucket(), etc.), this is always the same as the environment of the stack they belong to.

For referenced resources (those obtained from referencing methods like Role.fromRoleArn(), Bucket.fromBucketName(), etc.), they might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

oidcProviderRefRequired 
public readonly oidcProviderRef: OIDCProviderReference;
  • Type: aws-cdk-lib.interfaces.aws_iam.OIDCProviderReference

A reference to a OIDCProvider resource.

oidcProviderArnRequired 
public readonly oidcProviderArn: string;
  • Type: string

The Amazon Resource Name (ARN) of the IAM OpenID Connect provider.

oidcProviderIssuerRequired 
public readonly oidcProviderIssuer: string;
  • Type: string

The issuer for OIDC Provider.

openIdConnectProviderArnRequired 
public readonly openIdConnectProviderArn: string;
  • Type: string

Alias for oidcProviderArn to maintain backwards compatibility for constructs which accept iam.IOpenIdConnectProvider.

Use oidcProviderArn instead. This property exists for backward compatibility with existing constructs as migrating between the 2 constructs (OpenIdConnectProvider and OidcProviderNative) is not reasonably feasible as it requires a manual step (cdk import) since the resource type is changing between OpenIdConnectProvider and OidcProviderNative.

openIdConnectProviderIssuerRequired 
public readonly openIdConnectProviderIssuer: string;
  • Type: string

Alias for oidcProviderIssuer to maintain backwards compatibility for constructs which accept `iam.IOpenIdConnectProvider.

Use oidcProviderIssuer instead. This property exists for backward compatibility with existing constructs as migrating between the 2 constructs (OpenIdConnectProvider and OidcProviderNative) is not reasonably feasible as it requires a manual step (cdk import) since the resource type is changing between OpenIdConnectProvider and OidcProviderNative.