Skip to content

Commit

Permalink
docs: add comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@aripalo
aripalo committed Oct 31, 2021
1 parent 0cc2870 commit 3b30ce5
Show file tree
Hide file tree
Showing 4 changed files with 183 additions and 15 deletions.
66 changes: 64 additions & 2 deletions API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@

- *Implements:* [`@aripalo/aws-cdk-github-oidc.IGithubActionsIdentityProvider`](#@aripalo/aws-cdk-github-oidc.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.

> https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
#### Initializers <a name="@aripalo/aws-cdk-github-oidc.GithubActionsIdentityProvider.Initializer"></a>

```typescript
Expand All @@ -18,35 +24,43 @@ new GithubActionsIdentityProvider(scope: Construct, id: string)

- *Type:* [`@aws-cdk/core.Construct`](#@aws-cdk/core.Construct)

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

---

##### `id`<sup>Required</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubActionsIdentityProvider.parameter.id"></a>

- *Type:* `string`

CDK Construct ID given to the construct.

---


#### Static Functions <a name="Static Functions"></a>

##### `fromLookup` <a name="@aripalo/aws-cdk-github-oidc.GithubActionsIdentityProvider.fromLookup"></a>
##### `fromAccount` <a name="@aripalo/aws-cdk-github-oidc.GithubActionsIdentityProvider.fromAccount"></a>

```typescript
import { GithubActionsIdentityProvider } from '@aripalo/aws-cdk-github-oidc'

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

###### `scope`<sup>Required</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubActionsIdentityProvider.parameter.scope"></a>

- *Type:* [`@aws-cdk/core.Construct`](#@aws-cdk/core.Construct)

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

---

###### `id`<sup>Required</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubActionsIdentityProvider.parameter.id"></a>

- *Type:* `string`

CDK Construct ID given to the construct.

---


Expand All @@ -66,6 +80,11 @@ GithubActionsIdentityProvider.fromLookup(scope: Construct, id: string)

### GithubActionsRole <a name="@aripalo/aws-cdk-github-oidc.GithubActionsRole"></a>

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).

#### Initializers <a name="@aripalo/aws-cdk-github-oidc.GithubActionsRole.Initializer"></a>

```typescript
Expand Down Expand Up @@ -100,6 +119,11 @@ new GithubActionsRole(scope: Construct, id: string, props: GithubActionsRoleProp

### GithubActionsRoleProps <a name="@aripalo/aws-cdk-github-oidc.GithubActionsRoleProps"></a>

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).

#### Initializer <a name="[object Object].Initializer"></a>

```typescript
Expand All @@ -116,6 +140,8 @@ public readonly owner: string;

- *Type:* `string`

Repository owner (organization or username).

---

##### `provider`<sup>Required</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubActionsRoleProps.property.provider"></a>
Expand All @@ -126,6 +152,12 @@ public readonly provider: IGithubActionsIdentityProvider;

- *Type:* [`@aripalo/aws-cdk-github-oidc.IGithubActionsIdentityProvider`](#@aripalo/aws-cdk-github-oidc.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`<sup>Required</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubActionsRoleProps.property.repo"></a>
Expand All @@ -136,6 +168,8 @@ public readonly repo: string;

- *Type:* `string`

Repository name (slug) without the owner.

---

##### `filter`<sup>Optional</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubActionsRoleProps.property.filter"></a>
Expand All @@ -145,6 +179,13 @@ 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.

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

Expand Down Expand Up @@ -338,6 +379,8 @@ Acknowledging IAM Resources in AWS CloudFormation Templates.

### GithubConfiguration <a name="@aripalo/aws-cdk-github-oidc.GithubConfiguration"></a>

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

#### Initializer <a name="[object Object].Initializer"></a>

```typescript
Expand All @@ -354,6 +397,8 @@ public readonly owner: string;

- *Type:* `string`

Repository owner (organization or username).

---

##### `provider`<sup>Required</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubConfiguration.property.provider"></a>
Expand All @@ -364,6 +409,12 @@ public readonly provider: IGithubActionsIdentityProvider;

- *Type:* [`@aripalo/aws-cdk-github-oidc.IGithubActionsIdentityProvider`](#@aripalo/aws-cdk-github-oidc.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`<sup>Required</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubConfiguration.property.repo"></a>
Expand All @@ -374,6 +425,8 @@ public readonly repo: string;

- *Type:* `string`

Repository name (slug) without the owner.

---

##### `filter`<sup>Optional</sup> <a name="@aripalo/aws-cdk-github-oidc.GithubConfiguration.property.filter"></a>
Expand All @@ -383,6 +436,13 @@ 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.

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

Expand All @@ -395,6 +455,8 @@ public readonly filter: string;

- *Implemented By:* [`@aripalo/aws-cdk-github-oidc.GithubActionsIdentityProvider`](#@aripalo/aws-cdk-github-oidc.GithubActionsIdentityProvider), [`@aripalo/aws-cdk-github-oidc.IGithubActionsIdentityProvider`](#@aripalo/aws-cdk-github-oidc.IGithubActionsIdentityProvider)

Describes a Github OpenID Connect Identity Provider for AWS IAM.


#### Properties <a name="Properties"></a>

Expand Down
20 changes: 10 additions & 10 deletions src/provider.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ import * as cdk from '@aws-cdk/core';
export interface IGithubActionsIdentityProvider extends iam.IOpenIdConnectProvider {}

/**
* Github Actions as OpenID Connect Identity Provider for AWS IAM.
* Can be defined only once per AWS Account.
*
* 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.
*
*
* @see https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
*/
export class GithubActionsIdentityProvider extends iam.OpenIdConnectProvider implements IGithubActionsIdentityProvider {
Expand All @@ -21,8 +21,8 @@ export class GithubActionsIdentityProvider extends iam.OpenIdConnectProvider imp

/**
* 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
* 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.
* @param scope CDK Stack or Construct to which the provider is assigned to
* @param id CDK Construct ID given to the construct
Expand All @@ -37,10 +37,10 @@ export class GithubActionsIdentityProvider extends iam.OpenIdConnectProvider imp

/**
* Define a new Github OpenID Connect Identity PRovider for AWS IAM.
* Can be defined only once per AWS Account.
*
* There can be only one (per AWS Account).
*
* Use `fromAccount` to retrieve a reference to existing Github OIDC provider.
*
*
* @param scope CDK Stack or Construct to which the provider is assigned to
* @param id CDK Construct ID given to the construct
*/
Expand All @@ -51,4 +51,4 @@ export class GithubActionsIdentityProvider extends iam.OpenIdConnectProvider imp
clientIds: ['sts.amazonaws.com'],
});
}
}
}
Loading

0 comments on commit 3b30ce5

Please sign in to comment.