# ServicePrincipal

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

Extends: PrincipalBase › ServicePrincipal
Implements: IAssumeRolePrincipal, IComparablePrincipal, IGrantable, IPrincipal

- Source: [`aws-iam/lib/principals.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-iam/lib/principals.ts#L537)
- Type last changed: v2.163.0 · 22 Oct 2024

## 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");
```

## Initializer

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

## Properties

- `assumeRoleAction`: string — When this Principal is used in an AssumeRole policy, the action to use.

- `grantPrincipal`: [IPrincipal](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IPrincipal.html) — The principal to grant permissions to.

- `policyFragment`: [PrincipalPolicyFragment](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PrincipalPolicyFragment.html) — Return the policy fragment that identifies this principal in a Policy.

- `principalAccount`: 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.

- `service`: string — AWS service (i.e. sqs.amazonaws.com).

## Methods

- `addToAssumeRolePolicy(document: PolicyDocument): void` — 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): boolean` — Add to the policy of this principal.

- `addToPrincipalPolicy(_statement: PolicyStatement): AddToPrincipalPolicyResult` — Add to the policy of this principal.

- `dedupeString(): string` — Return whether or not this principal is equal to the given principal.

- `fromStaticServicePrincipleName(servicePrincipalName: string): ServicePrincipal // chainable` (static) — 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.

  ```ts
  const principalName = iam.ServicePrincipal.fromStaticServicePrincipleName('elasticmapreduce.amazonaws.com.rproxy.govskope.ca.cn');
  ```

- `servicePrincipalName(service: string): string` (static) — 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.rproxy.govskope.ca.cn
    - s3.c2s.ic.gov
    - s3.sc2s.sgov.gov

  ```ts
  const principalName = iam.ServicePrincipal.servicePrincipalName('ec2.amazonaws.com');
  ```

- `toJSON(): { [key: string]: string[] }` — JSON-ify the principal.

  Used when JSON.stringify() is called

- `toString(): string` — Returns a string representation of an object.

- `withConditions(conditions: { [key: string]: any }): 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:** a new PrincipalWithConditions object.

- `withSessionTags(): PrincipalBase` — Returns a new principal using this principal as the base, with session tags enabled.

  **Returns:** a new SessionTagsPrincipal object.