How to delegate user registration and product subscription

APPLIES TO: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

Delegation enables your website to own the user data and perform custom validation for users of the developer portal. With delegation, you can handle developer sign-in and sign-up (and related account management operations) and product subscription by using your existing website, instead of the developer portal's built-in functionality.

Delegating developer sign-in and sign-up

To delegate developer sign-in and sign-up and developer account management options to your existing website, create a special delegation endpoint on your site. This special delegation acts as the entry point for any sign-in/sign-up and related requests initiated from the API Management developer portal.

The final workflow consists of these steps:

1. Developer clicks the sign-in or sign-up link or an account management link at the API Management developer portal.
2. Browser redirects to the delegation endpoint.
3. Delegation endpoint in return redirects user to or presents user with sign-in/sign-up or account management UI.
4. After the operation completes, user is redirected back to the API Management developer portal at the location they left.

Set up API Management to route requests through a delegation endpoint

1. In the Azure portal, go to your API Management instance.

2. In the sidebar menu, under Developer portal, select Delegation.

3. Select the checkbox to Enable delegation.

4. Select the checkbox to enable Delegate sign-in & sign-up.

   

5. Choose the URL for your special delegation endpoint and enter it in the Delegation service endpoint field.

6. In Delegation keys:

   • Generate the Primary validation key or Secondary validation key (or both) to use by your delegation service to validate requests from API Management. Select the ellipsis (...) next to either key and then select Regenerate.
   • Select the ellipsis (...) next to either key and then select Copy. Copy the keys to a secure location, and use them when configuring your delegation service.

7. Select Save.

Create your delegation endpoint

To create a new delegation endpoint to implement on your site, follow these steps:

1. Receive a request in the following form, depending on the operation:

   http://www.yourwebsite.com/apimdelegation?operation={operation}&returnUrl={URL of source page}&salt={string}&sig={string}

   -Or-

   http://www.yourwebsite.com/apimdelegation?operation={operation}&userId={user ID of account}&salt={string}&sig={string}

   Query parameters:

   Parameter	Description
   operation	Identifies the delegation request type. Available operations: SignIn, SignUp, ChangePassword, ChangeProfile, CloseAccount, SignOut.
   returnUrl	On SignIn or SignUp, the URL of where the user clicked on a sign-in or sign-up link.
   userId	On ChangePassword, ChangeProfile, CloseAccount, and SignOut, the user ID of the account you wish to manage.
   salt	A special salt string used for computing a security hash.
   sig	A computed security hash used for comparison to your own computed hash.

2. Verify the request comes from Azure API Management (optional, but highly recommended for security).

   • Compute an HMAC-SHA512 hash of a string based on the returnUrl (or UserId) and salt query parameters. For examples, check our example code.

     For SignIn and SignUp:

     HMAC(salt + '\n' + returnUrl)
     

     For ChangePassword, ChangeProfile, CloseAccount, and SignOut:

     HMAC(salt + '\n' + userId)
     

   • Compare the above-computed hash to the value of the sig query parameter. If the two hashes match, move on to the next step. Otherwise, deny the request.

3. Verify you receive a request for a sign-in/sign-up or account management operation.

4. Present the user with sign-in/sign-up or account management UI.

5. After completing the operation on your side, manage the user in API Management. For example, if the user signs up, create a corresponding account for them in API Management.

   • Create a user with the API Management REST API.
   • Set the user ID to either the same value in your user store or a new, easily tracked ID.

6. After sign-in or sign-up, when the user is successfully authenticated:

   • Request a shared access token via the API Management REST API.

   • Append a returnUrl query parameter to the SSO URL you received from the API call above. For example:

     https://contoso.developer.azure-api.net/signin-sso?token=<URL-encoded token>&returnUrl=%2Freturn%2Furl

   • Redirect the user to the above-produced URL.

Delegating product subscription

Delegating product subscriptions works similarly to delegating user sign-in/sign-up. The final workflow consists of these steps:

1. Developer selects a product in the API Management developer portal and selects the Subscribe button.
2. Browser redirects to the delegation endpoint.
3. Delegation endpoint performs required product subscription steps, which you design. These steps could include:
   • Redirecting to another page to request billing information.
   • Asking further questions.
   • Storing the information and not requiring any user action.

Enable the API Management functionality

On the Delegation page, select the checkbox to Enable delegation, and then enable Delegate product subscription.

Create your delegation endpoint

To create a new delegation endpoint for your site, follow these steps:

1. Receive a request in the following form, depending on the operation.

   http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={product to subscribe to}&userId={user making request}&salt={string}&sig={string}

   -Or-

   http://www.yourwebsite.com/apimdelegation?operation={operation}&subscriptionId={subscription to manage}&salt={string}&sig={string}

   Query parameters:

   Parameter	Description
   operation	Identifies the delegation request type. Valid product subscription request options are: Subscribe: a request to subscribe the user to a given product with provided ID (see below). Unsubscribe: a request to unsubscribe a user from a product
   productId	On Subscribe, the product ID that the user requested subscription.
   userId	On Subscribe, the requesting user's ID.
   subscriptionId	On Unsubscribe, the product subscription ID.
   salt	A special salt string used for computing a security hash.
   sig	A computed security hash used for comparison to your own computed hash.

2. Verify that the request comes from Azure API Management (optional, but highly recommended for security).

   • Compute an HMAC-SHA512 of a string based on the productId and userId (or subscriptionId) and salt query parameters:

     For Subscribe:

     HMAC(salt + '\n' + productId + '\n' + userId)
     

     For Unsubscribe:

     HMAC(salt + '\n' + subscriptionId)
     

   • Compare the above-computed hash to the value of the sig query parameter. If the two hashes match, move to the next step. Otherwise, deny the request.

3. Process the product subscription based on the operation type requested in operation (for example: billing, further questions, etc.).

4. After completing the operation on your side, manage the subscription in API Management. For example, subscribe the user to the API Management product by calling the REST API for subscriptions.

Example code

These code samples show how to generate the hash of the returnUrl query parameter when delegating user sign-in or sign-up. The returnUrl is the URL of the page where the user clicked the sign-in or sign-up link.

• Take the delegation validation key, which you set in the Delegation screen of the Azure portal.
• Create an HMAC, which validates the signature and proves the validity of the passed returnUrl.

With slight modification, you can use the same code to calculate other hashes, such as with productId and userId when delegating product subscription.

C# code to generate hash of returnUrl

using System.Security.Cryptography;

string key = "delegation validation key";
string returnUrl = "returnUrl query parameter";
string salt = "salt query parameter";
string signature;
using (var encoder = new HMACSHA512(Convert.FromBase64String(key)))
{
    signature = Convert.ToBase64String(encoder.ComputeHash(Encoding.UTF8.GetBytes(salt + "\n" + returnUrl)));
    // change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
    // compare signature to sig query parameter
}

Node.js code to generate hash of returnUrl

var crypto = require('crypto');

var key = 'delegation validation key'; 
var returnUrl = 'returnUrl query parameter';
var salt = 'salt query parameter';

var hmac = crypto.createHmac('sha512', new Buffer(key, 'base64'));
var digest = hmac.update(salt + '\n' + returnUrl).digest();
// change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
// compare signature to sig query parameter

var signature = digest.toString('base64');

Related content

• Learn more about the developer portal
• Authenticate using Microsoft Entra ID or with Microsoft Entra External ID
• More developer portal questions? Find answers in our FAQ.