# Protecting your FAST API web API with Azure AD
This package allows you to protect easily your Web API, using Azure AD.
It has been created specifically for [FAST API](https://fastapi.tiangolo.com/), delivering a new [middleware](https://fastapi.tiangolo.com/tutorial/middleware/) in the pipeline to **authenticate** and **authorize** any http requests, if needed.
## Installation
To install with `pip`:
```bash
> python -m pip install aad_fastapi
```
## Usage
Once configured in Azure AD (see sections below), just add an **authentication middleware** with the `AadBearerBackend`:
``` python
from aad_fastapi import (
AadBearerBackend,
AadUser,
authorize,
oauth2_scheme,
AzureAdSettings
)
# App Registration settings for protecting all the APIs.
api_options = AzureAdSettings()
api_options.client_id = environ.get("API_CLIENT_ID")
api_options.domain = environ.get("DOMAIN")
api_options.scopes = environ.get("SCOPES")
# App Registration setting for authentication SWAGGER WEB UI AUTHENTICATION.
web_ui_client_id = environ.get("CLIENT_ID") # Client ID
web_ui_scopes = environ.get("SCOPES") # Client ID
# pre fill client id
swagger_ui_init_oauth = {
"usePkceWithAuthorizationCodeGrant": "true",
"clientId": web_ui_client_id,
"appName": "B-ID",
"scopes": web_ui_scopes,
}
# Create a FasAPI instance
app = FastAPI(swagger_ui_init_oauth=swagger_ui_init_oauth)
# Add the bearer middleware, protected with Api App Registration
app.add_middleware(AuthenticationMiddleware, backend=AadBearerBackend(api_options))
```
Once configured, you can add [authentication dependency injection](https://fastapi.tiangolo.com/advanced/security/http-basic-auth) to your routers:
``` python
# These routers needs an authentication for all its routes using Web App Registration
app.include_router(engines.router, dependencies=[Depends(oauth2_scheme(options=api_options))])
```
Or directly to your web api route:
``` python
@app.get("/user")
async def user(request: Request, token=Depends(oauth2_scheme(options=api_options))):
return request.user
```
> if you are inspecting the `request.user` object, you will find all the user's property retrieved from **Azure AD**.
You can specify **scopes** and / or **roles**, using **decorators**, to be checked before accessing your web api:
``` python
@app.get("/user_with_scope")
@authorize("user_impersonation")
async def user_with_scope(
request: Request, token=Depends(oauth2_scheme(options=api_options))
):
# code here
@app.get("/user_with_scope_and_roles")
@authorize("user_impersonation", "admin-role")
async def user_with_scope_and_roles(
request: Request, token=Depends(oauth2_scheme(options=api_options))
):
# code here
```
### Role Requirements and Multiple Roles
The `@authorize` decorator is capable of specifying multiple roles as a list of string, which will be checked against the user's roles.
If **all** the roles are found, the user is authorized.
To require the user to have **at least one** of the specified roles, you can use the `role_requirement` parameter with the
value `RoleRequirement.ANY`:
``` python
@app.get("/user_with_scope_and_roles_any")
@authorize("user_impersonation", roles=["admin","superuser"], role_requirement=RoleRequirement.ANY)
async def user_with_scope_and_roles_any(
request: Request, token=Depends(oauth2_scheme(options=api_options))
):
# code here
```
> **NOTE:** `RoleRequirement.ALL` is the default behavior and does not need to be specified.
## Register your application within your Azure AD tenant
There are two applications to register:
- First one will protect the Web API. It will only allows bearer token to access with the correct scope.
- Second one will allow the user to authenticate himself and get a token to access the Web API, using the correct scope.
### Register the Web API application
The Web API application does not need to allow user to authenticate. The main purpose of this application is to protect our Web API.
1. Navigate to the Microsoft identity platform for developers [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
1. Select **New registration**.
1. In the **Register an application page** that appears, enter your application's registration information:
- In the **Name** section, enter an application name, for example `py-api`.
- Under **Supported account types**, select **Accounts in this organizational directory only (Microsoft only - Single tenant)**.
- Select **Register** to create the application.
1. In the app's registration screen, find and note the **Application (client) ID**. You use this value in your app's configuration file(s) later in your code.
1. Select **Save** to save your changes.
1. In the app's registration screen, select the **Expose an API** blade to the left to open the page where you can declare the parameters to expose this app as an API for which client applications can obtain [access tokens](https://docs.microsoft.com/azure/active-directory/develop/access-tokens) for.
The first thing that we need to do is to declare the unique [resource](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow) URI that the clients will be using to obtain access tokens for this API. To declare an resource URI, follow the following steps:
- Click `Set` next to the **Application ID URI** to generate a URI that is unique for this app.
- For this sample, we are using the domain name and the client id as theApplication ID URI (https://{domain}.onmicrosoft.com/{clientId}) by selecting **Save**.
1. All APIs have to publish a minimum of one [scope](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code) for the client's to obtain an access token successfully. To publish a scope, follow the following steps:
- Select **Add a scope** button open the **Add a scope** screen and Enter the values as indicated below:
- For **Scope name**, use `user_impersonation`.
- Select **Admins and users** options for **Who can consent?**
- Keep **State** as **Enabled**
- Click on the **Add scope** button on the bottom to save this scope.
### Register the Client application
The Client application will allow the user to authenticate, and will expose a scope to the Web Api application.
1. Navigate to the Microsoft identity platform for developers [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.
1. Select **New registration**.
1. In the **Register an application page** that appears, enter your application's registration information:
- In the **Name** section, enter an application name that will be displayed to users, for example `py-web`.
- Under **Supported account types**, select **Accounts in this organizational directory only (Microsoft only - Single tenant)**.
1. Select **Register** to create the application.
1. In the app's registration screen, find and note the **Application (client) ID**. You use this value in your app's configuration file(s) later in your code.
1. In the app's registration screen, select **Authentication** in the menu.
- If you don't have a platform added, select **Add a platform** and select the **Web** option.
- In the **Redirect URIs** | **Suggested Redirect URIs for public clients (mobile, desktop)** section, select **http://localhost:5000/auth/oauth2-redirect**
- Select again **Add a platform** and select the **Single-page application** option.
- In the **Redirect URIs** | **Suggested Redirect URIs for public clients (mobile, desktop)** section, select **http://localhost:5000/docs/oauth2-redirect**
1. Select **Save** to save your changes.
Do not activate the implicit flow, as we are using the **new Authorization Code Flow with PKCE** (https://oauth.net/2/pkce/)
1. In the app's registration screen, click on the **Certificates & secrets** blade in the left to open the page where we can generate secrets and upload certificates.
1. In the **Client secrets** section, click on **New client secret**:
- Type a key description (for instance `sample` in our sample),
- Select one of the available key durations (**In 1 year**, **In 2 years**, or **Never Expires**) as per your security concerns.
- The generated key value will be displayed when you click the **Add** button. Copy the generated value for use in the steps later.
- You'll need this key later in your code's configuration files. This key value will not be displayed again, and is not retrievable by any other means, so make sure to note
1. In the app's registration screen, click on the **API permissions** blade in the left to open the page where we add access to the APIs that your application needs.
- Click the **Add a permission** button and then,
- Ensure that the **My APIs** tab is selected.
- In the list of APIs, select the API `py-api`.
- In the **Delegated permissions** section, select the **user_impersonation** in the list.
- Click on the **Add permissions** button at the bottom.
### Configure Known Client Applications in the Web API application
For a middle tier Web API to be able to call a downstream Web API, the middle tier app needs to be granted the required permissions as well.
However, since the middle tier cannot interact with the signed-in user, it needs to be explicitly bound to the client app in its Azure AD registration.
This binding merges the permissions required by both the client and the middle tier Web API and presents it to the end user in a single consent dialog. The user then consent to this combined set of permissions.
To achieve this, you need to add the **Application Id** of the client app (`py-web` in our sample), in the Manifest of the Web API in the `knownClientApplications` property. Here's how:
1. In the [Azure portal](https://portal.azure.com), navigate to your `py-api` app registration, and select **Expose an API** section.
1. In the textbox, fill the Client ID of the `py-web` application
1. Select the authorized scope `user_impersonation`
1. Click **Add application**
## Configure the .devcontainer
Open the project in VS Code and configure correctly the **.devcontainer/devcontainer.json** file:
``` ini
TENANT_ID={GUID} # The tenant id where you've created the application registrations
SUBSCRIPTION_ID= {GUID} # Your subscription id
DOMAIN={domain}.onmicrosoft.com # the domain name
AUTHORITY=https://login.microsoftonline.com/{tenant_id} # Authority used to login in Azure AD
# App Registration information for Web Authentication
CLIENT_ID={GUID} # This client id is the authentication client id used by the user (from `py-web` application registration)
CLIENT_SECRET= {PWD} # you
SCOPES=https://{domain}.onmicrosoft.com/{client_id}/user_impersonation : # Scope exposed to the `py-web` application
API_URL=http://localhost:8000
VAULT_NAME={Vault Name} # Optional : Key vault used to store the secret
VAULT_SECRET_KEY={Vault key} # Optional : Key vault secret's key
# App Registration information for Api Protection
API_CLIENT_ID={GUID} # Client id for the web api protection (from `py-api` application registration)
```
## Run the application
The solutions provides a `launch.json` example (in the **/.vscode** folder) that you can use to launch the demo.
1. In VS Code, select the Run and Debug blade on the left pane
1. Select the **API** sub menu item and click the green arrow (or hit **F5**)
1. Navigate to the url http://localhost:8000/docs and test the user authentication experience
> You don't need to fill the secret textbox when trying to authenticate your user, since we are using the PKCE method
Raw data
{
"_id": null,
"home_page": "https://github.com/Mimetis/aad_fastapi",
"name": "aad-fastapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "python",
"author": "S\u00e9bastien Pertus, Dor Lugasi-Gal",
"author_email": "sebastien.pertus@gmail.com, dorlugasigal@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/96/63/7cde167c18308e423ad4e177856d95030eb725158f5de3d7090d8d0605d0/aad_fastapi-1.1.4.tar.gz",
"platform": null,
"description": "# Protecting your FAST API web API with Azure AD\n\nThis package allows you to protect easily your Web API, using Azure AD.\n\nIt has been created specifically for [FAST API](https://fastapi.tiangolo.com/), delivering a new [middleware](https://fastapi.tiangolo.com/tutorial/middleware/) in the pipeline to **authenticate** and **authorize** any http requests, if needed.\n\n## Installation\n\nTo install with `pip`: \n\n```bash\n> python -m pip install aad_fastapi\n```\n\n## Usage\n\nOnce configured in Azure AD (see sections below), just add an **authentication middleware** with the `AadBearerBackend`:\n\n``` python\nfrom aad_fastapi import (\n AadBearerBackend,\n AadUser,\n authorize,\n oauth2_scheme,\n AzureAdSettings\n)\n\n# App Registration settings for protecting all the APIs.\napi_options = AzureAdSettings()\napi_options.client_id = environ.get(\"API_CLIENT_ID\")\napi_options.domain = environ.get(\"DOMAIN\")\napi_options.scopes = environ.get(\"SCOPES\")\n\n# App Registration setting for authentication SWAGGER WEB UI AUTHENTICATION.\nweb_ui_client_id = environ.get(\"CLIENT_ID\") # Client ID\nweb_ui_scopes = environ.get(\"SCOPES\") # Client ID\n\n# pre fill client id\nswagger_ui_init_oauth = {\n \"usePkceWithAuthorizationCodeGrant\": \"true\",\n \"clientId\": web_ui_client_id,\n \"appName\": \"B-ID\",\n \"scopes\": web_ui_scopes,\n}\n\n# Create a FasAPI instance\napp = FastAPI(swagger_ui_init_oauth=swagger_ui_init_oauth)\n\n# Add the bearer middleware, protected with Api App Registration\napp.add_middleware(AuthenticationMiddleware, backend=AadBearerBackend(api_options))\n```\n\nOnce configured, you can add [authentication dependency injection](https://fastapi.tiangolo.com/advanced/security/http-basic-auth) to your routers:\n\n``` python\n# These routers needs an authentication for all its routes using Web App Registration\napp.include_router(engines.router, dependencies=[Depends(oauth2_scheme(options=api_options))])\n```\n\nOr directly to your web api route:\n\n``` python\n@app.get(\"/user\")\nasync def user(request: Request, token=Depends(oauth2_scheme(options=api_options))):\n return request.user\n```\n\n> if you are inspecting the `request.user` object, you will find all the user's property retrieved from **Azure AD**.\n\nYou can specify **scopes** and / or **roles**, using **decorators**, to be checked before accessing your web api:\n\n``` python\n@app.get(\"/user_with_scope\")\n@authorize(\"user_impersonation\")\nasync def user_with_scope(\n request: Request, token=Depends(oauth2_scheme(options=api_options))\n):\n # code here\n\n@app.get(\"/user_with_scope_and_roles\")\n@authorize(\"user_impersonation\", \"admin-role\")\nasync def user_with_scope_and_roles(\n request: Request, token=Depends(oauth2_scheme(options=api_options))\n):\n # code here\n```\n\n\n### Role Requirements and Multiple Roles\nThe `@authorize` decorator is capable of specifying multiple roles as a list of string, which will be checked against the user's roles. \nIf **all** the roles are found, the user is authorized.\n\nTo require the user to have **at least one** of the specified roles, you can use the `role_requirement` parameter with the \nvalue `RoleRequirement.ANY`:\n\n``` python\n@app.get(\"/user_with_scope_and_roles_any\")\n@authorize(\"user_impersonation\", roles=[\"admin\",\"superuser\"], role_requirement=RoleRequirement.ANY)\nasync def user_with_scope_and_roles_any(\n request: Request, token=Depends(oauth2_scheme(options=api_options))\n):\n # code here\n```\n> **NOTE:** `RoleRequirement.ALL` is the default behavior and does not need to be specified.\n\n## Register your application within your Azure AD tenant\n\nThere are two applications to register:\n- First one will protect the Web API. It will only allows bearer token to access with the correct scope.\n- Second one will allow the user to authenticate himself and get a token to access the Web API, using the correct scope.\n\n### Register the Web API application\n\nThe Web API application does not need to allow user to authenticate. The main purpose of this application is to protect our Web API.\n\n1. Navigate to the Microsoft identity platform for developers [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.\n1. Select **New registration**.\n1. In the **Register an application page** that appears, enter your application's registration information:\n - In the **Name** section, enter an application name, for example `py-api`.\n - Under **Supported account types**, select **Accounts in this organizational directory only (Microsoft only - Single tenant)**.\n - Select **Register** to create the application.\n1. In the app's registration screen, find and note the **Application (client) ID**. You use this value in your app's configuration file(s) later in your code.\n1. Select **Save** to save your changes.\t\t\t\t\t\t\t\t\t\t\n1. In the app's registration screen, select the **Expose an API** blade to the left to open the page where you can declare the parameters to expose this app as an API for which client applications can obtain [access tokens](https://docs.microsoft.com/azure/active-directory/develop/access-tokens) for.\nThe first thing that we need to do is to declare the unique [resource](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow) URI that the clients will be using to obtain access tokens for this API. To declare an resource URI, follow the following steps:\n - Click `Set` next to the **Application ID URI** to generate a URI that is unique for this app.\n - For this sample, we are using the domain name and the client id as theApplication ID URI (https://{domain}.onmicrosoft.com/{clientId}) by selecting **Save**.\n1. All APIs have to publish a minimum of one [scope](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code) for the client's to obtain an access token successfully. To publish a scope, follow the following steps:\n - Select **Add a scope** button open the **Add a scope** screen and Enter the values as indicated below:\n - For **Scope name**, use `user_impersonation`.\n - Select **Admins and users** options for **Who can consent?**\n - Keep **State** as **Enabled**\n - Click on the **Add scope** button on the bottom to save this scope.\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\n### Register the Client application \n\nThe Client application will allow the user to authenticate, and will expose a scope to the Web Api application.\n\n1. Navigate to the Microsoft identity platform for developers [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page.\n1. Select **New registration**.\n1. In the **Register an application page** that appears, enter your application's registration information:\n - In the **Name** section, enter an application name that will be displayed to users, for example `py-web`.\n - Under **Supported account types**, select **Accounts in this organizational directory only (Microsoft only - Single tenant)**.\n1. Select **Register** to create the application.\n1. In the app's registration screen, find and note the **Application (client) ID**. You use this value in your app's configuration file(s) later in your code.\n1. In the app's registration screen, select **Authentication** in the menu.\n - If you don't have a platform added, select **Add a platform** and select the **Web** option.\n - In the **Redirect URIs** | **Suggested Redirect URIs for public clients (mobile, desktop)** section, select **http://localhost:5000/auth/oauth2-redirect**\n - Select again **Add a platform** and select the **Single-page application** option.\n - In the **Redirect URIs** | **Suggested Redirect URIs for public clients (mobile, desktop)** section, select **http://localhost:5000/docs/oauth2-redirect**\n1. Select **Save** to save your changes.\n\nDo not activate the implicit flow, as we are using the **new Authorization Code Flow with PKCE** (https://oauth.net/2/pkce/)\n\n1. In the app's registration screen, click on the **Certificates & secrets** blade in the left to open the page where we can generate secrets and upload certificates.\n1. In the **Client secrets** section, click on **New client secret**:\n - Type a key description (for instance `sample` in our sample),\n - Select one of the available key durations (**In 1 year**, **In 2 years**, or **Never Expires**) as per your security concerns.\n - The generated key value will be displayed when you click the **Add** button. Copy the generated value for use in the steps later.\n - You'll need this key later in your code's configuration files. This key value will not be displayed again, and is not retrievable by any other means, so make sure to note \n\n1. In the app's registration screen, click on the **API permissions** blade in the left to open the page where we add access to the APIs that your application needs.\n - Click the **Add a permission** button and then,\n - Ensure that the **My APIs** tab is selected.\n - In the list of APIs, select the API `py-api`.\n - In the **Delegated permissions** section, select the **user_impersonation** in the list.\n - Click on the **Add permissions** button at the bottom.\n\n### Configure Known Client Applications in the Web API application\n\nFor a middle tier Web API to be able to call a downstream Web API, the middle tier app needs to be granted the required permissions as well.\nHowever, since the middle tier cannot interact with the signed-in user, it needs to be explicitly bound to the client app in its Azure AD registration.\nThis binding merges the permissions required by both the client and the middle tier Web API and presents it to the end user in a single consent dialog. The user then consent to this combined set of permissions.\n\nTo achieve this, you need to add the **Application Id** of the client app (`py-web` in our sample), in the Manifest of the Web API in the `knownClientApplications` property. Here's how:\n\n1. In the [Azure portal](https://portal.azure.com), navigate to your `py-api` app registration, and select **Expose an API** section.\n1. In the textbox, fill the Client ID of the `py-web` application\n1. Select the authorized scope `user_impersonation`\n1. Click **Add application**\n\n## Configure the .devcontainer\n\nOpen the project in VS Code and configure correctly the **.devcontainer/devcontainer.json** file:\n\n``` ini\nTENANT_ID={GUID} # The tenant id where you've created the application registrations\nSUBSCRIPTION_ID= {GUID} # Your subscription id\nDOMAIN={domain}.onmicrosoft.com # the domain name\nAUTHORITY=https://login.microsoftonline.com/{tenant_id} # Authority used to login in Azure AD\n\n# App Registration information for Web Authentication\nCLIENT_ID={GUID} # This client id is the authentication client id used by the user (from `py-web` application registration)\nCLIENT_SECRET= {PWD} # you \nSCOPES=https://{domain}.onmicrosoft.com/{client_id}/user_impersonation : # Scope exposed to the `py-web` application\nAPI_URL=http://localhost:8000\nVAULT_NAME={Vault Name} # Optional : Key vault used to store the secret\nVAULT_SECRET_KEY={Vault key} # Optional : Key vault secret's key\n\n# App Registration information for Api Protection\nAPI_CLIENT_ID={GUID} # Client id for the web api protection (from `py-api` application registration)\n\n```\n\n## Run the application\n\nThe solutions provides a `launch.json` example (in the **/.vscode** folder) that you can use to launch the demo.\n\n1. In VS Code, select the Run and Debug blade on the left pane\n1. Select the **API** sub menu item and click the green arrow (or hit **F5**)\n1. Navigate to the url http://localhost:8000/docs and test the user authentication experience\n\n> You don't need to fill the secret textbox when trying to authenticate your user, since we are using the PKCE method\n",
"bugtrack_url": null,
"license": "",
"summary": "aad_fastapi middleware backend helper for bearer verification with FastAPI and Azure AD",
"version": "1.1.4",
"project_urls": {
"Bug Tracker": "https://github.com/Mimetis/aad_fastapi/issues",
"Homepage": "https://github.com/Mimetis/aad_fastapi"
},
"split_keywords": [
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "162a60b01ed42c3fffe1b83f8491b5073dd217f46d79cb192c618e2f29f5583a",
"md5": "781a8b20214b219e57c91dcdf06a9f64",
"sha256": "b70498e673bfd4dd19fd6452ec85e7fa202ad0c0bb12a3aa0848c3a6937bf298"
},
"downloads": -1,
"filename": "aad_fastapi-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "781a8b20214b219e57c91dcdf06a9f64",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17881,
"upload_time": "2023-09-12T10:03:20",
"upload_time_iso_8601": "2023-09-12T10:03:20.969202Z",
"url": "https://files.pythonhosted.org/packages/16/2a/60b01ed42c3fffe1b83f8491b5073dd217f46d79cb192c618e2f29f5583a/aad_fastapi-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96637cde167c18308e423ad4e177856d95030eb725158f5de3d7090d8d0605d0",
"md5": "f35c16733f1f4e5d172792b9e52e826f",
"sha256": "aceb4fd52e3abed1b7768b9a9d88ae2c9513acec6fddab531950b5a94b15c495"
},
"downloads": -1,
"filename": "aad_fastapi-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "f35c16733f1f4e5d172792b9e52e826f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 25198,
"upload_time": "2023-09-12T10:03:22",
"upload_time_iso_8601": "2023-09-12T10:03:22.753586Z",
"url": "https://files.pythonhosted.org/packages/96/63/7cde167c18308e423ad4e177856d95030eb725158f5de3d7090d8d0605d0/aad_fastapi-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-12 10:03:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mimetis",
"github_project": "aad_fastapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "aad-fastapi"
}
JSON
