Grant Keyless Non-Human Access to Mondoo

Set up keyless authentication with GCP

Prerequisites

• Sufficient GCP privileges to create and manage service accounts

• Editor or Owner privileges in the Mondoo space, organization, or platform to which your workload needs access

Step A: Prepare your GCP environment for WIF

1. Create a GCP service account. To learn how, read Create service accounts.

2. Go the Service account details page and note the service account's unique ID. You need this value when you configure the workload identity provider.

3. Assign the managed identity to a virtual machine or another resource where your workload runs. To learn how, read Create a VM and attach the service account.

Step B: Create a new workload identity provider in Mondoo

1. In the Mondoo Console, navigate to the space or organization in which you want to set up keyless access for non-human users.

2. In the left navigation, select Settings. Then select the Identity Providers tab.

   

3. Select the ADD IDENTITY PROVIDER button or the plus (+) symbol near the top-right corner of the tab and select Google.

4. In the Issuer URL box, keep the default https://accounts.google.com.

5. In the Subject box, enter the unique ID of the GCP service account you created in Step A.

6. In the Expiration time list, choose the duration of sessions authenticated with this WIF provider.

7. In the Name and Description boxes, provide a short name and longer description that help you and your teammates recognize the source and purpose of the provider.

8. Select the ADD IDENTITY PROVIDER button.

   

   Mondoo generates and displays the configuration values that you need to give your workload access.

Step C: Exchange your token for access

Fetch the local token:

curl -H "Metadata-Flavor: Google" "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=test"

Make a curl call to exchange a local token for a short-lived Mondoo service account:

curl --request POST \
  --url 'UNIVERSE_DOMAIN/SecureTokenService/ExchangeExternalToken?=' \
  --header 'content-type: application/json' \
  --data '{
  "audience": "AUDIENCE",
  "issuer_uri": "ISSUER",
  "jwt_token": "TOKEN"
  }'

This call returns a Mondoo service account in the form of a base64_credential value, which your workload can use to access Mondoo by setting MONDOO_CONFIG_BASE64 to the returned value.

Set up keyless authentication with Azure (Microsoft Entra ID)

Prerequisites

• Sufficient Microsoft Entra ID privileges to create and manage service principals

• Editor or Owner privileges in the Mondoo space, organization, or platform to which your workload needs access

Step A: Prepare your Microsoft environment for WIF

1. Register a Microsoft Entra app and create a service principal. You can use the default Application (client) ID or specify a custom URI. Be sure to note the Application ID URI. You need this value when you configure the workload identity provider.

2. Create a managed identity. Be sure to note its Object ID. You need this value when you configure the workload identity provider.

3. Assign the managed identity to a virtual machine or another resource where your workload runs. To learn how, read User-assigned managed identity.

Step B: Create an identity provider in Mondoo

1. In the Mondoo Console, navigate to the space or organization in which you want to set up keyless access for non-human users.

2. In the left navigation, select Settings. Then select the Identity Providers tab.

   

3. Select the ADD IDENTITY PROVIDER button or the plus (+) symbol near the top-right corner of the tab and select Azure.

4. In the Issuer URL box, enter https://sts.windows.net/YOUR_TENANT_ID. For YOUR_TENANT_ID, substitute the tenant ID of the Microsoft directory in which you created the service principal.

5. In the Subject box, enter the Application ID URI from Step A.

6. In the Expiration time list, choose the duration of sessions authenticated with this WIF provider.

7. In the Name and Description boxes, provide a short name and longer description that help you and your teammates recognize the source and purpose of the identity provider.

8. Select the ADD IDENTITY PROVIDER button.

   

   Mondoo generates and displays the configuration values that you need to give your workload access to your Mondoo space.

Step C: Exchange your token for access to the Mondoo space

Fetch the local token:

curl http://localhost:50342/oauth2/token --data "resource=https://management.azure.com/" -H Metadata:true -s | jq -r ".access_token"

Make a curl call to exchange a local token for a short-lived Mondoo service account:

curl --request POST \
  --url 'UNIVERSE_DOMAIN/SecureTokenService/ExchangeExternalToken?=' \
  --header 'content-type: application/json' \
  --data '{
  "audience": "AUDIENCE",
  "issuer_uri": "ISSUER",
  "jwt_token": "TOKEN"
  }'

This call returns a Mondoo service account in the form of a base64_credential value, which your workload can use to access Mondoo by setting MONDOO_CONFIG_BASE64 to the returned value.

Set up keyless authentication with AWS

AWS workloads authenticate using a pre-signed STS GetCallerIdentity request instead of an OIDC JWT. No raw credentials are transmitted to Mondoo.

Prerequisites

• An AWS IAM role or user whose identity you want to use for authentication

• Editor or Owner privileges in the Mondoo space, organization, or platform to which your workload needs access

Step A: Create an identity provider in Mondoo

1. In the Mondoo Console, navigate to the space or organization in which you want to set up keyless access for non-human users.

2. In the left navigation, select Settings. Then select the Identity Providers tab.

   

3. Select the ADD IDENTITY PROVIDER button or the plus (+) symbol near the top-right corner of the tab and select AWS.

4. In the Issuer URL box, keep the default https://sts.amazonaws.com.

5. In the Subject box, enter the ARN of the AWS identity that your workload uses. Use these patterns:

   Caller type	Subject pattern
   IAM User	arn:aws:iam::123456789012:user/UserName
   IAM Role (direct)	arn:aws:iam::123456789012:role/RoleName
   Assumed role (any session)	arn:aws:sts::123456789012:assumed-role/RoleName/*
   Assumed role (specific session)	arn:aws:sts::123456789012:assumed-role/RoleName/SessionName

   IAM and STS ARNs omit the region field, resulting in consecutive colons (for example, arn:aws:iam::<ACCOUNT>:role/...). This is the correct format.

   For assumed roles, use the /* wildcard because session names change with each invocation.

6. In the Expiration time list, choose the duration of sessions authenticated with this identity provider.

7. Optionally, add claim mappings to restrict access further. AWS supports these claim keys:

   Key	Description
   aws_claims.account	AWS account ID
   aws_claims.arn	Full ARN of the caller
   aws_claims.userid	Unique identifier of the caller

8. In the Name and Description boxes, provide a short name and longer description that help you and your teammates recognize the source and purpose of the identity provider.

9. Select the ADD IDENTITY PROVIDER button.

   Mondoo generates and displays the configuration values that you need to give your workload access.

Step B: Exchange your token for access

AWS authentication uses a pre-signed GetCallerIdentity request rather than a JWT. The process works like this:

1. Your workload signs a GetCallerIdentity request using AWS Signature V4 with its locally available credentials.

2. The serialized signed request is sent to Mondoo (no raw credentials are transmitted).

3. Mondoo executes the signed request against AWS STS to verify the caller's identity.

4. The returned ARN is matched against the identity provider's subject.

Despite the field name jwt_token, the value for AWS is not a JWT. Instead, it contains a JSON-serialized pre-signed request:

{
  "url": "https://sts.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15",
  "method": "POST",
  "headers": [
    {
      "key": "Authorization",
      "value": "AWS4-HMAC-SHA256 Credential=AKIA.../us-east-1/sts/aws4_request, SignedHeaders=host;x-amz-date, Signature=..."
    },
    { "key": "host", "value": "sts.amazonaws.com" },
    { "key": "x-amz-date", "value": "20240101T000000Z" },
    { "key": "x-amz-security-token", "value": "FwoGZXIvY..." }
  ]
}

The x-amz-security-token header is only present when using temporary credentials (assumed roles, instance profiles).

Make a curl call to exchange the pre-signed request for a short-lived Mondoo service account:

curl --request POST \
  --url 'UNIVERSE_DOMAIN/SecureTokenService/ExchangeExternalToken' \
  --header 'content-type: application/json' \
  --data '{
  "audience": "AUDIENCE",
  "issuer_uri": "https://sts.amazonaws.com",
  "jwt_token": "PRE_SIGNED_REQUEST_JSON"
  }'

This call returns a Mondoo service account in the form of a base64_credential value, which your workload can use to access Mondoo by setting MONDOO_CONFIG_BASE64 to the returned value.

Set up keyless authentication with GitHub

To configure keyless authentication to Mondoo using GitHub as your WIF provider, you use a GitHub Actions workflow in a GitHub repository. Choose an existing repository in your GitHub organization or create a new one just for this purpose.

Prerequisites

• Sufficient privileges in your GitHub repository to create and manage GitHub Actions workflows

• Editor or Owner privileges in the Mondoo space, organization, or platform to which your workload needs access

Step A: Create a workload identity provider in Mondoo

1. In the Mondoo Console, navigate to the space or organization in which you want to set up keyless access for non-human users.

2. In the left navigation, select Settings. Then select the Identity Providers tab.

   

3. Select the ADD IDENTITY PROVIDER button or the plus (+) symbol near the top-right corner of the tab and select GitHub.

4. In the Issuer URL box, keep the default https://token.actions.githubusercontent.com.

5. In the Subject box, enter the organization and repository where you plan to create your GitHub Actions workflow.

6. In the Expiration time list, choose the duration of sessions authenticated with this WIF provider.

7. In the Name and Description boxes, provide a short name and longer description that help you and your teammates recognize the source and purpose of the workload identity provider.

8. Select the ADD IDENTITY PROVIDER button.

   

   Mondoo generates and displays the configuration values that you need to give your workload access.

Step B: Create a GitHub Actions workflow

Create a GitHub Actions workflow in the repository you chose.

Set the id-token value to write.

Write the configuration values from Step A into a file, for example config.json.

Configure the workflow to run these commands:

export MONDOO_CONFIG_PATH=/path/to/config.json
cnspec status
if [ $(echo $?) != 0 ]; then echo "failed to reach mondoo"; exit 1; fi
# run the scan
cnspec scan

Set up keyless authentication with a custom OIDC provider

Any identity provider that implements the OpenID Connect Discovery 1.0 specification can be used as a WIF provider with Mondoo.

Requirements for custom OIDC providers

Your OIDC provider must meet these requirements:

• The issuer URL must use HTTPS and serve a valid /.well-known/openid-configuration endpoint.

• The discovery document must include issuer, jwks_uri, response_types_supported, subject_types_supported, and id_token_signing_alg_values_supported.

• The JWKS endpoint must serve the public keys used to sign tokens.

Prerequisites

• Access to configure your OIDC provider and obtain tokens

• Editor or Owner privileges in the Mondoo space, organization, or platform to which your workload needs access

Step A: Create an identity provider in Mondoo

1. In the Mondoo Console, navigate to the space or organization in which you want to set up keyless access for non-human users.

2. In the left navigation, select Settings. Then select the Identity Providers tab.

   

3. Select the ADD IDENTITY PROVIDER button or the plus (+) symbol near the top-right corner of the tab and select Custom OIDC.

4. In the Issuer URL box, enter your OIDC provider's issuer URL (for example, https://login.example.com).

5. In the Subject box, enter the expected sub claim value from the tokens your provider issues.

6. In the Expiration time list, choose the duration of sessions authenticated with this identity provider.

7. Optionally, add claim mappings to verify additional identity claims beyond the subject. Use the jwt_claims.* prefix to match claims in the token:

   jwt_claims.email = user@example.com
   jwt_claims.groups = engineering

8. Optionally, configure allowed audiences to restrict which audience values are accepted in the token.

9. In the Name and Description boxes, provide a short name and longer description that help you and your teammates recognize the source and purpose of the identity provider.

10. Select the ADD IDENTITY PROVIDER button.

    Mondoo generates and displays the configuration values that you need to give your workload access.

Step B: Exchange your token for access

1. Obtain an OIDC token from your identity provider. The token must have at least 3 minutes until expiration.

2. Make a curl call to exchange the token for a short-lived Mondoo service account:

curl --request POST \
  --url 'UNIVERSE_DOMAIN/SecureTokenService/ExchangeExternalToken' \
  --header 'content-type: application/json' \
  --data '{
  "audience": "AUDIENCE",
  "issuer_uri": "ISSUER",
  "jwt_token": "TOKEN"
  }'

This call returns a Mondoo service account in the form of a base64_credential value, which your workload can use to access Mondoo by setting MONDOO_CONFIG_BASE64 to the returned value.