Authorization

Accounts come in two flavors: User and ApiAccount. Either may be authorized for any “resource action,” which are privileges that are scoped to a type of resource. Learn more about CloudZiti authorization in the Authorization API reference.

Grant a Resource Action to an Identity with REST

Objective

Grant permission to Alice to reset any users’ secondary authentication factor (MFA).

Setup

This guide uses jq and http (HTTPie) to send REST calls and parse responses.

You can install nfctl with pip install netfoundry. The following setup step will configure the current shell with the necessary environment variables to complete the rest of the steps in this guide. Learn more about using the CLI in the CLI guide. Learn more about authentication in the Authentication guide.

eval "$(nfctl login --eval)"

You may skip using this CLI step if you set environment variable NETFOUNDRY_API_TOKEN to an API bearer token, and MOPENV to the name of the CloudZiti environment to which your account belongs, e.g. MOPENV=production.

Steps

1. Find the ID of the account you wish to grant a resource action to. You can find the ID of your own account by running nfctl get identity. You can find the ID of another account by running nfctl list identities for using the Identity API. Let’s find Alice’s account ID.

    ACCOUNT=$(
      http GET "https://gateway.${MOPENV}.netfoundry.io/identity/v1/identities" \
        "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}" \
      | jq -r '.[]|select(.email == "alice@example.com")|.id'
    )
   

2. Find the ID of the resource type you wish to grant a resource action on. For this example we’ll use code user-identity. This isn’t strictly necessary, but is useful for filtering the available resource actions by their applicable resource types.

    RESOURCE_TYPE=$(
      http GET "https://gateway.${MOPENV}.netfoundry.io/auth/v1/resource-types" \
        "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}" \
      | jq -r '.[]|select(.code == "user-identity")|.id'
    )
   

3. Find the ID of the resource action to grant. This will filter for action code update-reset-mfa.

    RESOURCE_ACTION=$(
      http GET "https://gateway.${MOPENV}.netfoundry.io/auth/v1/resource-actions?resourceTypeId=${RESOURCE_TYPE}" \
        "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}" \
      | jq -r '.[]|select(.code == "update-reset-mfa")|.id'
    )
   

4. Grant the action to the identity on the resource type with the network scope.

    http POST https://gateway.${MOPENV}.netfoundry.io/auth/v1/identity-resource-actions \
      "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}" \
      identityId=${ACCOUNT} \
      resourceActionId=${RESOURCE_ACTION} \
      path=[]
   

5. Verify the action is now granted.

    http GET "https://gateway.${MOPENV}.netfoundry.io/auth/v1/grants?resourceActionId=${RESOURCE_ACTION}&identityId=${ACCOUNT}" \
      "Authorization: Bearer ${NETFOUNDRY_API_TOKEN}"