# Trust data sent to Verified Access from trust providers Verified Access trust data Trust data is data sent to AWS Verified Access from a trust provider. Trust data is also referred to as "user claims" or "trust context." The data generally includes information about either a user or a device. Examples of trust data include user email, group membership, device operating system version, device security state, and so on. The information that's sent varies depending on the trust provider, so you should refer to your trust provider’s documentation for a complete and updated list of trust data. However, by using the Verified Access logging capabilities, you can also see what trust data is being sent from your trust provider. This can be useful when defining policies that allow or deny access to your applications. For information on including trust context in your logs, see [Enable or disable Verified Access trust context](include-trust-context.md). This section contains sample trust data and examples to help you get started with policy writing. The information provided here is intended for illustrative purposes only and not as an official reference. **Topics** + [Default context](trust-data-default-context.md) + [AWS IAM Identity Center context](trust-data-iam.md) + [Third-party context](trust-data-third-party-trust.md) + [User claims passing](user-claims-passing.md) # Default context for Verified Access trust data Default context AWS Verified Access includes some elements about the current request by default in all Cedar evaluations regardless of your configured trust providers. You can write a policy that evaluates against the data if you choose. The following are examples of the data that is included in the evaluation. **Topics** + [ ## HTTP request ](#default-context-http-request) + [ ## TCP flow ](#default-context-tcp-flow) ## HTTP request When a policy is evaluated, Verified Access includes data about the current HTTP request in the Cedar context under the `context.http_request` key. ``` { "title": "HTTP Request data included by Verified Access", "type": "object", "properties": { "http_method": { "type": "string", "description": "The HTTP method", "example": "GET" }, "hostname": { "type": "string", "description": "The host subcomponent of the authority component of the URI", "example": "example.com" }, "path": { "type": "string", "description": "The path component of the URI", "example": "app/images" }, "query": { "type": "string", "description": "The query component of the URI", "example": "value1=1&value2=2" }, "x_forwarded_for": { "type": "string", "description": "The value of the X-Forwarded-For request header", "example": "17.7.7.1" }, "port": { "type": "integer", "description": "The endpoint port", "example": 443 }, "user_agent": { "type": "string", "description": "The value of the User-Agent request header", "example": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0" }, "client_ip": { "type": "string", "description": "The IP address connecting to the endpoint", "example": "15.248.6.6" } } } ``` **Policy example** The following is an example Cedar policy that uses the HTTP request data. ``` forbid(principal, action, resource) when { context.http_request.http_method == "POST" && !(context.identity.roles.contains("Administrator")) }; ``` ## TCP flow When a policy is evaluated, Verified Access includes data about the current TCP flow in the Cedar context under the `context.tcp_flow` key. ``` { "title": "TCP flow data included by Verified Access", "type": "object", "properties": { "destination_ip": { "type": "string", "description": "The IP address of the target", "example": "192.100.1.3" }, "destination_port": { "type": "string", "description": "The target port", "example": 22 }, "client_ip": { "type": "string", "description": "The IP address connecting to the endpoint", "example": "172.154.16.9" } } } ``` # AWS IAM Identity Center context for Verified Access trust data AWS IAM Identity Center context When a policy is evaluated, if you define AWS IAM Identity Center as a trust provider, AWS Verified Access includes the trust data in the Cedar context under the key you specify as “Policy Reference Name” on the trust provider configuration. You can write a policy that evaluates against the trust data if you choose. **Note** The context key for your trust provider comes from the policy reference name that you configure when you create the trust provider. For example, if you configure the policy reference name as "idp123", the context key will be "context.idp123". Check that you are using the correct context key when you create the policy. The following [JSON schema](https://json-schema.org/) shows which data is included in the evaluation. ``` { "title": "AWS IAM Identity Center context specification", "type": "object", "properties": { "user": { "type": "object", "properties": { "user_id": { "type": "string", "description": "a unique user id generated by AWS IdC" }, "user_name": { "type": "string", "description": "username provided in the directory" }, "email": { "type": "object", "properties": { "address": { "type": "email", "description": "email address associated with the user" }, "verified": { "type": "boolean", "description": "whether the email address has been verified by AWS IdC" } } } } }, "groups": { "type": "object", "description": "A list of groups the user is a member of", "patternProperties": { "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$": { "type": "object", "description": "The Group ID of the group", "properties": { "group_name": { "type": "string", "description": "The customer-provided name of the group" } } } } } } } ``` The following is an example of a policy that evaluates against the trust data provided by AWS IAM Identity Center. ``` permit(principal, action, resource) when { context.idc.user.email.verified == true // User is in the "sales" group with specific ID && context.idc.groups has "c242c5b0-6081-1845-6fa8-6e0d9513c107" }; ``` **Note** As group names can be changed, IAM Identity Center refers to groups using their group ID. This helps avoid breaking a policy statement when changing the name of a group. # Third-party trust provider context for Verified Access trust data Third-party context This section describes the trust data provided to AWS Verified Access by third-party trust providers. **Note** The context key for your trust provider comes from the policy reference name that you configure when you create the trust provider. For example, if you configure the policy reference name as "idp123", the context key will be "context.idp123". Ensure you are using the correct context key when you create the policy. **Topics** + [ ## Browser extension ](#trust-data-browser) + [ ## Jamf ](#trust-data-iam-jamf) + [ ## CrowdStrike ](#trust-data-iam-cs) + [ ## JumpCloud ](#trust-data-jc) ## Browser extension If you plan to incorporate device trust context into your access policies, then you will need either the AWS Verified Access browser extension, or another partner's browser extension. Verified Access currently supports Google Chrome and Mozilla Firefox browsers. We currently support three device trust providers: Jamf (which supports macOS devices), CrowdStrike (which supports Windows 11 and Windows 10 devices), and JumpCloud (which supports both Windows and MacOS). + If you're using **Jamf** trust data in your policies, your users must download and install the AWS Verified Access browser extension from the [Chrome web store](https://chromewebstore.google.com/category/extensions) or [Firefox Add-on site](https://addons.mozilla.org/en-US/firefox/) on their devices. + If you are using **CrowdStrike** trust data in your policies, first your users need to install the [AWS Verified Access Native Messaging Host](https://d3p8dc6667u8pq.cloudfront.net/WPF/latest/AWS_Verified_Access_Native_Messaging_Host.msi) (direct download link). This component is required to get the trust data from the CrowdStrike agent running on users’ devices. Then, after installing this component, users must install the AWS Verified Access browser extension from the [Chrome web store](https://chromewebstore.google.com/category/extensions) or [Firefox Add-on site](https://addons.mozilla.org/en-US/firefox/) on their devices. + If you're using **JumpCloud**, your users must have the JumpCloud browser extension from the [Chrome web store](https://chromewebstore.google.com/category/extensions) or [Firefox Add-on site](https://addons.mozilla.org/en-US/firefox/) installed on their devices. ## Jamf Jamf is a third-party trust provider. When a policy is evaluated, if you define Jamf as a trust provider, Verified Access includes the trust data in the Cedar context under the key you specify as “Policy Reference Name” on the trust provider configuration. You can write a policy that evaluates against the trust data if you choose. The following [JSON schema](https://json-schema.org/) shows which data is included in the evaluation. For more information about using Jamf with Verified Access, see [Integrating AWS Verified Access with Jamf Device Identity](https://docs.jamf.com/technical-papers/jamf-security/aws-verified-access/index.html) on the Jamf website. ``` { "title": "Jamf device data specification", "type": "object", "properties": { "iss": { "type": "string", "description": "\"Issuer\" - the Jamf customer ID" }, "iat": { "type": "integer", "description": "\"Issued at Time\" - a unixtime (seconds since epoch) value of when the device information data was generated" }, "exp": { "type": "integer", "description": "\"Expiration\" - a unixtime (seconds since epoch) value for when this device information is no longer valid" }, "sub": { "type": "string", "description": "\"Subject\" - either the hardware UID or a value generated based on device location" }, "groups": { "type": "array", "description": "Group IDs from UEM connector sync", "items": { "type": "string" } }, "risk": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW", "SECURE", "NOT_APPLICABLE" ], "description": "a Jamf-reported level of risk associated with the device." }, "osv": { "type": "string", "description": "The version of the OS that is currently running, in Apple version number format (https://support.apple.com/en-us/HT201260)" } } } ``` The following is an example of a policy that evaluates against the trust data provided by Jamf. ``` permit(principal, action, resource) when { context.jamf.risk == "LOW" }; ``` Cedar provides a useful `.contains()` function to help with enums like Jamf’s risk score. ``` permit(principal, action, resource) when { ["LOW", "SECURE"].contains(context.jamf.risk) }; ``` ## CrowdStrike CrowdStrike is a third-party trust provider. When a policy is evaluated, if you define CrowdStrike as a trust provider, Verified Access includes the trust data in the Cedar context under the key you specify as “Policy Reference Name” on the trust provider configuration. You can write a policy that evaluates against the trust data if you choose. The following [JSON schema](https://json-schema.org/) shows which data is included in the evaluation. For more information about using CrowdStrike with Verified Access, see [Securing private applications with CrowdStrike and AWS Verified Access](https://github.com/CrowdStrike/aws-verified-access/) on the GitHub website. ``` { "title": "CrowdStrike device data specification", "type": "object", "properties": { "assessment": { "type": "object", "description": "Data about CrowdStrike's assessment of the device", "properties": { "overall": { "type": "integer", "description": "A single metric, between 1-100, that accounts as a weighted average of the OS and and Sensor Config scores" }, "os": { "type": "integer", "description": "A single metric, between 1-100, that accounts for the OS-specific settings monitored on the host" }, "sensor_config": { "type": "integer", "description": "A single metric, between 1-100, that accounts for the different sensor policies monitored on the host" }, "version": { "type": "string", "description": "The version of the scoring algorithm being used" } } }, "cid": { "type": "string", "description": "Customer ID (CID) unique to the customer's environment" }, "exp": { "type": "integer", "description": "unixtime, The expiration time of the token" }, "iat": { "type": "integer", "description": "unixtime, The issued time of the token" }, "jwk_url": { "type": "string", "description": "URL that details the JWT signing" }, "platform": { "type": "string", "enum": ["Windows 10", "Windows 11", "macOS"], "description": "Operating system of the endpoint" }, "serial_number": { "type": "string", "description": "The serial number of the device derived by unique system information" }, "sub": { "type": "string", "description": "Unique CrowdStrike Agent ID (AID) of machine" }, "typ": { "type": "string", "enum": ["crowdstrike-zta+jwt"], "description": "Generic name for this JWT media. Client MUST reject any other type" } } } ``` The following is an example of a policy that evaluates against the trust data provided by CrowdStrike. ``` permit(principal, action, resource) when { context.crowdstrike.assessment.overall > 50 }; ``` ## JumpCloud JumpCloud is a third-party trust provider. When a policy is evaluated, if you define JumpCloud as a trust provider, Verified Access includes the trust data in the Cedar context under the key you specify as “Policy Reference Name” on the trust provider configuration. You can write a policy that evaluates against the trust data if you choose. The following [JSON schema](https://json-schema.org/) shows which data is included in the evaluation. For more information about using JumpCloud with AWS Verified Access, see [Integrating JumpCloud and AWS Verified Access](https://jumpcloud.com/support/integrate-with-aws-verified-access) on the JumpCloud website. ``` { "title": "JumpCloud device data specification", "type": "object", "properties": { "device": { "type": "object", "description": "Properties of the device", "properties": { "is_managed": { "type": "boolean", "description": "Boolean to indicate if the device is under management" } } }, "exp": { "type": "integer", "description": "Expiration. Unixtime of the token's expiration." }, "durt_id": { "type": "string", "description": "Device User Refresh Token ID. Unique ID that represents the device + user." }, "iat": { "type": "integer", "description": "Issued At. Unixtime of the token's issuance." }, "iss": { "type": "string", "description": "Issuer. This will be 'go.jumpcloud.com'" }, "org_id": { "type": "string", "description": "The JumpCloud Organization ID" }, "sub": { "type": "string", "description": "Subject. The managed JumpCloud user ID on the device." }, "system": { "type": "string", "description": "The JumpCloud system ID" } } } ``` The following is an example of a policy that evaluates against the trust context provided by JumpCloud. ``` permit(principal, action, resource) when { context.jumpcloud.org_id == 'Unique_organization_identifier' }; ``` # User claims passing and signature verification in Verified Access User claims passing After an AWS Verified Access instance authenticates a user successfully, it sends the user claims received from the IdP to the Verified Access endpoint. The user claims are signed so that applications can verify the signatures and also verify that the claims were sent by Verified Access. During this process, the following HTTP header is added: `x-amzn-ava-user-context` This header contains the user claims in JSON web token (JWT) format. The JWT format includes a header, payload, and signature that are base64 URL encoded. Verified Access uses ES384 (ECDSA signature algorithm using SHA-384 hash algorithm) to generate the JWT signature. Applications can use these claims for personalization or other user specific experiences. Application developers should educate themselves regarding the level of uniqueness and verification of each claim provided by the identity provider before use. In general, the `sub` claim is the best way to identify a given user. **Topics** + [JWT for OIDC user claims](#oidc-sample) + [JWT for IAM Identity Center user claims](#IdC-sample) + [ ## Public keys ](#public-keys) + [Retrieving and decoding JWT](#sample-code) ## Example: Signed JWT for OIDC user claims JWT for OIDC user claims The following examples demonstrate what the header and payload for OIDC user claims will look like in the JWT format. Example header: ``` { "alg": "ES384", "kid": "12345678-1234-1234-1234-123456789012", "signer": "arn:aws:ec2:us-east-1:123456789012:verified-access-instance/vai-abc123xzy321a2b3c", "iss": "OIDC Issuer URL", "exp": "expiration" (120 secs) } ``` Example payload: ``` { "sub": "xyzsubject", "email": "xxx@amazon.com", "email_verified": true, "groups": [ "Engineering", "finance" ], "additional_user_context": { "aud": "xxx", "exp": 1000000000, "groups": [ "group-id-1", "group-id-2" ], "iat": 1000000000, "iss": "https://oidc-tp.com/", "sub": "xyzsubject", "ver": "1.0" } } ``` ## Example: Signed JWT for IAM Identity Center user claims JWT for IAM Identity Center user claims The following examples demonstrate what the header and payload for IAM Identity Center user claims will look like in the JWT format. **Note** For IAM Identity Center, only user information will be included in the claims. Example header: ``` { "alg": "ES384", "kid": "12345678-1234-1234-1234-123456789012", "signer": "arn:aws:ec2:us-east-1:123456789012:verified-access-instance/vai-abc123xzy321a2b3c", "iss": "arn:aws:ec2:us-east-1:123456789012:verified-access-trust-provider/vatp-abc123xzy321a2b3c", "exp": "expiration" (120 secs) } ``` Example payload: ``` { "user": { "user_id": "f478d4c8-a001-7064-6ea6-12423523", "user_name": "test-123", "email": { "address": "test@amazon.com", "verified": false } } } ``` ## Public keys Because Verified Access instances do not encrypt user claims, we recommend that you configure Verified Access endpoints to use HTTPS. If you configure your Verified Access endpoint to use HTTP, be sure to restrict the traffic to the endpoint using security groups. To ensure security, you must verify the signature before doing any authorization based on the claims, and validate that the `signer` field in the JWT header contains the expected Verified Access instance ARN. To get the public key, get the key ID from the JWT header and use it to look up the public key from the endpoint. The endpoint for each AWS Region is as follows: `https://public-keys.prod.verified-access..amazonaws.com/` ## Example: Retrieving and decoding JWT Retrieving and decoding JWT The following code example shows how to get the key ID, public key, and payload in Python 3.9. ``` import jwt import requests import base64 import json # Step 1: Validate the signer expected_verified_access_instance_arn = 'arn:aws:ec2:region-code:account-id:verified-access-instance/verified-access-instance-id' encoded_jwt = headers.dict['x-amzn-ava-user-context'] jwt_headers = encoded_jwt.split('.')[0] decoded_jwt_headers = base64.b64decode(jwt_headers) decoded_jwt_headers = decoded_jwt_headers.decode("utf-8") decoded_json = json.loads(decoded_jwt_headers) received_verified_access_instance_arn = decoded_json['signer'] assert expected_verified_access_instance_arn == received_verified_access_instance_arn, "Invalid Signer" # Step 2: Get the key id from JWT headers (the kid field) kid = decoded_json['kid'] # Step 3: Get the public key from regional endpoint url = 'https://public-keys.prod.verified-access.' + region + '.amazonaws.com/' + kid req = requests.get(url) pub_key = req.text # Step 4: Get the payload payload = jwt.decode(encoded_jwt, pub_key, algorithms=['ES384']) ```