IAM and permissions

OBSESC has two separate permission layers. AWS IAM controls what the node can do in your account. The product’s own authentication and role-based access control (RBAC) controls what people and shippers can do on the node. This page covers both.

AWS IAM: what the stack creates

The node role

The node uses one instance role. Each grant is scoped to a single resource or prefix, and the optional grants exist only when you set the parameter that needs them.

Policy	Actions	Scope	Present when
Raw-bucket access	s3:PutObject, GetObject, DeleteObject, AbortMultipartUpload, ListMultipartUploadParts	raw/*, catalog/*, cluster/*, query/audit/*, holds/* in your raw bucket	Always
Scoped listing	s3:ListBucket, ListBucketMultipartUploads	The raw bucket, limited to those five prefixes by an s3:prefix condition	Always
KMS	kms:Encrypt, Decrypt, GenerateDataKey, DescribeKey	Your KmsKeyArn only	Always
Session Manager	AWS-managed AmazonSSMManagedInstanceCore	—	Always
Auth secret	secretsmanager:GetSecretValue	Your AuthSecretArn only	AuthSecretArn set
TLS material	ssm:GetParameter	The two named TLS parameters	TLS parameters set
Console load balancer settings	ssm:GetParameter	One parameter the stack creates for the load balancer	EnableUiLoadBalancer set
Cross-account bucket role	sts:AssumeRole	S3AssumeRoleArn only	S3AssumeRoleArn set
Marketplace metering	aws-marketplace:MeterUsage	* (the action takes no resource)	MarketplaceProductCode set

Because listing is limited to those prefixes, the node can’t list anything else stored in the same bucket.

Provisioning policy

The stack also attaches a separate policy that is used to register the node with the console load balancer and, in multi-node deployments, to launch and remove nodes. It is tightly scoped:

• New instances and volumes must carry this stack’s Project tag and live in this VPC. Only instances with that tag can be terminated.
• iam:PassRole can pass only the node role, and only to EC2.
• KMS grants are limited to AWS resources, and volume data keys can be generated only through EC2.
• Load balancer target registration is limited to this stack’s target groups.
• ec2:DescribeInstances and DescribeVolumes apply to *, because AWS doesn’t support narrower scoping for them. The role can’t delete volumes.

The stock deployment runs a single node. Contact us about multi-node deployments.

Permissions you add yourself

The stack doesn’t grant access for optional features that point at resources it doesn’t know about. Add these to the node role when you use them:

• Pull sources (Kinesis, SQS with S3 notifications): read access to the stream, queue and bucket you consume (see Supported sources).
• Amazon SNS alert destinations: sns:Publish on the topic.

A raw bucket in another account

If a central log-archive account owns the raw bucket, deploy with CreateRawBucket=false and use one of these two methods:

• Bucket policy. Set RawBucketAccountId to the bucket owner’s account ID. The stack outputs RawBucketPolicySnippet, which the bucket owner applies:

  aws s3api put-bucket-policy --bucket my-obsesc-bucket --policy file://policy.json

• Assumed role. Set S3AssumeRoleArn to a role in the bucket’s account. Give that role the same S3 grants, and add the S3AssumeRoleTrustSnippet output to its trust policy.

If the bucket uses SSE-KMS with a key in the other account, that key’s policy must also allow the node role kms:Encrypt, Decrypt, GenerateDataKey and DescribeKey.

The node checks that the bucket is owned by the account you expect. A bucket with the same name but a different owner is refused rather than written to.

Product authentication and RBAC

Turning enforcement on

When you set AuthSecretArn, the stack turns on role-based access. The query_api_token in that secret becomes an admin credential, and every console and API action checks the caller’s role. Callers with no valid credentials get 401, and callers without the required permission get 403.

If you don’t set AuthSecretArn, the console and the query API don’t require authentication at all. Don’t run a production deployment that way.

Built-in roles

Role	Can do
viewer	Use the console and run queries, searches and analyses; build evidence bundles; see legal holds, alert silences and watchlists
operator	Everything a viewer can, plus silence alerts and update incidents
admin	Everything, including legal holds, erasure, reading the query audit trail, managing watchlists and other users’ saved items

Reading the query audit trail is deliberately left out of viewer, because the trail names people and what they accessed.

Custom roles and extra tokens

You can declare extra roles, and bind additional tokens to roles, in the node config. Tokens are hashed at startup, but they are stored in the config file. Only the admin query_api_token can be supplied from Secrets Manager.

security:
  authz:
    enabled: true
    roles:
      - name: auditor
        permissions: ["read", "audit:read"]
    token_role_map:
      - token: "<long random token>"
        role: auditor
      - token: "<another token>"
        role: viewer

The permissions you can grant include read, audit:read, alert:silence, hold:write, erase:write, watchlist:write and saved:admin. A custom role can’t reuse a built-in role’s name.

Single sign-on through an Application Load Balancer

Console sign-in uses the load balancer’s authenticate-oidc action with your identity provider. Every signed-in user reaches the node with their own verified identity and their own role. The node verifies the identity the load balancer passes on, and accepts it only from your stack’s load balancer.

Turn it on with these parameters. Both options require EnableUiLoadBalancer, UiCertificateArn, AuthSecretArn, UiOidcIssuerUrl, UiOidcClientId, the AlbOidc* parameters and NodeApiOidcAdminValue:

Parameter	Effect
EnableUiPerUserRbac=true	Signs users in at the console’s HTTPS listener (443). This is the recommended setting.
EnableNodeApiOidc=true	Adds a second HTTPS listener on port 8443 that signs browser users in before forwarding to the node. If you turn on only this option, the UiUrl output points at port 8443

Map users to roles with:

• NodeApiOidcClaim: which identity claim to match (default email; also sub, username or groups)
• NodeApiOidcAdminValue: the claim value that gets admin
• NodeApiOidcViewerValue: the claim value that gets viewer. Set it to "*" so every other signed-in user can use the console as a viewer. Otherwise, signed-in users with no mapping are turned away.

The load balancer builds the identity from your identity provider’s userInfo response. Amazon Cognito’s userInfo contains no groups claim, so use groups only if your identity provider includes it there.

Set NodeApiOidcJwksUrl to https://public-keys.auth.elb.<region>.amazonaws.com and the node picks up the load balancer’s rotated signing keys automatically. Leave it empty on a node without outbound access, and update AlbOidcSignerPublicKeyPem by hand when the key rotates.

If you set AuthSecretArn but don’t turn on sign-in, the console still loads, but it can’t show data until you supply a token.

Ingest credentials

Store ingest credentials in the same Secrets Manager secret as the API token:

{
  "query_api_token": "<admin token>",
  "ingest_tokens": ["<otlp/es/vector/loki token>"],
  "hec_tokens": ["<splunk hec token>"],
  "fluent_shared_key": "<forward shared key>",
  "firehose_access_key": "<firehose endpoint key>",
  "kafka_sasl_password": "<sasl password>"
}

Values in the secret take precedence over values in the config file. The node reads the secret only at startup, so to rotate a credential, update the value in Secrets Manager and then restart the node. If you need help planning a rotation, contact us.