Guides

OAuth Setup Guide for Azure AD Applications: Permission API Integration

This guide outlines the setup steps required to configure Azure AD applications for secure integration between z-PAX Login Service and the Permission API.

1. Create App Registration: Permission API

  1. Register a new Azure AD application named Permission API.
  2. Obtain the Application ID URI (typically in the format: api://<permission-app-guid>).
    • This can be found or configured under the Expose an API tab in the Azure portal.

2. Define App Role

  1. In the Permission API app registration, navigate to App roles.
  2. Create an app role named:
    • Name: Zpax.Permission
  3. Set Allowed Member Types to Application (enabling client credentials flow for service-to-service access).

3. Create App Registration: Zpax Login Service

Register another Azure AD application named Zpax Login Service.

4. Configure API Permissions for Login Service

  1. In the Zpax Login Service registration, open API Permissions.
  2. Click Add a permission > My APIs > Permission API.
  3. Under Application Permissions, add the Zpax.Permission role.
  4. Click Grant admin consent to approve permissions tenant-wide.

5. Generate Client Secret

  1. In the Zpax Login Service registration, navigate to Certificates & Secrets.
  2. Generate a new client secret.
  3. Record the secret securely — it will be required for token acquisition.

6. Information to Share with z-PAX Team

Provide the following details securely to the z-PAX integration team:

  • Permission API Application ID URI: api://<permission-app-guid>
  • Zpax Login Service Tenant ID
  • Zpax Login Service Client ID
  • Zpax Login Service Client Secret

7. Token Request by z-PAX

z-PAX will request an OAuth 2.0 token from Azure AD’s token endpoint:

POST https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<client-id>&
client_secret=<client-secret>&
scope=api://<permission-app-guid>/.default&
grant_type=client_credentials