Authentication

Article
07/23/2024

When making REST Calls, several steps are required to authenticate properly. Azure Communication Services SDKs handle this process for you, but making requests manually means you'll need to handle it yourself.

Types of Authentication

Azure Communication Services has three types of Authentication, they're used for different purposes:

Access Key authentication for SMS, Network Traversal, Call Automation, Identity, and access token operations. Access Key authentication is suitable for applications running in a trusted service environment.
Azure RBAC authentication to control access to resources by leveraging Azure RBAC by assigning Azure roles.
User Access Token authentication for Chat and Calling. User access tokens let your client applications authenticate directly against Azure Communication Services. These tokens are generated on a server-side token provisioning service that you create. They're then provided to client devices that use the token to initialize the Chat and Calling client libraries.

Access Key Authentication

Access Key authentication is used when requests aren't made by your end-user application. Run these requests within a trusted service environment.

In this authentication method, requests are signed using a client-generated hash-based message authentication code(HMAC).

Before getting started, ensure you have:

Your Azure Communication Services Access Key
Your Azure Communication Service Endpoint
The URL Path and HTTP Verb that you're calling
A development environment, which can generate HMACs, SHA256 hashes, and perform Base64 operations.

Once you have these items, you can continue with signing your request.

Signing an HTTP Request

Make sure you have the following values available:
- HTTP request method (for example, GET or PUT)
- Coordinated Universal Time (UTC) timestamp for the request according to the RFC1123 standard
- HTTP request host (the <authority> URI component as specified in RFC2396)
- HTTP request body hashed using the SHA256 algorithm
- HTTP request path (the <path> and <query> concatenated by ? components as specified in RFC2396)
```
Verb=<http_method>
Timestamp=<current_datetime>
Host=<uri_authority>
ContentHash=SHA256(<request_body>)
URIPathAndQuery=<uri_path>?<uri_query>
```

Construct the string to be signed by concatenating the values in the following way:

StringToSign=Verb + "\n"
URIPathAndQuery + "\n"
Timestamp + ";" + Host + ";" + ContentHash

Generate an HMAC-256 signature of the UTF-8 encoded string that you created in the previous step. Next, encode your results as Base64. You also need to Base64-decode your access key. Use the following format (shown as pseudo-code):
```
Signature=Base64(HMAC-SHA256(UTF8(StringToSign), Base64.decode(<your_access_key>)))
```

Add the following headers to the request:

x-ms-date: <Timestamp>
x-ms-content-sha256: <ContentHash>
host: <URIPathAndQuery>   
Authorization: "HMAC-SHA256 SignedHeaders=x-ms-date;host;x-ms-content-sha256&Signature=<Signature>"

Upon receiving the request, the service validates the signature and timestamp to guard against certain security attacks, including replay attacks. To learn how to sign the HTTP request in various programming languages, visit the HMAC header signing tutorial.

Azure RBAC Authentication

The Azure platform provides role-based access (Azure RBAC) to control access to the resources. Azure RBAC security principal represents a user, group, service principal, or managed identity that is requesting access to Azure resources.

Microsoft Entra authentication provides superior security and ease of use over other authorization options. For example, by using managed identity, you avoid having to store your account access key within your code, as you do with Access Key authentication. While you can continue to use Access Key authentication with communication services applications, Microsoft recommends moving to Microsoft Entra ID where possible.

Azure RBAC includes many built-in roles, can be assigned at different scopes, and allows you to create your own custom roles. It includes over 100 built-in roles. There are five fundamental Azure roles - Owner, Contributor, Reader, Role Based Access Control Administrator and User Access Administrator. For more information on these roles, visit the Role-based access control tutorial.

Permissions Supported by Azure Communication Services (ACS)

ACS offers specific permissions (acs.read and acs.write) that allow controlled access to various resources.

acs.read permission: grants the ability to retrieve or view data.
acs.write permission: permits modification or creation of data within those same resource types.

Additionally, ACS supports email-related permissions:

acs.email.read: enables reading or accessing email-related services data.
acs.email.write: allows modification or creation of email-related services data.

These permissions are crucial for ensuring granular access control and security over ACS resources.

Obtaining Additional RBAC Token

To acquire a token for ACS, you can use MSAL (Microsoft Authentication Library). Here's a step-by-step guide:

Register an Application in Azure AD: Ensure your app is registered in Azure AD.
Install MSAL: Install the MSAL library for your platform (e.g., Microsoft.Identity.Client for .NET).
Configure MSAL: Set up MSAL with your application's client ID, tenant ID, and client secret.
Acquire a Token: Use MSAL to acquire a token with the necessary scope (https://communication.azure.com/.default).

For detailed instructions and code examples, refer to the official MSAL documentation and Access Token documentation.

Example HTTP Request to Issue ACS Access Token

Request:

POST https://my-resource.communication.azure.com/identities/{identity}/:issueAccessToken?api-version=2023-10-01
Authorization: Bearer <your-access-token>
Content-Type: application/json
{
  "scopes": [
    "chat",
    "voip"
  ]
}

Response:

{
  "token": "token",
  "expiresOn": "2023-10-10T21:39:39.3244584+00:00"
}

Helpful links on Azure RBAC

User Access Token Authentication

User access tokens let your client applications authenticate directly against Azure Communication Services as a particular user or identity.

Generating / Obtaining a User Access Tokens

User Access Tokens are generated by you within a trusted environment. Generating them using the Azure Communication Services Identity SDK is the easiest way. For more information, see creating and managing user access tokens.

Using a User Access Token in a request

Once you have a suitable User Access Token, you can include it in your requests to Azure Communication Services' REST API. To do so, you need to supply it within the Authorization header using the Bearer HTTP authentication scheme Authorization: Bearer <token>.

Share via