2.168.0

class ServicePrincipal

LanguageType name
.NETAmazon.CDK.AWS.IAM.ServicePrincipal
Gogithub.com/aws/aws-cdk-go/awscdk/v2/awsiam#ServicePrincipal
Javasoftware.amazon.awscdk.services.iam.ServicePrincipal
Pythonaws_cdk.aws_iam.ServicePrincipal
TypeScript (source)aws-cdk-lib » aws_iam » ServicePrincipal

Implements IAssumeRolePrincipal, IGrantable, IPrincipal, IComparablePrincipal

Extends PrincipalBase

An IAM principal that represents an AWS service (i.e. sqs.amazonaws.com).

Example

const role = new iam.Role(this, 'Role', {
  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
});

declare const definition: sfn.IChainable;
const stateMachine = new sfn.StateMachine(this, 'StateMachine', {
  definitionBody: sfn.DefinitionBody.fromChainable(definition),
});

// Give role permission to get execution history of ALL executions for the state machine
stateMachine.grantExecution(role, 'states:GetExecutionHistory');

Initializer

new ServicePrincipal(service: string, opts?: ServicePrincipalOpts)

Parameters

Reference an AWS service, optionally in a given region.

Properties

NameTypeDescription
assumeRoleActionstringWhen this Principal is used in an AssumeRole policy, the action to use.
grantPrincipalIPrincipalThe principal to grant permissions to.
policyFragmentPrincipalPolicyFragmentReturn the policy fragment that identifies this principal in a Policy.
servicestringAWS service (i.e. sqs.amazonaws.com).
principalAccount?stringThe AWS account ID of this principal.

assumeRoleAction

Type: string

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

grantPrincipal

Type: IPrincipal

The principal to grant permissions to.

policyFragment

Type: PrincipalPolicyFragment

Return the policy fragment that identifies this principal in a Policy.

service

Type: string

AWS service (i.e. sqs.amazonaws.com).

principalAccount?

Type: string (optional)

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.

Methods

NameDescription
addToAssumeRolePolicy(document)Add the principal to the AssumeRolePolicyDocument.
addToPolicy(statement)Add to the policy of this principal.
addToPrincipalPolicy(_statement)Add to the policy of this principal.
dedupeString()Return whether or not this principal is equal to the given principal.
toJSON()JSON-ify the principal.
toString()Returns a string representation of an object.
withConditions(conditions)Returns a new PrincipalWithConditions using this principal as the base, with the passed conditions added.
withSessionTags()Returns a new principal using this principal as the base, with session tags enabled.
static fromStaticServicePrincipleName(servicePrincipalName)Return the service principal using the service principal name as it is passed to the function without any change regardless of the region used in the stack if it is Opted in or not.
static servicePrincipalName(service)Return the service principal name based on the region it's used in.

addToAssumeRolePolicy(document)

public addToAssumeRolePolicy(document: PolicyDocument): void

Parameters

Add the principal to the AssumeRolePolicyDocument.

Add the statements to the AssumeRolePolicyDocument necessary to give this principal permissions to assume the given role.

addToPolicy(statement)

public addToPolicy(statement: PolicyStatement): boolean

Parameters

Returns

  • boolean

Add to the policy of this principal.

addToPrincipalPolicy(_statement)

public addToPrincipalPolicy(_statement: PolicyStatement): AddToPrincipalPolicyResult

Parameters

Returns

Add to the policy of this principal.

dedupeString()

public dedupeString(): string

Returns

  • string

Return whether or not this principal is equal to the given principal.

toJSON()

public toJSON(): { [string]: string[] }

Returns

  • { [string]: string[] }

JSON-ify the principal.

Used when JSON.stringify() is called

toString()

public toString(): string

Returns

  • string

Returns a string representation of an object.

withConditions(conditions)

public withConditions(conditions: { [string]: any }): PrincipalBase

Parameters

  • conditions { [string]: any }

Returns

Returns a new PrincipalWithConditions using this principal as the base, with the passed conditions added.

When there is a value for the same operator and key in both the principal and the conditions parameter, the value from the conditions parameter will be used.

withSessionTags()

public withSessionTags(): PrincipalBase

Returns

Returns a new principal using this principal as the base, with session tags enabled.

static fromStaticServicePrincipleName(servicePrincipalName)

public static fromStaticServicePrincipleName(servicePrincipalName: string): ServicePrincipal

Parameters

  • servicePrincipalName string

Returns

Return the service principal using the service principal name as it is passed to the function without any change regardless of the region used in the stack if it is Opted in or not. Example

const principalName = iam.ServicePrincipal.fromStaticServicePrincipleName('elasticmapreduce.amazonaws.com.cn');

static servicePrincipalName(service)

public static servicePrincipalName(service: string): string

Parameters

  • service string

Returns

  • string

Return the service principal name based on the region it's used in.

Some service principal names used to be different for different partitions, and some were not. This method would return the appropriate region-specific service principal name, getting that information from the region-info module.

These days all service principal names are standardized, and they are all of the form <servicename>.amazonaws.com.

To avoid breaking changes, handling is provided for services added with the formats below, however, no additional handling will be added for new regions or partitions.

  • s3
  • s3.amazonaws.com
  • s3.amazonaws.com.cn
  • s3.c2s.ic.gov
  • s3.sc2s.sgov.gov Example
const principalName = iam.ServicePrincipal.servicePrincipalName('ec2.amazonaws.com');
← PreviousNext →