Set up the Postman collection for Environmental Credit Service (preview)

  • Article

Microsoft Cloud for Sustainability Technical Summit May 2024

Important

Some or all of this functionality is available as part of a preview release. The content and the functionality are subject to change. You can access the Environmental Credit Service (preview) sandbox environment for a 30-day trial. To use Environmental Credit Service (preview) in a production environment, complete the Environmental Credit Service (preview) sign up form.

You can copy the Postman collection and change the parameters as necessary.

Onboard Environmental Credit Service (preview) as a first-party application in your Microsoft Entra ID tenant

To authenticate with Environmental Credit Service (preview), users from your directory must present an authentication token, particularly a JSON web token, with some required claims. These claims will help Environmental Credit Service (preview) to identify the access provided to a user.

Note

Because Environmental Credit Service (preview) is a Microsoft first-party application, you can’t delete it from your tenant after deploying it.

  1. Verify that you have access to deploy Environmental Credit Service (preview) in your tenant.

    Navigate to Azure Portal > Microsoft Entra ID > User settings and check for the property Users can register applications. If it’s set to No, contact one of the Microsoft Entra ID tenant admins to set up Environmental Credit Service (preview) in your tenant.

  2. You may also need this permission to register any client or web apps in your tenant, based on the applicable scenario for your team.

  3. Follow the steps in Connect with the Microsoft Entra ID PowerShell for Graph module. These steps will set up the Microsoft Entra ID PowerShell module and connect with your Microsoft Entra ID tenant using an identity that has the permissions specified in the first step.

  4. To deploy Environmental Credit Service (preview) in your tenant, use this PowerShell command, specifying your Microsoft Entra ID PowerShell module:

       New-AzureADServicePrincipal -AppId "b9b0ac19-f710-429d-b58e-dc3f73a330a9" -DisplayName "Environmental Credit Service"

  5. After Environmental Credit Service (preview) is deployed in your tenant, navigate to Azure Portal > Microsoft Entra ID > Enterprise Applications > Choose Microsoft Applications for Application type (and Apply). Search for Environmental Credit Service (preview) to visualize the deployed enterprise app.

Set up the Postman collection

To set up the Postman collection for Environmental Credit Service (preview), follow this one-time step for every Microsoft Entra ID tenant you use that would interact with Environmental Credit Service (preview):

  1. Register a public client application in the tenant by navigating to Azure Portal > Microsoft Entra ID > App registrations > New registration. Enter the following values:

    • Name: Give a valid user-facing display name.
    • Supported account types: Choose the option Accounts in this organizational directory only, because the app won’t authenticate user accounts outside of this tenant.
    • No redirect URI is expected in this case.

  2. Select Authentication. In Advanced settings, set Treat application as a public client to Yes. Save your changes. Public client applications allow users to authenticate using mobile or desktop workflows and collect plaintext passwords using a resource-owner password credential workflow.

  3. Select the Manifest section. In the JSON editor, search for the property accessTokenAcceptedVersion and set its value to 2. Select Save to apply the changes.

  4. In this scenario, the public client attempts to use the signed-in user's token to access the Environmental Credit Service (preview) APIs. The application must request the Application.ReadWrite delegated permission as exposed by the Environmental Credit Service (preview) enterprise app registered in the prerequisite section:

    1. Navigate to the registered application, select API permissions, and then select Add a permission.
    2. Select the APIs my organization uses tab and search for the Environmental Credit Service (preview) enterprise app that was deployed in the tenant during the prerequisite steps.
    3. Select Delegated permissions. Delegated permissions require one-time user consent to indicate that the application can use their token to access the required resource. Because this scenario involves non-interactive workflow, the consent needs to be granted upfront by the tenant administrator for the required delegated permissions.

After the delegated permissions are set up, you can non-interactively request for access token using the details provided in Authorization request.

The value for the scope property in the access token request must be equal to the Application.ReadWrite scope: https://ecs.mcfs.microsoft.com/Application.ReadWrite. The call for the token endpoint can be initiated before hitting any Environmental Credit Service (preview) API.

After authentication is working, update the following Postman collection variables:

  1. Set the client ID variables to the application ID property of the public client application(s) registered in the respective Microsoft Entra ID tenant(s), as described in the previous steps.

  2. Update the username (email) and password as needed for the available variables in the Postman collection.

See also

Environmental Credit Service (preview) overview
Environmental Credit Service (preview) glossary
API reference overview for Environmental Credit Service (preview)