ServicePrincipal Class
An IAM principal that represents an AWS service (i.e. sqs.amazonaws.com).
Example
ts
// Create a browser
const browser = new agentcore.BrowserCustom(this, "MyBrowser", {
browserCustomName: "my_browser",
description: "Browser for web automation",
networkConfiguration: agentcore.BrowserNetworkConfiguration.usingPublicNetwork(),
});
// Create a role that needs access to the browser
const userRole = new iam.Role(this, "UserRole", {
assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
});
// Grant read permissions (Get and List actions)
browser.grantRead(userRole);
// Grant use permissions (Start, Update, Connect to the automation stream, and Stop actions)
browser.grantUse(userRole);
// Grant specific custom permissions
browser.grant(userRole, "bedrock-agentcore:GetBrowserSession");
python
# Create a browser
browser = agentcore.BrowserCustom(self, "MyBrowser",
browser_custom_name="my_browser",
description="Browser for web automation",
network_configuration=agentcore.BrowserNetworkConfiguration.using_public_network()
)
# Create a role that needs access to the browser
user_role = iam.Role(self, "UserRole",
assumed_by=iam.ServicePrincipal("lambda.amazonaws.com")
)
# Grant read permissions (Get and List actions)
browser.grant_read(user_role)
# Grant use permissions (Start, Update, Connect to the automation stream, and Stop actions)
browser.grant_use(user_role)
# Grant specific custom permissions
browser.grant(user_role, "bedrock-agentcore:GetBrowserSession")
java
// Create a browser
BrowserCustom browser = BrowserCustom.Builder.create(this, "MyBrowser")
.browserCustomName("my_browser")
.description("Browser for web automation")
.networkConfiguration(BrowserNetworkConfiguration.usingPublicNetwork())
.build();
// Create a role that needs access to the browser
Role userRole = Role.Builder.create(this, "UserRole")
.assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
.build();
// Grant read permissions (Get and List actions)
browser.grantRead(userRole);
// Grant use permissions (Start, Update, Connect to the automation stream, and Stop actions)
browser.grantUse(userRole);
// Grant specific custom permissions
browser.grant(userRole, "bedrock-agentcore:GetBrowserSession");
csharp
// Install: dotnet add package Amazon.CDK.Lib
// Create a browser
var browser = new BrowserCustom(this, "MyBrowser", new BrowserCustomProps {
BrowserCustomName = "my_browser",
Description = "Browser for web automation",
NetworkConfiguration = BrowserNetworkConfiguration.UsingPublicNetwork()
});
// Create a role that needs access to the browser
var userRole = new Role(this, "UserRole", new RoleProps {
AssumedBy = new ServicePrincipal("lambda.amazonaws.com")
});
// Grant read permissions (Get and List actions)
browser.GrantRead(userRole);
// Grant use permissions (Start, Update, Connect to the automation stream, and Stop actions)
browser.GrantUse(userRole);
// Grant specific custom permissions
browser.Grant(userRole, "bedrock-agentcore:GetBrowserSession");
go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
// Create a browser
browser := agentcore.NewBrowserCustom(this, jsii.String("MyBrowser"), &BrowserCustomProps{
BrowserCustomName: jsii.String("my_browser"),
Description: jsii.String("Browser for web automation"),
NetworkConfiguration: agentcore.BrowserNetworkConfiguration_UsingPublicNetwork(),
})
// Create a role that needs access to the browser
userRole := iam.NewRole(this, jsii.String("UserRole"), &RoleProps{
AssumedBy: iam.NewServicePrincipal(jsii.String("lambda.amazonaws.com")),
})
// Grant read permissions (Get and List actions)
browser.GrantRead(userRole)
// Grant use permissions (Start, Update, Connect to the automation stream, and Stop actions)
browser.GrantUse(userRole)
// Grant specific custom permissions
browser.Grant(userRole, jsii.String("bedrock-agentcore:GetBrowserSession"))
Initializer
ts
new ServicePrincipal(service: string, opts?: ServicePrincipalOpts)
python
ServicePrincipal(service: str, opts: typing.Optional[ServicePrincipalOpts] = None)
java
new ServicePrincipal(String service, ServicePrincipalOpts opts)
csharp
new ServicePrincipal(string service, ServicePrincipalOpts? opts = null)
go
NewServicePrincipal(Service *string, Opts ServicePrincipalOpts)
Properties
assumeRoleActionstringassume_role_actionstrassumeRoleActionStringAssumeRoleActionstringAssumeRoleAction*stringrequired#When this Principal is used in an AssumeRole policy, the action to use.
grantPrincipalIPrincipalgrant_principalIPrincipalgrantPrincipalIPrincipalGrantPrincipalIPrincipalGrantPrincipalIPrincipalrequired#The principal to grant permissions to.
policyFragmentPrincipalPolicyFragmentpolicy_fragmentPrincipalPolicyFragmentpolicyFragmentPrincipalPolicyFragmentPolicyFragmentPrincipalPolicyFragmentPolicyFragmentPrincipalPolicyFragmentrequired#Return the policy fragment that identifies this principal in a Policy.
principalAccountstringprincipal_accountstrprincipalAccountStringPrincipalAccountstringPrincipalAccount*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.
AWS service (i.e. sqs.amazonaws.com).
Methods
addToAssumeRolePolicy(document: PolicyDocument): voiddef add_to_assume_role_policy(self, document: PolicyDocument) -> Nonepublic void addToAssumeRolePolicy(PolicyDocument document)public void AddToAssumeRolePolicy(PolicyDocument document)func AddToAssumeRolePolicy(Document PolicyDocument)#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: PolicyStatement): booleandef add_to_policy(self, statement: PolicyStatement) -> boolpublic Boolean addToPolicy(PolicyStatement statement)public bool AddToPolicy(PolicyStatement statement)func AddToPolicy(Statement PolicyStatement) *bool#Add to the policy of this principal.
addToPrincipalPolicy(_statement: PolicyStatement): AddToPrincipalPolicyResultdef add_to_principal_policy(self, _statement: PolicyStatement) -> AddToPrincipalPolicyResultpublic AddToPrincipalPolicyResult addToPrincipalPolicy(PolicyStatement _statement)public AddToPrincipalPolicyResult AddToPrincipalPolicy(PolicyStatement _statement)func AddToPrincipalPolicy(_statement PolicyStatement) AddToPrincipalPolicyResult#Add to the policy of this principal.
dedupeString(): stringdef dedupe_string(self, ) -> strpublic String dedupeString()public string DedupeString()func DedupeString() *string#Return whether or not this principal is equal to the given principal.
fromStaticServicePrincipleName(servicePrincipalName: string): ServicePrincipal // chainable@staticmethod def from_static_service_principle_name(service_principal_name: str) -> ServicePrincipalpublic static ServicePrincipal fromStaticServicePrincipleName(String servicePrincipalName)public static ServicePrincipal FromStaticServicePrincipleName(string servicePrincipalName)func FromStaticServicePrincipleName(ServicePrincipalName *string) ServicePrincipalstatic#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
ts
const principalName = iam.ServicePrincipal.fromStaticServicePrincipleName('elasticmapreduce.amazonaws.com.rproxy.goskope.com.cn');
servicePrincipalName(service: string): string@staticmethod def service_principal_name(service: str) -> strpublic static String servicePrincipalName(String service)public static string ServicePrincipalName(string service)func ServicePrincipalName(Service *string) *stringstatic#Return the service principal name based on the region it's used in.
notes · example
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.rproxy.goskope.com.cn
- s3.c2s.ic.gov
- s3.sc2s.sgov.gov
ts
const principalName = iam.ServicePrincipal.servicePrincipalName('ec2.amazonaws.com');
toJSON(): { [key: string]: string[] }def to_json(self, ) -> typing.Mapping[str, typing.List[str]]public Map<String, List<String>> toJSON()public IDictionary<string, string[]> ToJSON()func ToJSON() *map[string]*[]*string#JSON-ify the principal.
Used when JSON.stringify() is called
toString(): stringdef to_string(self, ) -> strpublic String toString()public string ToString()func ToString() *string#Returns a string representation of an object.
withConditions(conditions: { [key: string]: any }): PrincipalBasedef with_conditions(self, conditions: typing.Mapping[str, Any]) -> PrincipalBasepublic PrincipalBase withConditions(Map<String, Object> conditions)public PrincipalBase WithConditions(IDictionary<string, object> conditions)func WithConditions(Conditions *map[string]interface{}) PrincipalBase#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.
returns
Returns: a new PrincipalWithConditions object.
withSessionTags(): PrincipalBasedef with_session_tags(self, ) -> PrincipalBasepublic PrincipalBase withSessionTags()public PrincipalBase WithSessionTags()func WithSessionTags() PrincipalBase#Returns a new principal using this principal as the base, with session tags enabled.
returns
Returns: a new SessionTagsPrincipal object.