# Azure Communication Identity Package client library for Python
Azure Communication Identity client package is intended to be used to setup the basics for opening a way to use Azure Communication Service offerings. This package helps to create identity user tokens to be used by other client packages such as chat, calling, sms.
[Source code](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/communication/azure-communication-identity)
| [Package (Pypi)](https://pypi.org/project/azure-communication-identity/)
| [Package (Conda)](https://anaconda.org/microsoft/azure-communication/)
| [API reference documentation](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/communication/azure-communication-identity)
| [Product documentation](https://docs.microsoft.com/azure/communication-services/quickstarts/access-tokens?pivots=programming-language-python)
## _Disclaimer_
_Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_
# Getting started
### Prerequisites
- Python 3.7 or later is required to use this package.
- You must have an [Azure subscription](https://azure.microsoft.com/free/)
- A deployed Communication Services resource. You can use the [Azure Portal](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up.
### Install the package
Install the Azure Communication Identity client library for Python with [pip](https://pypi.org/project/pip/):
```bash
pip install azure-communication-identity
```
# Key concepts
## CommunicationIdentityClient
`CommunicationIdentityClient` provides operations for:
- Create/delete identities to be used in Azure Communication Services. Those identities can be used to make use of Azure Communication offerings and can be scoped to have limited abilities through token scopes.
- Create/revoke scoped user access tokens to access services such as chat, calling, sms. Tokens are issued for a valid Azure Communication identity and can be revoked at any time.
### Initializing Identity Client
```python
# You can find your endpoint and access token from your resource in the Azure Portal
import os
from azure.communication.identity import CommunicationIdentityClient
from azure.identity import DefaultAzureCredential
connection_str = "endpoint=ENDPOINT;accessKey=KEY"
endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
identity_client_managed_identity = CommunicationIdentityClient(endpoint, DefaultAzureCredential())
#You can also authenticate using your connection string
identity_client = CommunicationIdentityClient.from_connection_string(connection_str)
```
## Examples
The following section provides several code snippets covering some of the most common Azure Communication Services tasks, including:
- [Creating a new user](#creating-a-new-user)
- [Issuing or Refreshing an access token for a user](#issuing-or-refreshing-an-access-token-for-a-user)
- [Creating a user and a token in a single request](#creating-a-user-and-a-token-in-a-single-request)
- [Revoking a user's access tokens](#revoking-a-users-access-tokens)
- [Deleting a user](#deleting-a-user)
- [Exchanging Azure AD access token of a Teams User for a Communication Identity access token](#exchanging-azure-ad-access-token-of-a-teams-user-for-a-communication-identity-access-token)
### Creating a new user
Use the `create_user` method to create a new user.
```python
user = identity_client.create_user()
print("User created with id:" + user.properties['id'])
```
### Issuing or Refreshing an access token for a user
Use the `get_token` method to issue or refresh a scoped access token for the user. \
Pass in the user object as a parameter, and a list of `CommunicationTokenScope`. Scope options are:
- `CHAT` (Use this for full access to Chat APIs)
- `VOIP` (Use this for full access to Calling APIs)
- `CHAT_JOIN` (Access to Chat APIs but without the authorization to create, delete or update chat threads)
- `CHAT_JOIN_LIMITED` (A more limited version of CHAT_JOIN that doesn't allow to add or remove participants)
- `VOIP_JOIN` (Access to Calling APIs but without the authorization to start new calls)
```python
tokenresponse = identity_client.get_token(user, scopes=[CommunicationTokenScope.CHAT])
print("Token issued with value: " + tokenresponse.token)
```
### Issuing or Refreshing an access token with custom expiration for a user
You can specify expiration time for the token. The token can be configured to expire in as little as one hour or as long as 24 hours. The default expiration time is 24 hours.
```python
token_expires_in = timedelta(hours=1)
tokenresponse = identity_client.get_token(user, scopes=[CommunicationTokenScope.CHAT], token_expires_in=token_expires_in)
print("Token issued with value: " + tokenresponse.token)
```
### Creating a user and a token in a single request
For convenience, use `create_user_and_token` to create a new user and issue a token with one function call. This translates into a single web request as opposed to creating a user first and then issuing a token.
```python
user, tokenresponse = identity_client.create_user_and_token(scopes=[CommunicationTokenScope.CHAT])
print("User id:" + user.properties['id'])
print("Token issued with value: " + tokenresponse.token)
```
### Creating a user and a token with custom expiration in a single request
You can specify expiration time for the token. The token can be configured to expire in as little as one hour or as long as 24 hours. The default expiration time is 24 hours.
```python
token_expires_in = timedelta(hours=1)
user, tokenresponse = identity_client.create_user_and_token(scopes=[CommunicationTokenScope.CHAT], token_expires_in=token_expires_in)
print("User id:" + user.properties['id'])
print("Token issued with value: " + tokenresponse.token)
```
### Revoking a user's access tokens
Use `revoke_tokens` to revoke all access tokens for a user. Pass in the user object as a parameter
```python
identity_client.revoke_tokens(user)
```
### Deleting a user
Use the `delete_user` method to delete a user. Pass in the user object as a parameter
```python
identity_client.delete_user(user)
```
### Exchanging Azure AD access token of a Teams User for a Communication Identity access token
Use the `get_token_for_teams_user` method to exchange an Azure AD access token of a Teams User for a new Communication Identity access token.
```python
identity_client.get_token_for_teams_user(aad_token, client_id, user_object_id)
```
# Troubleshooting
The Azure Communication Service Identity client will raise exceptions defined in [Azure Core][azure_core].
# Next steps
## More sample code
Please take a look at the [samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/communication/azure-communication-identity/samples) directory for detailed examples of how to use this library to manage identities and tokens.
## Provide Feedback
If you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-python/issues) section of the project
# Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the
PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
<!-- LINKS -->
[azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python",
"name": "azure-communication-identity",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "azure,azure sdk",
"author": "Microsoft Corporation",
"author_email": "azuresdkengsysadmins@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/f6/9e/6cbc94f5c01406083960bea219ee9d9313ad925c894b6b5df3df1d3d51a0/azure-communication-identity-1.5.0.tar.gz",
"platform": null,
"description": "# Azure Communication Identity Package client library for Python\n\nAzure Communication Identity client package is intended to be used to setup the basics for opening a way to use Azure Communication Service offerings. This package helps to create identity user tokens to be used by other client packages such as chat, calling, sms.\n\n[Source code](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/communication/azure-communication-identity)\n| [Package (Pypi)](https://pypi.org/project/azure-communication-identity/)\n| [Package (Conda)](https://anaconda.org/microsoft/azure-communication/)\n| [API reference documentation](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/communication/azure-communication-identity)\n| [Product documentation](https://docs.microsoft.com/azure/communication-services/quickstarts/access-tokens?pivots=programming-language-python)\n\n## _Disclaimer_\n\n_Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_\n\n# Getting started\n### Prerequisites\n- Python 3.7 or later is required to use this package.\n- You must have an [Azure subscription](https://azure.microsoft.com/free/)\n- A deployed Communication Services resource. You can use the [Azure Portal](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up.\n### Install the package\nInstall the Azure Communication Identity client library for Python with [pip](https://pypi.org/project/pip/):\n\n```bash\npip install azure-communication-identity\n```\n\n# Key concepts\n## CommunicationIdentityClient\n`CommunicationIdentityClient` provides operations for:\n\n- Create/delete identities to be used in Azure Communication Services. Those identities can be used to make use of Azure Communication offerings and can be scoped to have limited abilities through token scopes.\n\n- Create/revoke scoped user access tokens to access services such as chat, calling, sms. Tokens are issued for a valid Azure Communication identity and can be revoked at any time.\n\n### Initializing Identity Client\n```python\n# You can find your endpoint and access token from your resource in the Azure Portal\nimport os\nfrom azure.communication.identity import CommunicationIdentityClient\nfrom azure.identity import DefaultAzureCredential\n\nconnection_str = \"endpoint=ENDPOINT;accessKey=KEY\"\nendpoint = \"https://<RESOURCE_NAME>.communication.azure.com\"\n\n# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have\n# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.\nidentity_client_managed_identity = CommunicationIdentityClient(endpoint, DefaultAzureCredential())\n\n#You can also authenticate using your connection string\nidentity_client = CommunicationIdentityClient.from_connection_string(connection_str)\n\n```\n\n## Examples\nThe following section provides several code snippets covering some of the most common Azure Communication Services tasks, including:\n\n- [Creating a new user](#creating-a-new-user)\n- [Issuing or Refreshing an access token for a user](#issuing-or-refreshing-an-access-token-for-a-user)\n- [Creating a user and a token in a single request](#creating-a-user-and-a-token-in-a-single-request)\n- [Revoking a user's access tokens](#revoking-a-users-access-tokens)\n- [Deleting a user](#deleting-a-user)\n- [Exchanging Azure AD access token of a Teams User for a Communication Identity access token](#exchanging-azure-ad-access-token-of-a-teams-user-for-a-communication-identity-access-token)\n\n### Creating a new user\n\nUse the `create_user` method to create a new user.\n```python\nuser = identity_client.create_user()\nprint(\"User created with id:\" + user.properties['id'])\n```\n\n### Issuing or Refreshing an access token for a user\n\nUse the `get_token` method to issue or refresh a scoped access token for the user. \\\nPass in the user object as a parameter, and a list of `CommunicationTokenScope`. Scope options are:\n- `CHAT` (Use this for full access to Chat APIs)\n- `VOIP` (Use this for full access to Calling APIs)\n- `CHAT_JOIN` (Access to Chat APIs but without the authorization to create, delete or update chat threads)\n- `CHAT_JOIN_LIMITED` (A more limited version of CHAT_JOIN that doesn't allow to add or remove participants)\n- `VOIP_JOIN` (Access to Calling APIs but without the authorization to start new calls)\n\n```python\ntokenresponse = identity_client.get_token(user, scopes=[CommunicationTokenScope.CHAT])\nprint(\"Token issued with value: \" + tokenresponse.token)\n```\n\n### Issuing or Refreshing an access token with custom expiration for a user\n\nYou can specify expiration time for the token. The token can be configured to expire in as little as one hour or as long as 24 hours. The default expiration time is 24 hours.\n\n```python\ntoken_expires_in = timedelta(hours=1)\ntokenresponse = identity_client.get_token(user, scopes=[CommunicationTokenScope.CHAT], token_expires_in=token_expires_in)\nprint(\"Token issued with value: \" + tokenresponse.token)\n```\n\n### Creating a user and a token in a single request\nFor convenience, use `create_user_and_token` to create a new user and issue a token with one function call. This translates into a single web request as opposed to creating a user first and then issuing a token.\n\n```python\nuser, tokenresponse = identity_client.create_user_and_token(scopes=[CommunicationTokenScope.CHAT])\nprint(\"User id:\" + user.properties['id'])\nprint(\"Token issued with value: \" + tokenresponse.token)\n```\n\n### Creating a user and a token with custom expiration in a single request\n\nYou can specify expiration time for the token. The token can be configured to expire in as little as one hour or as long as 24 hours. The default expiration time is 24 hours.\n```python\ntoken_expires_in = timedelta(hours=1)\nuser, tokenresponse = identity_client.create_user_and_token(scopes=[CommunicationTokenScope.CHAT], token_expires_in=token_expires_in)\nprint(\"User id:\" + user.properties['id'])\nprint(\"Token issued with value: \" + tokenresponse.token)\n```\n\n### Revoking a user's access tokens\n\nUse `revoke_tokens` to revoke all access tokens for a user. Pass in the user object as a parameter\n```python\nidentity_client.revoke_tokens(user)\n```\n\n### Deleting a user\n\nUse the `delete_user` method to delete a user. Pass in the user object as a parameter\n```python\nidentity_client.delete_user(user)\n```\n\n### Exchanging Azure AD access token of a Teams User for a Communication Identity access token\n\nUse the `get_token_for_teams_user` method to exchange an Azure AD access token of a Teams User for a new Communication Identity access token.\n```python\nidentity_client.get_token_for_teams_user(aad_token, client_id, user_object_id)\n```\n\n# Troubleshooting\nThe Azure Communication Service Identity client will raise exceptions defined in [Azure Core][azure_core].\n\n# Next steps\n## More sample code\n\nPlease take a look at the [samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/communication/azure-communication-identity/samples) directory for detailed examples of how to use this library to manage identities and tokens.\n\n## Provide Feedback\n\nIf you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-python/issues) section of the project\n\n# Contributing\nThis project welcomes contributions and suggestions. Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the\nPR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n<!-- LINKS -->\n[azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure Communication Identity Service Client Library for Python",
"version": "1.5.0",
"project_urls": {
"Bug Reports": "https://github.com/Azure/azure-sdk-for-python/issues",
"Homepage": "https://github.com/Azure/azure-sdk-for-python",
"Source": "https://github.com/Azure/azure-sdk-for-python"
},
"split_keywords": [
"azure",
"azure sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b1219266411a36a182e235ad9ed338a071e417d01d6804747ae959c2232399b0",
"md5": "f246d4331dc682dd209c8f7740f8b012",
"sha256": "dd6dc7aafc9f3707ffbbf40a45f2b4ccb5dc67f4d1545e74b083f83f9afa7a1a"
},
"downloads": -1,
"filename": "azure_communication_identity-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f246d4331dc682dd209c8f7740f8b012",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 65601,
"upload_time": "2024-02-15T08:20:06",
"upload_time_iso_8601": "2024-02-15T08:20:06.825577Z",
"url": "https://files.pythonhosted.org/packages/b1/21/9266411a36a182e235ad9ed338a071e417d01d6804747ae959c2232399b0/azure_communication_identity-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f69e6cbc94f5c01406083960bea219ee9d9313ad925c894b6b5df3df1d3d51a0",
"md5": "5f4832a49fe679cc1879aada98ec69e0",
"sha256": "d3186403395b78066ff30313ac119693694d2da9e0c76e9ac70eaa590dcb29e8"
},
"downloads": -1,
"filename": "azure-communication-identity-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "5f4832a49fe679cc1879aada98ec69e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 66685,
"upload_time": "2024-02-15T08:20:04",
"upload_time_iso_8601": "2024-02-15T08:20:04.324462Z",
"url": "https://files.pythonhosted.org/packages/f6/9e/6cbc94f5c01406083960bea219ee9d9313ad925c894b6b5df3df1d3d51a0/azure-communication-identity-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-15 08:20:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-communication-identity"
}
JSON
