Skip to content

Latest commit

 

History

History
1278 lines (788 loc) · 48.8 KB

API.md

File metadata and controls

1278 lines (788 loc) · 48.8 KB
Raw

CDK Library for AWS SSO

build

Note: This construct library is currently being developed and requires more tests, but fundamentally it should work.

This CDK library provides L2 constructs for the AWS SSO CfnPermissionSet and CfnAssignment. Assignment is not consumed by other resources so it's attributes and properties are minimal, but a L2 construct makes it easier to interact with and allows providing a more fully featured construct for the Permission Set and assignment requires.

Features

  • L2 Construct for PermissionSet including importing from ARN and granting the permission
  • L2 Construct for Assignment
  • Some enums to provide valid inputs for certain properties

API Doc

See API

Examples

PermissionSet

import { PermissionSet, Assignment, PrincipalTypes } from '@renovosolutions/cdk-library-aws-sso';
import {
  App,
  Stack,
  StackProps,
  aws_sso as sso,
  aws_iam as iam,
  Duration,
} from 'aws-cdk-lib';

// create a permission set
const permissionSetExample = new PermissionSet(this, 'permissionSet', {
  ssoInstanceArn: 'arn:aws:sso:::instance/ssoins-1234567891234567',
  name: 'ExamplePermissionSet',
  description: 'Example permission set with some policies',
  awsManagedPolicies:  [
    iam.ManagedPolicy.fromAwsManagedPolicyName('job-function/ViewOnlyAccess'),
  ],
  customerManagedPolicyReferences: [
    {
      name: 'someServiceLogRead', // must exist in the target account
      path: '/',
    }
  ],
  relayStateType: 'https://us-east-1.console.aws.amazon.com/cloudwatch/home'
})

// assign it to an account/principal with an Assignment
new Assignment(this, 'ExampleAssignment', {
  permissionSet: permissionSetExample,
  principal: {
    principalId: '25750630-0ae9-479a-97c2-0afc2d5b4eac,
    principalType: PrincipalTypes.GROUP,
  },
  targetId: '124567890123456',
});

// assign it to something else with a grant
permissionSetExample.grant('permissionSetExampleAssignment', {
  principal: {
    principalId: '12350630-0ae9-479a-97c2-0afc2d5b4eac',
    principalType: PrincipalTypes.GROUP,
  },
  targetId: '344567890123456',
});

// import an existing permission set
const existingPermissionSetExample = PermissionSet.fromPermissionSetArn(this, 'existingPermissionSetExample', 'arn:aws:sso:::permissionSet/ssoins-1234567891234567/ps-55a5555a5a55ab55');

API Reference

Constructs

Assignment

The assignment construct.

Has no import method because there is no attributes to import.

Initializers 

import { Assignment } from '@renovosolutions/cdk-library-aws-sso'

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

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

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

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

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
isConstruct 
import { Assignment } from '@renovosolutions/cdk-library-aws-sso'

Assignment.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { Assignment } from '@renovosolutions/cdk-library-aws-sso'

Assignment.isOwnedResource(construct: IConstruct)

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

constructRequired
  • Type: constructs.IConstruct
isResource 
import { Assignment } from '@renovosolutions/cdk-library-aws-sso'

Assignment.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct

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.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

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

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

The stack in which this resource is defined.

PermissionSet

Initializers 

import { PermissionSet } from '@renovosolutions/cdk-library-aws-sso'

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

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
grant Grant this permission set to a given principal for a given targetId (AWS account identifier) on a given SSO instance.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

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

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

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
grant 
public grant(id: string, assignmentOptions: AssignmentOptions): Assignment

Grant this permission set to a given principal for a given targetId (AWS account identifier) on a given SSO instance.

idRequired
  • Type: string
assignmentOptionsRequired

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.
fromPermissionSetArn Reference an existing permission set by ARN.
isConstruct 
import { PermissionSet } from '@renovosolutions/cdk-library-aws-sso'

PermissionSet.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { PermissionSet } from '@renovosolutions/cdk-library-aws-sso'

PermissionSet.isOwnedResource(construct: IConstruct)

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

constructRequired
  • Type: constructs.IConstruct
isResource 
import { PermissionSet } from '@renovosolutions/cdk-library-aws-sso'

PermissionSet.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
fromPermissionSetArn 
import { PermissionSet } from '@renovosolutions/cdk-library-aws-sso'

PermissionSet.fromPermissionSetArn(scope: Construct, id: string, permissionSetArn: string)

Reference an existing permission set by ARN.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
permissionSetArnRequired
  • Type: string

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.
cfnPermissionSet aws-cdk-lib.aws_sso.CfnPermissionSet The underlying CfnPermissionSet resource.
permissionSetArn string The permission set ARN of the permission set.
ssoInstanceArn string The SSO instance the permission set belongs to.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

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

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

The stack in which this resource is defined.

cfnPermissionSetRequired 
public readonly cfnPermissionSet: CfnPermissionSet;
  • Type: aws-cdk-lib.aws_sso.CfnPermissionSet

The underlying CfnPermissionSet resource.

permissionSetArnRequired 
public readonly permissionSetArn: string;
  • Type: string

The permission set ARN of the permission set.

ssoInstanceArnRequired 
public readonly ssoInstanceArn: string;
  • Type: string

The SSO instance the permission set belongs to.

Structs

AssignmentAttributes

Attributes for an assignment of which there are none.

Initializer 

import { AssignmentAttributes } from '@renovosolutions/cdk-library-aws-sso'

const assignmentAttributes: AssignmentAttributes = { ... }

AssignmentOptions

The options for creating an assignment.

Initializer 

import { AssignmentOptions } from '@renovosolutions/cdk-library-aws-sso'

const assignmentOptions: AssignmentOptions = { ... }

Properties

Name Type Description
principal PrincipalProperty The principal to assign the permission set to.
targetId string The target id the permission set will be assigned to.
targetType TargetTypes The entity type for which the assignment will be created.
principalRequired 
public readonly principal: PrincipalProperty;

The principal to assign the permission set to.

targetIdRequired 
public readonly targetId: string;
  • Type: string

The target id the permission set will be assigned to.

targetTypeOptional 
public readonly targetType: TargetTypes;

The entity type for which the assignment will be created.

AssignmentProps

The properties of a new assignment.

Initializer 

import { AssignmentProps } from '@renovosolutions/cdk-library-aws-sso'

const assignmentProps: AssignmentProps = { ... }

Properties

Name Type Description
principal PrincipalProperty The principal to assign the permission set to.
targetId string The target id the permission set will be assigned to.
targetType TargetTypes The entity type for which the assignment will be created.
permissionSet IPermissionSet The permission set to assign to the principal.
principalRequired 
public readonly principal: PrincipalProperty;

The principal to assign the permission set to.

targetIdRequired 
public readonly targetId: string;
  • Type: string

The target id the permission set will be assigned to.

targetTypeOptional 
public readonly targetType: TargetTypes;

The entity type for which the assignment will be created.

permissionSetRequired 
public readonly permissionSet: IPermissionSet;

The permission set to assign to the principal.

CustomerManagedPolicyReference

Initializer 

import { CustomerManagedPolicyReference } from '@renovosolutions/cdk-library-aws-sso'

const customerManagedPolicyReference: CustomerManagedPolicyReference = { ... }

Properties

Name Type Description
name string The name of the IAM policy that you have configured in each account where you want to deploy your permission set.
path string The path to the IAM policy that you have configured in each account where you want to deploy your permission set.
nameRequired 
public readonly name: string;
  • Type: string

The name of the IAM policy that you have configured in each account where you want to deploy your permission set.

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sso-permissionset-customermanagedpolicyreference.html#cfn-sso-permissionset-customermanagedpolicyreference-name

pathOptional 
public readonly path: string;
  • Type: string

The path to the IAM policy that you have configured in each account where you want to deploy your permission set.

The default is / . For more information, see Friendly names and paths in the IAM User Guide .

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sso-permissionset-customermanagedpolicyreference.html#cfn-sso-permissionset-customermanagedpolicyreference-path

PermissionBoundary

Initializer 

import { PermissionBoundary } from '@renovosolutions/cdk-library-aws-sso'

const permissionBoundary: PermissionBoundary = { ... }

Properties

Name Type Description
customerManagedPolicyReference aws-cdk-lib.IResolvable | aws-cdk-lib.aws_sso.CfnPermissionSet.CustomerManagedPolicyReferenceProperty Specifies the name and path of a customer managed policy.
managedPolicyArn string The AWS managed policy ARN that you want to attach to a permission set as a permissions boundary.
customerManagedPolicyReferenceOptional 
public readonly customerManagedPolicyReference: IResolvable | CustomerManagedPolicyReferenceProperty;
  • Type: aws-cdk-lib.IResolvable | aws-cdk-lib.aws_sso.CfnPermissionSet.CustomerManagedPolicyReferenceProperty

Specifies the name and path of a customer managed policy.

You must have an IAM policy that matches the name and path in each AWS account where you want to deploy your permission set.

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sso-permissionset-permissionsboundary.html#cfn-sso-permissionset-permissionsboundary-customermanagedpolicyreference

managedPolicyArnOptional 
public readonly managedPolicyArn: string;
  • Type: string

The AWS managed policy ARN that you want to attach to a permission set as a permissions boundary.

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-sso-permissionset-permissionsboundary.html#cfn-sso-permissionset-permissionsboundary-managedpolicyarn

PermissionSetAttributes

Attributes for a permission set.

Initializer 

import { PermissionSetAttributes } from '@renovosolutions/cdk-library-aws-sso'

const permissionSetAttributes: PermissionSetAttributes = { ... }

Properties

Name Type Description
permissionSetArn string The permission set ARN of the permission set.
ssoInstanceArn string The SSO instance ARN of the permission set.
permissionSetArnRequired 
public readonly permissionSetArn: string;
  • Type: string

The permission set ARN of the permission set.

Such as arn:aws:sso:::permissionSet/ins-instanceid/ps-permissionsetid.

ssoInstanceArnRequired 
public readonly ssoInstanceArn: string;
  • Type: string

The SSO instance ARN of the permission set.

PermissionSetProps

The properties of a new permission set.

Initializer 

import { PermissionSetProps } from '@renovosolutions/cdk-library-aws-sso'

const permissionSetProps: PermissionSetProps = { ... }

Properties

Name Type Description
name string The name of the permission set.
ssoInstanceArn string The ARN of the SSO instance under which the operation will be executed.
awsManagedPolicies aws-cdk-lib.aws_iam.IManagedPolicy[] The AWS managed policies to attach to the PermissionSet.
customerManagedPolicyReferences CustomerManagedPolicyReference[] Specifies the names and paths of a customer managed policy.
description string The description of the PermissionSet.
inlinePolicy aws-cdk-lib.aws_iam.PolicyDocument The IAM inline policy that is attached to the permission set.
permissionsBoundary PermissionBoundary Specifies the configuration of the AWS managed or customer managed policy that you want to set as a permissions boundary.
relayStateType string Used to redirect users within the application during the federation authentication process.
sessionDuration aws-cdk-lib.Duration The length of time that the application user sessions are valid for.
nameRequired 
public readonly name: string;
  • Type: string

The name of the permission set.

ssoInstanceArnRequired 
public readonly ssoInstanceArn: string;
  • Type: string

The ARN of the SSO instance under which the operation will be executed.

awsManagedPoliciesOptional 
public readonly awsManagedPolicies: IManagedPolicy[];
  • Type: aws-cdk-lib.aws_iam.IManagedPolicy[]
  • Default: No AWS managed policies

The AWS managed policies to attach to the PermissionSet.

customerManagedPolicyReferencesOptional 
public readonly customerManagedPolicyReferences: CustomerManagedPolicyReference[];

Specifies the names and paths of a customer managed policy.

You must have an IAM policy that matches the name and path in each AWS account where you want to deploy your permission set.

descriptionOptional 
public readonly description: string;
  • Type: string
  • Default: No description

The description of the PermissionSet.

inlinePolicyOptional 
public readonly inlinePolicy: PolicyDocument;
  • Type: aws-cdk-lib.aws_iam.PolicyDocument
  • Default: No inline policy

The IAM inline policy that is attached to the permission set.

permissionsBoundaryOptional 
public readonly permissionsBoundary: PermissionBoundary;

Specifies the configuration of the AWS managed or customer managed policy that you want to set as a permissions boundary.

Specify either customerManagedPolicyReference to use the name and path of a customer managed policy, or managedPolicy to use the ARN of an AWS managed policy.

A permissions boundary represents the maximum permissions that any policy can grant your role. For more information, see Permissions boundaries for IAM entities in the AWS Identity and Access Management User Guide.

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

relayStateTypeOptional 
public readonly relayStateType: string;
  • Type: string
  • Default: No redirection

Used to redirect users within the application during the federation authentication process.

By default, when a user signs into the AWS access portal, chooses an account, and then chooses the role that AWS creates from the assigned permission set, IAM Identity Center redirects the user’s browser to the AWS Management Console.

You can change this behavior by setting the relay state to a different console URL. Setting the relay state enables you to provide the user with quick access to the console that is most appropriate for their role. For example, you can set the relay state to the Amazon EC2 console URL (https://console.aws.amazon.com/ec2/) to redirect the user to that console when they choose the Amazon EC2 administrator role.

https://docs.aws.amazon.com/singlesignon/latest/userguide/howtopermrelaystate.html

sessionDurationOptional 
public readonly sessionDuration: Duration;
  • Type: aws-cdk-lib.Duration

The length of time that the application user sessions are valid for.

PrincipalProperty

Initializer 

import { PrincipalProperty } from '@renovosolutions/cdk-library-aws-sso'

const principalProperty: PrincipalProperty = { ... }

Properties

Name Type Description
principalId string The id of the principal.
principalType PrincipalTypes The type of the principal.
principalIdRequired 
public readonly principalId: string;
  • Type: string

The id of the principal.

principalTypeRequired 
public readonly principalType: PrincipalTypes;

The type of the principal.

Protocols

IAssignment

The resource interface for an AWS SSO assignment.

This interface has no attributes because the resulting resource has none.

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.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

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

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

The stack in which this resource is defined.

IPermissionSet

The resource interface for an AWS SSO permission set.

Methods

Name Description
grant Grant this permission set to a given principal for a given targetId (AWS account identifier) on a given SSO instance.
grant 
public grant(id: string, assignmentOptions: AssignmentOptions): Assignment

Grant this permission set to a given principal for a given targetId (AWS account identifier) on a given SSO instance.

idRequired
  • Type: string
assignmentOptionsRequired

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.
permissionSetArn string The permission set ARN of the permission set.
ssoInstanceArn string The SSO instance ARN of the permission set.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

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

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

The stack in which this resource is defined.

permissionSetArnRequired 
public readonly permissionSetArn: string;
  • Type: string

The permission set ARN of the permission set.

Such as arn:aws:sso:::permissionSet/ins-instanceid/ps-permissionsetid.

ssoInstanceArnRequired 
public readonly ssoInstanceArn: string;
  • Type: string

The SSO instance ARN of the permission set.

Enums

PrincipalTypes

Members

Name Description
USER No description.
GROUP No description.
USER
GROUP

TargetTypes

Members

Name Description
AWS_ACCOUNT No description.
AWS_ACCOUNT