Authentication

Article
11/29/2022

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 AD authentication Applicable similarly as Access Key Authentication. The access control is more granular and leverages Azure RBAC.
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 AD Authentication

Azure AD authentication can be used when the requestor is an Azure RBAC security principal. Security principal can be user, group, service principal, or managed identity.

Before getting started, ensure you have:

Your Azure service principal
The URL Path and HTTP Verb that you're calling

For how to get a service principal, see - Create an Azure Active Directory service principal application from the Azure CLI.

Once you have created a service principal, you can use one of its secrets for authentication to access Communication Services for creating users, issuing user access tokens, or sending SMS messages.

Using security principal credential in a request

After you have the ID and a secret of a security principal, you can use them in your requests to Azure Communication Services' REST API by supplying them in the 'Authorization' header.

authorizationHeaderValue = convertToBase64String(<security principal ID> + ":" + <secret of the security principal>)
Authorization="BASIC <authorizationHeaderValue>"

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>.