# API Reference
## Constructs
### GithubActionsIdentityProvider
- *Implements:* IGithubActionsIdentityProvider
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](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
#### Initializers
```typescript
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. |
---
##### `scope`Required
- *Type:* constructs.Construct
CDK Stack or Construct to which the provider is assigned to.
---
##### `id`Required
- *Type:* string
CDK Construct ID given to the construct.
---
##### `props`Optional
- *Type:* GithubActionsIdentityProviderProps
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`
```typescript
public toString(): string
```
Returns a string representation of this construct.
##### `with`
```typescript
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.
###### `mixins`Required
- *Type:* ...constructs.IMixin[]
---
##### `applyCrossStackReferenceStrength`
```typescript
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.
###### `strength`Required
- *Type:* aws-cdk-lib.ReferenceStrength
The reference strength to use for this resource.
---
##### `applyRemovalPolicy`
```typescript
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`).
###### `policy`Required
- *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`
```typescript
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.
###### `x`Required
- *Type:* any
Any object.
---
##### `isOwnedResource`
```typescript
import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'
GithubActionsIdentityProvider.isOwnedResource(construct: IConstruct)
```
Returns true if the construct was created by CDK, and false otherwise.
###### `construct`Required
- *Type:* constructs.IConstruct
---
##### `isResource`
```typescript
import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'
GithubActionsIdentityProvider.isResource(construct: IConstruct)
```
Check whether the given construct is a Resource.
###### `construct`Required
- *Type:* constructs.IConstruct
---
##### `fromOidcProviderArn`
```typescript
import { GithubActionsIdentityProvider } from 'aws-cdk-github-oidc'
GithubActionsIdentityProvider.fromOidcProviderArn(scope: Construct, id: string, oidcProviderArn: string)
```
Imports an Open ID connect provider from an ARN.
###### `scope`Required
- *Type:* constructs.Construct
The definition scope.
---
###### `id`Required
- *Type:* string
ID of the construct.
---
###### `oidcProviderArn`Required
- *Type:* string
the ARN to import.
---
##### `fromAccount`
```typescript
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*
```typescript
GithubActionsIdentityProvider.fromAccount(scope, "GithubProvider");
```
###### `scope`Required
- *Type:* constructs.Construct
CDK Stack or Construct to which the provider is assigned to.
---
###### `id`Required
- *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. |
---
##### `node`Required
```typescript
public readonly node: Node;
```
- *Type:* constructs.Node
The tree node.
---
##### `env`Required
```typescript
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.
---
##### `stack`Required
```typescript
public readonly stack: Stack;
```
- *Type:* aws-cdk-lib.Stack
The stack in which this resource is defined.
---
##### `oidcProviderArn`Required
```typescript
public readonly oidcProviderArn: string;
```
- *Type:* string
The Amazon Resource Name (ARN) of the Native IAM OpenID Connect provider.
---
##### `oidcProviderIssuer`Required
```typescript
public readonly oidcProviderIssuer: string;
```
- *Type:* string
The issuer for the Native OIDC Provider.
---
##### `oidcProviderRef`Required
```typescript
public readonly oidcProviderRef: OIDCProviderReference;
```
- *Type:* aws-cdk-lib.interfaces.aws_iam.OIDCProviderReference
A reference to a OIDCProvider resource.
---
##### `oidcProviderThumbprints`Required
```typescript
public readonly oidcProviderThumbprints: string;
```
- *Type:* string
The thumbprints configured for this provider.
---
##### `openIdConnectProviderArn`Required
```typescript
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.
---
##### `openIdConnectProviderIssuer`Required
```typescript
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_ID`Required
```typescript
public readonly PROPERTY_INJECTION_ID: string;
```
- *Type:* string
Uniquely identifies this class.
---
##### `issuer`Required
```typescript
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*
```typescript
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
```typescript
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.* |
---
##### `scope`Required
- *Type:* constructs.Construct
---
##### `id`Required
- *Type:* string
---
##### `props`Required
- *Type:* GithubActionsRoleProps
---
#### 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`
```typescript
public toString(): string
```
Returns a string representation of this construct.
##### `with`
```typescript
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.
###### `mixins`Required
- *Type:* ...constructs.IMixin[]
---
##### `applyCrossStackReferenceStrength`
```typescript
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.
###### `strength`Required
- *Type:* aws-cdk-lib.ReferenceStrength
The reference strength to use for this resource.
---
##### `applyRemovalPolicy`
```typescript
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.
###### `policy`Required
- *Type:* aws-cdk-lib.RemovalPolicy
RemovalPolicy.
---
##### `addManagedPolicy`
```typescript
public addManagedPolicy(policy: IManagedPolicy): void
```
Attaches a managed policy to this role.
###### `policy`Required
- *Type:* aws-cdk-lib.aws_iam.IManagedPolicy
The the managed policy to attach.
---
##### `addToPolicy`
```typescript
public addToPolicy(statement: PolicyStatement): boolean
```
Add to the policy of this principal.
###### `statement`Required
- *Type:* aws-cdk-lib.aws_iam.PolicyStatement
---
##### `addToPrincipalPolicy`
```typescript
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.
###### `statement`Required
- *Type:* aws-cdk-lib.aws_iam.PolicyStatement
The permission statement to add to the policy document.
---
##### `attachInlinePolicy`
```typescript
public attachInlinePolicy(policy: Policy): void
```
Attaches a policy to this role.
###### `policy`Required
- *Type:* aws-cdk-lib.aws_iam.Policy
The policy to attach.
---
##### `grant`
```typescript
public grant(grantee: IPrincipal, actions: ...string[]): Grant
```
Grant the actions defined in actions to the identity Principal on this resource.
###### `grantee`Required
- *Type:* aws-cdk-lib.aws_iam.IPrincipal
---
###### `actions`Required
- *Type:* ...string[]
---
##### `grantAssumeRole`
```typescript
public grantAssumeRole(identity: IPrincipal): Grant
```
Grant permissions to the given principal to assume this role.
###### `identity`Required
- *Type:* aws-cdk-lib.aws_iam.IPrincipal
---
##### `grantPassRole`
```typescript
public grantPassRole(identity: IPrincipal): Grant
```
Grant permissions to the given principal to pass this role.
###### `identity`Required
- *Type:* aws-cdk-lib.aws_iam.IPrincipal
---
##### `withoutPolicyUpdates`
```typescript
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.
###### `options`Optional
- *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`
```typescript
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.
###### `x`Required
- *Type:* any
Any object.
---
##### `isOwnedResource`
```typescript
import { GithubActionsRole } from 'aws-cdk-github-oidc'
GithubActionsRole.isOwnedResource(construct: IConstruct)
```
Returns true if the construct was created by CDK, and false otherwise.
###### `construct`Required
- *Type:* constructs.IConstruct
---
##### `isResource`
```typescript
import { GithubActionsRole } from 'aws-cdk-github-oidc'
GithubActionsRole.isResource(construct: IConstruct)
```
Check whether the given construct is a Resource.
###### `construct`Required
- *Type:* constructs.IConstruct
---
##### `customizeRoles`
```typescript
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*
```typescript
declare const app: App;
iam.Role.customizeRoles(app, {
usePrecreatedRoles: {
'ConstructPath/To/Role': 'my-precreated-role-name',
},
});
```
###### `scope`Required
- *Type:* constructs.Construct
construct scope to customize role creation.
---
###### `options`Optional
- *Type:* aws-cdk-lib.aws_iam.CustomizeRolesOptions
options for configuring role creation.
---
##### `fromLookup`
```typescript
import { GithubActionsRole } from 'aws-cdk-github-oidc'
GithubActionsRole.fromLookup(scope: Construct, id: string, options: RoleLookupOptions)
```
Lookup an existing Role.
###### `scope`Required
- *Type:* constructs.Construct
---
###### `id`Required
- *Type:* string
---
###### `options`Required
- *Type:* aws-cdk-lib.aws_iam.RoleLookupOptions
---
##### `fromRoleArn`
```typescript
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.
###### `scope`Required
- *Type:* constructs.Construct
construct scope.
---
###### `id`Required
- *Type:* string
construct id.
---
###### `roleArn`Required
- *Type:* string
the ARN of the role to import.
---
###### `options`Optional
- *Type:* aws-cdk-lib.aws_iam.FromRoleArnOptions
allow customizing the behavior of the returned role.
---
##### `fromRoleName`
```typescript
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.
###### `scope`Required
- *Type:* constructs.Construct
construct scope.
---
###### `id`Required
- *Type:* string
construct id.
---
###### `roleName`Required
- *Type:* string
the name of the role to import.
---
###### `options`Optional
- *Type:* aws-cdk-lib.aws_iam.FromRoleNameOptions
allow customizing the behavior of the returned role.
---
##### `isRole`
```typescript
import { GithubActionsRole } from 'aws-cdk-github-oidc'
GithubActionsRole.isRole(x: any)
```
Return whether the given object is a Role.
###### `x`Required
- *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. |
---
##### `node`Required
```typescript
public readonly node: Node;
```
- *Type:* constructs.Node
The tree node.
---
##### `env`Required
```typescript
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.
---
##### `stack`Required
```typescript
public readonly stack: Stack;
```
- *Type:* aws-cdk-lib.Stack
The stack in which this resource is defined.
---
##### `assumeRoleAction`Required
```typescript
public readonly assumeRoleAction: string;
```
- *Type:* string
When this Principal is used in an AssumeRole policy, the action to use.
---
##### `grantPrincipal`Required
```typescript
public readonly grantPrincipal: IPrincipal;
```
- *Type:* aws-cdk-lib.aws_iam.IPrincipal
The principal to grant permissions to.
---
##### `grants`Required
```typescript
public readonly grants: RoleGrants;
```
- *Type:* aws-cdk-lib.aws_iam.RoleGrants
Collection of grant methods for a Role.
---
##### `policyFragment`Required
```typescript
public readonly policyFragment: PrincipalPolicyFragment;
```
- *Type:* aws-cdk-lib.aws_iam.PrincipalPolicyFragment
Returns the role.
---
##### `roleArn`Required
```typescript
public readonly roleArn: string;
```
- *Type:* string
Returns the ARN of this role.
---
##### `roleId`Required
```typescript
public readonly roleId: string;
```
- *Type:* string
Returns the stable and unique string identifying the role.
For example,
AIDAJQABLZS4A3QDU576Q.
---
##### `roleName`Required
```typescript
public readonly roleName: string;
```
- *Type:* string
Returns the name of the role.
---
##### `roleRef`Required
```typescript
public readonly roleRef: RoleReference;
```
- *Type:* aws-cdk-lib.interfaces.aws_iam.RoleReference
A reference to a Role resource.
---
##### `assumeRolePolicy`Optional
```typescript
public readonly assumeRolePolicy: PolicyDocument;
```
- *Type:* aws-cdk-lib.aws_iam.PolicyDocument
The assume role policy document associated with this role.
---
##### `permissionsBoundary`Optional
```typescript
public readonly permissionsBoundary: IManagedPolicy;
```
- *Type:* aws-cdk-lib.aws_iam.IManagedPolicy
Returns the permissions boundary attached to this role.
---
##### `principalAccount`Optional
```typescript
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_ID`Required
```typescript
public readonly PROPERTY_INJECTION_ID: string;
```
- *Type:* string
Uniquely identifies this class.
---
## Structs
### GithubActionsIdentityProviderProps
#### Initializer
```typescript
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. |
---
##### `removalPolicy`Optional
```typescript
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*
```typescript
{
provider: GithubActionsIdentityProvider.fromAccount(scope, "GithubProvider"),
owner: 'octo-org',
repo: 'octo-repo',
filter: 'ref:refs/tags/v*',
roleName: 'MyDeployRole',
}
```
#### Initializer
```typescript
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. |
---
##### `owner`Required
```typescript
public readonly owner: string;
```
- *Type:* string
Repository owner (organization or username).
---
*Example*
```typescript
'octo-org'
```
##### `provider`Required
```typescript
public readonly provider: IGithubActionsIdentityProvider;
```
- *Type:* 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).
---
##### `repo`Required
```typescript
public readonly repo: string;
```
- *Type:* string
Repository name (slug) without the owner.
---
*Example*
```typescript
'octo-repo'
```
##### `filter`Optional
```typescript
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](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#examples)
---
*Example*
```typescript
'ref:refs/tags/v*'
'ref:refs/heads/demo-branch'
'pull_request'
'environment:Production'
```
##### `ownerId`Optional
```typescript
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](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims)
---
*Example*
```typescript
'123456'
```
##### `repoId`Optional
```typescript
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](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims)
---
*Example*
```typescript
'456789'
```
##### `description`Optional
```typescript
public readonly description: string;
```
- *Type:* string
- *Default:* No description.
A description of the role.
It can be up to 1000 characters long.
---
##### `externalIds`Optional
```typescript
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.
---
##### `inlinePolicies`Optional
```typescript
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).
---
##### `managedPolicies`Optional
```typescript
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))`.
---
##### `maxSessionDuration`Optional
```typescript
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)
---
##### `path`Optional
```typescript
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.
---
##### `permissionsBoundary`Optional
```typescript
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)
---
##### `roleName`Optional
```typescript
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
```typescript
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. |
---
##### `owner`Required
```typescript
public readonly owner: string;
```
- *Type:* string
Repository owner (organization or username).
---
*Example*
```typescript
'octo-org'
```
##### `provider`Required
```typescript
public readonly provider: IGithubActionsIdentityProvider;
```
- *Type:* 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).
---
##### `repo`Required
```typescript
public readonly repo: string;
```
- *Type:* string
Repository name (slug) without the owner.
---
*Example*
```typescript
'octo-repo'
```
##### `filter`Optional
```typescript
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](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#examples)
---
*Example*
```typescript
'ref:refs/tags/v*'
'ref:refs/heads/demo-branch'
'pull_request'
'environment:Production'
```
##### `ownerId`Optional
```typescript
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](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims)
---
*Example*
```typescript
'123456'
```
##### `repoId`Optional
```typescript
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](https://docs.github.com/en/actions/reference/security/oidc#immutable-subject-claims)
---
*Example*
```typescript
'456789'
```
### RoleProps
Properties for defining an IAM Role.
These are copied fron
#### Initializer
```typescript
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. |
---
##### `description`Optional
```typescript
public readonly description: string;
```
- *Type:* string
- *Default:* No description.
A description of the role.
It can be up to 1000 characters long.
---
##### `externalIds`Optional
```typescript
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.
---
##### `inlinePolicies`Optional
```typescript
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).
---
##### `managedPolicies`Optional
```typescript
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))`.
---
##### `maxSessionDuration`Optional
```typescript
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)
---
##### `path`Optional
```typescript
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.
---
##### `permissionsBoundary`Optional
```typescript
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)
---
##### `roleName`Optional
```typescript
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
- *Extends:* aws-cdk-lib.aws_iam.IOidcProvider
- *Implemented By:* GithubActionsIdentityProvider, 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. |
---
##### `node`Required
```typescript
public readonly node: Node;
```
- *Type:* constructs.Node
The tree node.
---
##### `env`Required
```typescript
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.
---
##### `stack`Required
```typescript
public readonly stack: Stack;
```
- *Type:* aws-cdk-lib.Stack
The stack in which this resource is defined.
---
##### `oidcProviderRef`Required
```typescript
public readonly oidcProviderRef: OIDCProviderReference;
```
- *Type:* aws-cdk-lib.interfaces.aws_iam.OIDCProviderReference
A reference to a OIDCProvider resource.
---
##### `oidcProviderArn`Required
```typescript
public readonly oidcProviderArn: string;
```
- *Type:* string
The Amazon Resource Name (ARN) of the IAM OpenID Connect provider.
---
##### `oidcProviderIssuer`Required
```typescript
public readonly oidcProviderIssuer: string;
```
- *Type:* string
The issuer for OIDC Provider.
---
##### `openIdConnectProviderArn`Required
```typescript
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.
---
##### `openIdConnectProviderIssuer`Required
```typescript
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.
---