# API Reference
## Constructs
### CircleCiOidcProvider
- *Implements:* ICircleCiOidcProvider
This construct creates a CircleCI ODIC provider to allow AWS access from CircleCI jobs.
You'll need to instantiate
this construct once per AWS account you want to use CircleCI OIDC with.
You can import a existing provider using `CircleCiOidcProvider.fromOrganizationId`.
To create a role that can be assumed by CircleCI jobs, use the `CircleCiOidcRole` construct.
#### Initializers
```typescript
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'
new CircleCiOidcProvider(scope: Construct, id: string, props: CircleCiOidcProviderProps)
```
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| scope | constructs.Construct | *No description.* |
| id | string | *No description.* |
| props | CircleCiOidcProviderProps | *No description.* |
---
##### `scope`Required
- *Type:* constructs.Construct
---
##### `id`Required
- *Type:* string
---
##### `props`Required
- *Type:* CircleCiOidcProviderProps
---
#### Methods
| **Name** | **Description** |
| --- | --- |
| toString | Returns a string representation of this construct. |
| overrideLogicalId | Overrides the auto-generated logical ID with a specific ID. |
| addDeletionOverride | Syntactic sugar for `addOverride(path, undefined)`. |
| addDependency | Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned. |
| addDependsOn | Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned. |
| addMetadata | Add a value to the CloudFormation Resource Metadata. |
| addOverride | Adds an override to the synthesized CloudFormation resource. |
| addPropertyDeletionOverride | Adds an override that deletes the value of a property from the resource definition. |
| addPropertyOverride | Adds an override to a resource property. |
| applyRemovalPolicy | Sets the deletion policy of the resource based on the removal policy specified. |
| getAtt | Returns a token for an runtime attribute of this resource. |
| getMetadata | Retrieve a value value from the CloudFormation Resource Metadata. |
| obtainDependencies | Retrieves an array of resources this resource depends on. |
| obtainResourceDependencies | Get a shallow copy of dependencies between this resource and other resources in the same stack. |
| removeDependency | Indicates that this resource no longer depends on another resource. |
| replaceDependency | Replaces one dependency with another. |
| inspect | Examines the CloudFormation resource and discloses attributes. |
---
##### `toString`
```typescript
public toString(): string
```
Returns a string representation of this construct.
##### `overrideLogicalId`
```typescript
public overrideLogicalId(newLogicalId: string): void
```
Overrides the auto-generated logical ID with a specific ID.
###### `newLogicalId`Required
- *Type:* string
The new logical ID to use for this stack element.
---
##### `addDeletionOverride`
```typescript
public addDeletionOverride(path: string): void
```
Syntactic sugar for `addOverride(path, undefined)`.
###### `path`Required
- *Type:* string
The path of the value to delete.
---
##### `addDependency`
```typescript
public addDependency(target: CfnResource): void
```
Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned.
This can be used for resources across stacks (or nested stack) boundaries
and the dependency will automatically be transferred to the relevant scope.
###### `target`Required
- *Type:* aws-cdk-lib.CfnResource
---
##### ~~`addDependsOn`~~
```typescript
public addDependsOn(target: CfnResource): void
```
Indicates that this resource depends on another resource and cannot be provisioned unless the other resource has been successfully provisioned.
###### `target`Required
- *Type:* aws-cdk-lib.CfnResource
---
##### `addMetadata`
```typescript
public addMetadata(key: string, value: any): void
```
Add a value to the CloudFormation Resource Metadata.
> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html
Note that this is a different set of metadata from CDK node metadata; this
metadata ends up in the stack template under the resource, whereas CDK
node metadata ends up in the Cloud Assembly.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html
Note that this is a different set of metadata from CDK node metadata; this
metadata ends up in the stack template under the resource, whereas CDK
node metadata ends up in the Cloud Assembly.)
###### `key`Required
- *Type:* string
---
###### `value`Required
- *Type:* any
---
##### `addOverride`
```typescript
public addOverride(path: string, value: any): void
```
Adds an override to the synthesized CloudFormation resource.
To add a
property override, either use `addPropertyOverride` or prefix `path` with
"Properties." (i.e. `Properties.TopicName`).
If the override is nested, separate each nested level using a dot (.) in the path parameter.
If there is an array as part of the nesting, specify the index in the path.
To include a literal `.` in the property name, prefix with a `\`. In most
programming languages you will need to write this as `"\\."` because the
`\` itself will need to be escaped.
For example,
```typescript
cfnResource.addOverride('Properties.GlobalSecondaryIndexes.0.Projection.NonKeyAttributes', ['myattribute']);
cfnResource.addOverride('Properties.GlobalSecondaryIndexes.1.ProjectionType', 'INCLUDE');
```
would add the overrides
```json
"Properties": {
"GlobalSecondaryIndexes": [
{
"Projection": {
"NonKeyAttributes": [ "myattribute" ]
...
}
...
},
{
"ProjectionType": "INCLUDE"
...
},
]
...
}
```
The `value` argument to `addOverride` will not be processed or translated
in any way. Pass raw JSON values in here with the correct capitalization
for CloudFormation. If you pass CDK classes or structs, they will be
rendered with lowercased key names, and CloudFormation will reject the
template.
###### `path`Required
- *Type:* string
The path of the property, you can use dot notation to override values in complex types.
Any intermediate keys
will be created as needed.
---
###### `value`Required
- *Type:* any
The value.
Could be primitive or complex.
---
##### `addPropertyDeletionOverride`
```typescript
public addPropertyDeletionOverride(propertyPath: string): void
```
Adds an override that deletes the value of a property from the resource definition.
###### `propertyPath`Required
- *Type:* string
The path to the property.
---
##### `addPropertyOverride`
```typescript
public addPropertyOverride(propertyPath: string, value: any): void
```
Adds an override to a resource property.
Syntactic sugar for `addOverride("Properties.<...>", value)`.
###### `propertyPath`Required
- *Type:* string
The path of the property.
---
###### `value`Required
- *Type:* any
The value.
---
##### `applyRemovalPolicy`
```typescript
public applyRemovalPolicy(policy?: RemovalPolicy, options?: RemovalPolicyOptions): void
```
Sets the deletion policy of the resource based on the removal policy specified.
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`). In some
cases, a snapshot can be taken of the resource prior to deletion
(`RemovalPolicy.SNAPSHOT`). A list of resources that support this policy
can be found in the following link:
> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html#aws-attribute-deletionpolicy-options](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-deletionpolicy.html#aws-attribute-deletionpolicy-options)
###### `policy`Optional
- *Type:* aws-cdk-lib.RemovalPolicy
---
###### `options`Optional
- *Type:* aws-cdk-lib.RemovalPolicyOptions
---
##### `getAtt`
```typescript
public getAtt(attributeName: string, typeHint?: ResolutionTypeHint): Reference
```
Returns a token for an runtime attribute of this resource.
Ideally, use generated attribute accessors (e.g. `resource.arn`), but this can be used for future compatibility
in case there is no generated attribute.
###### `attributeName`Required
- *Type:* string
The name of the attribute.
---
###### `typeHint`Optional
- *Type:* aws-cdk-lib.ResolutionTypeHint
---
##### `getMetadata`
```typescript
public getMetadata(key: string): any
```
Retrieve a value value from the CloudFormation Resource Metadata.
> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html
Note that this is a different set of metadata from CDK node metadata; this
metadata ends up in the stack template under the resource, whereas CDK
node metadata ends up in the Cloud Assembly.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html
Note that this is a different set of metadata from CDK node metadata; this
metadata ends up in the stack template under the resource, whereas CDK
node metadata ends up in the Cloud Assembly.)
###### `key`Required
- *Type:* string
---
##### `obtainDependencies`
```typescript
public obtainDependencies(): Stack | CfnResource[]
```
Retrieves an array of resources this resource depends on.
This assembles dependencies on resources across stacks (including nested stacks)
automatically.
##### `obtainResourceDependencies`
```typescript
public obtainResourceDependencies(): CfnResource[]
```
Get a shallow copy of dependencies between this resource and other resources in the same stack.
##### `removeDependency`
```typescript
public removeDependency(target: CfnResource): void
```
Indicates that this resource no longer depends on another resource.
This can be used for resources across stacks (including nested stacks)
and the dependency will automatically be removed from the relevant scope.
###### `target`Required
- *Type:* aws-cdk-lib.CfnResource
---
##### `replaceDependency`
```typescript
public replaceDependency(target: CfnResource, newTarget: CfnResource): void
```
Replaces one dependency with another.
###### `target`Required
- *Type:* aws-cdk-lib.CfnResource
The dependency to replace.
---
###### `newTarget`Required
- *Type:* aws-cdk-lib.CfnResource
The new dependency to add.
---
##### `inspect`
```typescript
public inspect(inspector: TreeInspector): void
```
Examines the CloudFormation resource and discloses attributes.
###### `inspector`Required
- *Type:* aws-cdk-lib.TreeInspector
tree inspector to collect and process attributes.
---
#### Static Functions
| **Name** | **Description** |
| --- | --- |
| isConstruct | Checks if `x` is a construct. |
| isCfnElement | Returns `true` if a construct is a stack element (i.e. part of the synthesized cloudformation template). |
| isCfnResource | Check whether the given construct is a CfnResource. |
| fromOrganizationId | *No description.* |
---
##### ~~`isConstruct`~~
```typescript
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcProvider.isConstruct(x: any)
```
Checks if `x` is a construct.
###### `x`Required
- *Type:* any
Any object.
---
##### `isCfnElement`
```typescript
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcProvider.isCfnElement(x: any)
```
Returns `true` if a construct is a stack element (i.e. part of the synthesized cloudformation template).
Uses duck-typing instead of `instanceof` to allow stack elements from different
versions of this library to be included in the same stack.
###### `x`Required
- *Type:* any
---
##### `isCfnResource`
```typescript
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcProvider.isCfnResource(construct: IConstruct)
```
Check whether the given construct is a CfnResource.
###### `construct`Required
- *Type:* constructs.IConstruct
---
##### `fromOrganizationId`
```typescript
import { CircleCiOidcProvider } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcProvider.fromOrganizationId(scope: Construct, organizationId: string)
```
###### `scope`Required
- *Type:* constructs.Construct
---
###### `organizationId`Required
- *Type:* string
---
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| node | constructs.Node | The tree node. |
| creationStack | string[] | *No description.* |
| logicalId | string | The logical ID for this CloudFormation stack element. |
| stack | aws-cdk-lib.Stack | The stack in which this element is defined. |
| ref | string | Return a string that will be resolved to a CloudFormation `{ Ref }` for this element. |
| cfnOptions | aws-cdk-lib.ICfnResourceOptions | Options for this resource, such as condition, update policy etc. |
| cfnResourceType | string | AWS resource type. |
| attrArn | string | Returns the Amazon Resource Name (ARN) for the specified `AWS::IAM::OIDCProvider` resource. |
| tags | aws-cdk-lib.TagManager | A list of tags that are attached to the specified IAM OIDC provider. |
| thumbprintList | string[] | A list of certificate thumbprints that are associated with the specified IAM OIDC provider resource object. |
| clientIdList | string[] | A list of client IDs (also known as audiences) that are associated with the specified IAM OIDC provider resource object. |
| url | string | The URL that the IAM OIDC provider resource object is associated with. |
| arn | string | *No description.* |
| organizationId | string | *No description.* |
---
##### `node`Required
```typescript
public readonly node: Node;
```
- *Type:* constructs.Node
The tree node.
---
##### `creationStack`Required
```typescript
public readonly creationStack: string[];
```
- *Type:* string[]
---
##### `logicalId`Required
```typescript
public readonly logicalId: string;
```
- *Type:* string
The logical ID for this CloudFormation stack element.
The logical ID of the element
is calculated from the path of the resource node in the construct tree.
To override this value, use `overrideLogicalId(newLogicalId)`.
---
##### `stack`Required
```typescript
public readonly stack: Stack;
```
- *Type:* aws-cdk-lib.Stack
The stack in which this element is defined.
CfnElements must be defined within a stack scope (directly or indirectly).
---
##### `ref`Required
```typescript
public readonly ref: string;
```
- *Type:* string
Return a string that will be resolved to a CloudFormation `{ Ref }` for this element.
If, by any chance, the intrinsic reference of a resource is not a string, you could
coerce it to an IResolvable through `Lazy.any({ produce: resource.ref })`.
---
##### `cfnOptions`Required
```typescript
public readonly cfnOptions: ICfnResourceOptions;
```
- *Type:* aws-cdk-lib.ICfnResourceOptions
Options for this resource, such as condition, update policy etc.
---
##### `cfnResourceType`Required
```typescript
public readonly cfnResourceType: string;
```
- *Type:* string
AWS resource type.
---
##### `attrArn`Required
```typescript
public readonly attrArn: string;
```
- *Type:* string
Returns the Amazon Resource Name (ARN) for the specified `AWS::IAM::OIDCProvider` resource.
---
##### `tags`Required
```typescript
public readonly tags: TagManager;
```
- *Type:* aws-cdk-lib.TagManager
A list of tags that are attached to the specified IAM OIDC provider.
The returned list of tags is sorted by tag key. For more information about tagging, see [Tagging IAM resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide* .
> [http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-tags](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-tags)
---
##### `thumbprintList`Required
```typescript
public readonly thumbprintList: string[];
```
- *Type:* string[]
A list of certificate thumbprints that are associated with the specified IAM OIDC provider resource object.
For more information, see [CreateOpenIDConnectProvider](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateOpenIDConnectProvider.html) .
> [http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-thumbprintlist](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-thumbprintlist)
---
##### `clientIdList`Optional
```typescript
public readonly clientIdList: string[];
```
- *Type:* string[]
A list of client IDs (also known as audiences) that are associated with the specified IAM OIDC provider resource object.
For more information, see [CreateOpenIDConnectProvider](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateOpenIDConnectProvider.html) .
> [http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-clientidlist](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-clientidlist)
---
##### `url`Optional
```typescript
public readonly url: string;
```
- *Type:* string
The URL that the IAM OIDC provider resource object is associated with.
For more information, see [CreateOpenIDConnectProvider](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateOpenIDConnectProvider.html) .
> [http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-url](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-url)
---
##### `arn`Required
```typescript
public readonly arn: string;
```
- *Type:* string
---
##### `organizationId`Required
```typescript
public readonly organizationId: string;
```
- *Type:* string
---
#### Constants
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| CFN_RESOURCE_TYPE_NAME | string | The CloudFormation resource type name for this resource class. |
---
##### `CFN_RESOURCE_TYPE_NAME`Required
```typescript
public readonly CFN_RESOURCE_TYPE_NAME: string;
```
- *Type:* string
The CloudFormation resource type name for this resource class.
---
### CircleCiOidcRole
Define an IAM Role that can be assumed by a CircleCI Job via the CircleCI OpenID Connect Identity Provider.
#### Initializers
```typescript
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'
new CircleCiOidcRole(scope: Construct, id: string, props: CircleCiOidcRoleProps)
```
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| scope | constructs.Construct | *No description.* |
| id | string | *No description.* |
| props | CircleCiOidcRoleProps | *No description.* |
---
##### `scope`Required
- *Type:* constructs.Construct
---
##### `id`Required
- *Type:* string
---
##### `props`Required
- *Type:* CircleCiOidcRoleProps
---
#### Methods
| **Name** | **Description** |
| --- | --- |
| toString | Returns a string representation of this construct. |
| applyRemovalPolicy | Apply the given removal policy to this resource. |
| 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.
##### `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
---
##### `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. |
| 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 { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcRole.isConstruct(x: any)
```
Checks if `x` is a construct.
###### `x`Required
- *Type:* any
Any object.
---
##### `isOwnedResource`
```typescript
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcRole.isOwnedResource(construct: IConstruct)
```
Returns true if the construct was created by CDK, and false otherwise.
###### `construct`Required
- *Type:* constructs.IConstruct
---
##### `isResource`
```typescript
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcRole.isResource(construct: IConstruct)
```
Check whether the given construct is a Resource.
###### `construct`Required
- *Type:* constructs.IConstruct
---
##### `customizeRoles`
```typescript
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcRole.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;
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.
---
##### `fromRoleArn`
```typescript
import { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcRole.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 { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcRole.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 { CircleCiOidcRole } from '@blimmer/cdk-circleci-oidc'
CircleCiOidcRole.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.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. |
| 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. |
| 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.ResourceEnvironment
The environment this resource belongs to.
For resources that are created and managed by the CDK
(generally, those created by creating new class instances like Role, Bucket, etc.),
this is always the same as the environment of the stack they belong to;
however, for imported resources
(those obtained from static methods like fromRoleArn, fromBucketName, etc.),
that 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.
---
##### `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.
---
##### `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.
---
## Structs
### CircleCiConfiguration
#### Initializer
```typescript
import { CircleCiConfiguration } from '@blimmer/cdk-circleci-oidc'
const circleCiConfiguration: CircleCiConfiguration = { ... }
```
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| provider | ICircleCiOidcProvider | Reference to CircleCI OpenID Connect Provider configured in AWS IAM. |
| projectIds | string[] | Provide the UUID(s) of the CircleCI project(s) you want to be allowed to use this role. |
---
##### `provider`Required
```typescript
public readonly provider: ICircleCiOidcProvider;
```
- *Type:* ICircleCiOidcProvider
Reference to CircleCI OpenID Connect Provider configured in AWS IAM.
Either pass an construct defined by `new CircleCiOidcProvider`
or a retrieved reference from `CircleCiOidcProvider.fromOrganizationId`.
There can be only one (per AWS Account).
---
##### `projectIds`Optional
```typescript
public readonly projectIds: string[];
```
- *Type:* string[]
- *Default:* All CircleCI projects in the provider's organization
Provide the UUID(s) of the CircleCI project(s) you want to be allowed to use this role.
If you don't provide this
value, the role will be allowed to be assumed by any CircleCI project in your organization. You can find a
project's ID in the CircleCI dashboard UI under the "Project Settings" tab. It's usually in a UUID format.
---
### CircleCiOidcProviderProps
#### Initializer
```typescript
import { CircleCiOidcProviderProps } from '@blimmer/cdk-circleci-oidc'
const circleCiOidcProviderProps: CircleCiOidcProviderProps = { ... }
```
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| organizationId | string | The ID of your CircleCI organization. |
| thumbprints | string[] | The OIDC thumbprints used by the provider. |
---
##### `organizationId`Required
```typescript
public readonly organizationId: string;
```
- *Type:* string
The ID of your CircleCI organization.
This is typically in a UUID format. You can find this ID in the CircleCI
dashboard UI under the "Organization Settings" tab.
---
##### `thumbprints`Optional
```typescript
public readonly thumbprints: string[];
```
- *Type:* string[]
The OIDC thumbprints used by the provider.
You should not need to provide this value unless CircleCI suddenly
rotates their OIDC thumbprints (e.g., in response to a security incident).
If you do need to generate this thumbprint, you can follow the instructions here:
https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html
---
### CircleCiOidcRoleProps
Props that define the IAM Role that can be assumed by a CircleCI job via the CircleCI OpenID Connect Identity Provider.
Besides {@link CircleCiConfiguration}, you may pass in any {@link RoleProps} except `assumedBy`
which will be defined by this construct.
#### Initializer
```typescript
import { CircleCiOidcRoleProps } from '@blimmer/cdk-circleci-oidc'
const circleCiOidcRoleProps: CircleCiOidcRoleProps = { ... }
```
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| provider | ICircleCiOidcProvider | Reference to CircleCI OpenID Connect Provider configured in AWS IAM. |
| projectIds | string[] | Provide the UUID(s) of the CircleCI project(s) you want to be allowed to use this role. |
| 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. |
---
##### `provider`Required
```typescript
public readonly provider: ICircleCiOidcProvider;
```
- *Type:* ICircleCiOidcProvider
Reference to CircleCI OpenID Connect Provider configured in AWS IAM.
Either pass an construct defined by `new CircleCiOidcProvider`
or a retrieved reference from `CircleCiOidcProvider.fromOrganizationId`.
There can be only one (per AWS Account).
---
##### `projectIds`Optional
```typescript
public readonly projectIds: string[];
```
- *Type:* string[]
- *Default:* All CircleCI projects in the provider's organization
Provide the UUID(s) of the CircleCI project(s) you want to be allowed to use this role.
If you don't provide this
value, the role will be allowed to be assumed by any CircleCI project in your organization. You can find a
project's ID in the CircleCI dashboard UI under the "Project Settings" tab. It's usually in a UUID format.
---
##### `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.
---
### RoleProps
RoleProps.
#### Initializer
```typescript
import { RoleProps } from '@blimmer/cdk-circleci-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
### ICircleCiOidcProvider
- *Implemented By:* CircleCiOidcProvider, ICircleCiOidcProvider
Describes a CircleCI OpenID Connect Identity Provider for AWS IAM.
#### Properties
| **Name** | **Type** | **Description** |
| --- | --- | --- |
| arn | string | *No description.* |
| organizationId | string | *No description.* |
---
##### `arn`Required
```typescript
public readonly arn: string;
```
- *Type:* string
---
##### `organizationId`Required
```typescript
public readonly organizationId: string;
```
- *Type:* string
---