Sign in to the Azure Portal and search for "App registrations" in the top search bar. Click on App registrations under Services, then click New registration.

Give your application a descriptive name, something like "MyIntranet Viva Engage Integration". Under Supported account types, choose Accounts in this organizational directory only (Single tenant) unless you're building a multi-tenant app for multiple organizations. For the Redirect URI, select Web and enter the callback URL your PHP application will handle, for example:

https://yourdomain.com/auth/microsoft/callback

For local development, add:

http://localhost:8080/auth/microsoft/callback

Click Register. Azure will create the app and take you to its overview page. Copy the Application (client) ID and Directory (tenant) ID, you'll need both.

In the left sidebar, click Certificates & secrets, then New client secret. Give it a description and choose an expiry period. After you click Add, the secret value is shown once. Copy it immediately and store it securely, you cannot retrieve it again after navigating away.

Click API permissions in the left sidebar, then Add a permission. In the panel that opens, scroll down and select Yammer (this is the underlying API for Viva Engage). Under Delegated permissions, check:

• user_impersonation, allows the app to access Yammer/Viva Engage as the signed-in user

Click Add permissions. If your organization requires admin consent for delegated permissions (common in enterprise environments), click Grant admin consent for [your tenant] and confirm. Without this step, users may see a consent screen they can't dismiss.

In your project root, run the following to install the OAuth2 client library and a dotenv loader for managing your credentials:

composer require league/oauth2-client vlucas/phpdotenv

If you're using Laravel, the OAuth client is already available and you can use Laravel Socialite or Passport instead, but this guide covers the framework-agnostic approach that works with any PHP application.

Create a .env file in your project root (and add it to .gitignore immediately):

AZURE_CLIENT_ID=your-application-client-id-here
AZURE_CLIENT_SECRET=your-client-secret-here
AZURE_TENANT_ID=your-directory-tenant-id-here
AZURE_REDIRECT_URI=https://yourdomain.com/auth/microsoft/callback
APP_SESSION_SECRET=a-long-random-string-for-session-signing
VIVA_ENGAGE_NETWORK=yourcompany.onmicrosoft.com

Create a file at src/Auth/MicrosoftProvider.php. The league/oauth2-client package doesn't include a Microsoft-specific provider by default, so we'll configure the authorization and token endpoints manually:

<?php

namespace App\Auth;

use League\OAuth2\Client\Provider\GenericProvider;
use Dotenv\Dotenv;

class MicrosoftProvider
{
    public static function create(): GenericProvider
    {
        $tenantId = $_ENV['AZURE_TENANT_ID'];

        return new GenericProvider([
            'clientId'                => $_ENV['AZURE_CLIENT_ID'],
            'clientSecret'            => $_ENV['AZURE_CLIENT_SECRET'],
            'redirectUri'             => $_ENV['AZURE_REDIRECT_URI'],
            'urlAuthorize'            => "https://login.microsoftonline.com/{$tenantId}/oauth2/v2.0/authorize",
            'urlAccessToken'          => "https://login.microsoftonline.com/{$tenantId}/oauth2/v2.0/token",
            'urlResourceOwnerDetails' => 'https://graph.microsoft.com/v1.0/me',
            'scopes'                  => 'openid profile email https://api.yammer.com/user_impersonation',
            'scopeSeparator'          => ' ',
        ]);
    }
}

Create auth/login.php. This file redirects the user to Microsoft's login page:

<?php

require_once __DIR__ . '/../vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

session_start();

$provider = App\Auth\MicrosoftProvider::create();

// Generate and store CSRF state token
$state = bin2hex(random_bytes(16));
$_SESSION['oauth2_state'] = $state;

$authorizationUrl = $provider->getAuthorizationUrl([
    'state' => $state,
    'response_type' => 'code',
]);

header('Location: ' . $authorizationUrl);
exit;

Create auth/callback.php. This handles the redirect back from Microsoft and exchanges the authorization code for an access token:

<?php

require_once __DIR__ . '/../vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

session_start();

// CSRF state validation
if (empty($_GET['state']) || $_GET['state'] !== $_SESSION['oauth2_state']) {
    unset($_SESSION['oauth2_state']);
    http_response_code(403);
    echo 'Invalid OAuth state. Please try logging in again.';
    exit;
}

if (!empty($_GET['error'])) {
    $error = htmlspecialchars($_GET['error'], ENT_QUOTES, 'UTF-8');
    $description = htmlspecialchars($_GET['error_description'] ?? '', ENT_QUOTES, 'UTF-8');
    echo "Authorization error: {$error}, {$description}";
    exit;
}

$provider = App\Auth\MicrosoftProvider::create();

try {
    $accessToken = $provider->getAccessToken('authorization_code', [
        'code' => $_GET['code'],
    ]);

    // Store token data in session
    $_SESSION['viva_access_token'] = $accessToken->getToken();
    $_SESSION['viva_token_expires'] = $accessToken->getExpires();
    $_SESSION['viva_refresh_token'] = $accessToken->getRefreshToken();

    // Redirect to the page that initiated the login
    $returnTo = $_SESSION['return_to'] ?? '/';
    unset($_SESSION['return_to']);
    header('Location: ' . $returnTo);
    exit;

} catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $e) {
    error_log('OAuth token exchange failed: ' . $e->getMessage());
    echo 'Authentication failed. Please try again.';
    exit;
}

Access tokens expire. Create src/Auth/TokenManager.php to handle automatic refresh:

<?php

namespace App\Auth;

class TokenManager
{
    public static function getValidToken(): ?string
    {
        if (empty($_SESSION['viva_access_token'])) {
            return null;
        }

        // If token expires within 5 minutes, refresh it
        $buffer = 300;
        if (!empty($_SESSION['viva_token_expires']) &&
            $_SESSION['viva_token_expires'] - $buffer < time()) {

            if (empty($_SESSION['viva_refresh_token'])) {
                return null;
            }

            $provider = MicrosoftProvider::create();

            try {
                $newToken = $provider->getAccessToken('refresh_token', [
                    'refresh_token' => $_SESSION['viva_refresh_token'],
                ]);

                $_SESSION['viva_access_token'] = $newToken->getToken();
                $_SESSION['viva_token_expires'] = $newToken->getExpires();
                $_SESSION['viva_refresh_token'] = $newToken->getRefreshToken();

            } catch (\Exception $e) {
                // Refresh failed, user needs to log in again
                unset(
                    $_SESSION['viva_access_token'],
                    $_SESSION['viva_token_expires'],
                    $_SESSION['viva_refresh_token']
                );
                return null;
            }
        }

        return $_SESSION['viva_access_token'];
    }
}

Navigate to the Viva Engage community you want to embed in a browser. Look at the URL, it will be structured like:

https://web.yammer.com/main/org/yourcompany.onmicrosoft.com/groups/eyJfdHlwZSI6Ikdyb3VwIiwiaWQiOiIxMjM0NTY3In0/all

The encoded segment after /groups/ is the group/community ID. You can also use the Viva Engage API to retrieve it programmatically. For the Embed SDK, you'll primarily need the feedType (group, topic, user, or open-graph) and the feedId.

To get the numeric group ID, call the Yammer API with your access token:

GET https://www.yammer.com/api/v1/groups.json
Authorization: Bearer {your_access_token}

Each group object in the response has an id field, that's your feedId.

Create pages/community.php. This page checks for a valid token, initiates login if needed, then renders the Viva Engage embed:

<?php

require_once __DIR__ . '/../vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

session_start();

use App\Auth\TokenManager;

$token = TokenManager::getValidToken();

if ($token === null) {
    // Store the current URL so we can return here after login
    $_SESSION['return_to'] = $_SERVER['REQUEST_URI'];
    header('Location: /auth/login.php');
    exit;
}

// Pass token to JavaScript safely, never expose full token in page source
// in a real application; use a server-side proxy endpoint instead.
// For this example, we're encoding it for the SDK initialization.
$safeToken = htmlspecialchars($token, ENT_QUOTES, 'UTF-8');
$feedId = '1234567'; // Replace with your actual community ID
$networkPermalink = htmlspecialchars($_ENV['VIVA_ENGAGE_NETWORK'], ENT_QUOTES, 'UTF-8');

?>

<!-- Include the Viva Engage Embed SDK -->
<script type="text/javascript" src="https://c64.assets-yammer.com/assets/platform_embed.js"></script>

<div id="viva-engage-container" style="width: 100%; min-height: 400px;"></div>

<script>
(function() {
    yam.config({
        network: '<?php echo $networkPermalink; ?>',
        appClientId: '<?php echo htmlspecialchars($_ENV['AZURE_CLIENT_ID'], ENT_QUOTES, 'UTF-8'); ?>',
    });

    yam.connect.loginWithRedirect(
        function(resp) {
            // Login successful, render the feed
            yam.render({
                container: '#viva-engage-container',
                network: '<?php echo $networkPermalink; ?>',
                appClientId: '<?php echo htmlspecialchars($_ENV['AZURE_CLIENT_ID'], ENT_QUOTES, 'UTF-8'); ?>',
                feedType: 'group',
                feedId: '<?php echo htmlspecialchars($feedId, ENT_QUOTES, 'UTF-8'); ?>',
                config: {
                    use_sso: false,
                    header: false,
                    footer: false,
                    showOpenGraphPreview: false,
                    defaultToCanonical: false,
                    hideNetworkName: true,
                    promptText: 'Start a conversation...'
                }
            });
        },
        function(resp) {
            // Login failed or user cancelled
            document.getElementById('viva-engage-container').innerHTML =
                '<p>Please sign in to view community discussions.</p>';
        }
    );
})();
</script>

Embedding the access token directly in page HTML is acceptable for internal apps but not ideal for production. Instead, create a server-side endpoint that the Embed SDK can use to silently refresh authentication. Create api/token.php:

<?php

require_once __DIR__ . '/../vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

session_start();

use App\Auth\TokenManager;

header('Content-Type: application/json');
header('Cache-Control: no-store');

$token = TokenManager::getValidToken();

if ($token === null) {
    http_response_code(401);
    echo json_encode(['error' => 'not_authenticated']);
    exit;
}

// Return only what the SDK needs, never return the full token to untrusted clients
echo json_encode([
    'authenticated' => true,
    'token_hint' => substr($token, 0, 10) . '...' // for debugging only
]);