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 App, 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.