Metadata-Version: 2.4
Name: eam_b2c_helper
Version: 0.1.66
Summary: A package to interact with ms graph /users functionality
Author-email: Dave Gunn <daveg@8amsolutions.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# eam_b2c_helper

This package is used to add data to Cosmos DB, which is required during onboarding of a client or adding a new vendor to the 8am system. It provides the `B2CHelper` class for interacting with Azure AD B2C via the Microsoft Graph API, along with helper classes for managing user relations in Cosmos DB and retrieving secrets from Azure Key Vault.

## Installation

```bash
pip install eam_b2c_helper
```

## Usage

### Constructor

```python
from eam_b2c_helper.b2c import B2CHelper

b2c = B2CHelper({
    'grant_type': 'client_credentials',
    'user_mgmt_client_id': '<client id>',
    'scope': 'https://graph.microsoft.com/.default',
    'user_mgmt_client_secret': '<client secret>',
    'tenant_id': '<b2c tenant id>',
    'ext_app_client_id': '<extension app client id>'
})
```

An optional `db` parameter (a `DatabaseHelper` from `eam_db_helper`) can be provided to automatically create user relation records in Cosmos DB when users are created.

### Environment Variables

The following environment variables are required when creating or updating local (non-federated) users, as the password is retrieved from Azure Key Vault:

- `KEY_VAULT_URL` - The Key Vault URL
- `KEY_VAULT_APP_REG_SECRET` - The service principal client secret used to authenticate to Key Vault

Passwords are fetched based on role: `8am-admin-password` for `8amAdmin` users, `8am-default-password` otherwise.

## Methods

### B2CHelper.get_token()

This method is used to get the token from the MS AD B2C. It uses the token request data provided in the constructor and returns the access token string.

### B2CHelper.get_auth_header()

This method is used to get the authorization header for the MS AD B2C. It uses the token string returned from the `get_token()` method and structures it into a Bearer token along with the Content-Type header for ease of use.

### B2CHelper.create_user()

This method is used to add a new user to the MS AD B2C directory. It takes the user details and the b2c prefix as parameters and returns the response from the MS Graph API. An optional `branch_id` can be provided, which appends the branch id to the user's email address (e.g. `user+branch@domain.com`).

If a database helper was provided to the constructor, a user relation record is also created in Cosmos DB.

```python
response = b2c.create_user({
    'firstName': 'Dave',
    'lastName': 'G',
    'email': 'dave@example.com',
    'phone': '1234567890',
    'role': 'Admin',
    'company_id': '12345',
    'sign_up_code': '12345',
    'reset_password': False
}, 'eightam72045b2ctenant')
```

### B2CHelper.create_users()

This method is used to add a list of new users to the MS AD B2C directory. It takes a list of user details and the b2c prefix as parameters and returns a list of responses from the MS Graph API. Supports the same optional `branch_id` behavior as `create_user()`.

### B2CHelper.update_user()

This method is used to update a user in the MS AD B2C directory. It takes the user details (including the user `id`) and the b2c prefix as parameters and returns the response from the MS Graph API. An optional `reactivate` flag can be passed to include the password profile in the update (e.g. when reactivating a deleted user).

### B2CHelper.update_users()

This method is used to update a list of users in the MS AD B2C directory. It takes a list of user details and the b2c prefix as parameters and returns a list of responses from the MS Graph API.

### B2CHelper.delete_user()

This method is used to delete a user from the MS AD B2C directory. It takes the user id as a parameter and returns the response from the MS Graph API.

### B2CHelper.delete_users()

This method is used to delete a list of users from the MS AD B2C directory. It takes a list of user ids as a parameter and returns a list of responses from the MS Graph API.

### B2CHelper.get_user()

This method is used to get a user from the MS AD B2C directory. It takes the user id as a parameter and returns the user as a dictionary.

### B2CHelper.get_user_by_email()

This method is used to get a user from the MS AD B2C directory by email. It takes the email address as a parameter and returns the user as a dictionary.

### B2CHelper.get_users()

This method is used to get a list of users from the MS AD B2C directory. It optionally takes a `company_id`, `role_type`, or `branch_id` to filter the results, and returns the users as a list.

## Helper Functions

### build_user_object()

This function is used to format the user object according to the MS AD schema. It takes the user details object from the 8am Web App front end, along with the extension id and b2c prefix, and returns the formatted user object. The last 4 fields within the user object are custom fields which use the extension id to denote them as such. Federated users (with `signInType: 'federated'`) are built via `build_federated_user_object()`; all others via `build_local_user_object()`.

## Common Classes

### UserRelation

The `UserRelation` class (in `common/user_relation.py`) manages the relationship between users and companies in Cosmos DB. It is used automatically by `B2CHelper.create_user()` and `B2CHelper.create_users()` when a database helper is provided.

- `UserRelation(db, user_id)` - constructs the relation helper
- `create_user_relation(company, user, userId)` - creates (or updates) a `userRelation` record in Cosmos DB. Records for `8amadmin` emails are returned but not persisted.

### KeyVaultHelper

The `KeyVaultHelper` class (in `common/keyvault_helper.py`) provides Azure Key Vault operations using a service principal client secret.

- `KeyVaultHelper(vault_url, client_secret)` - constructs the helper
- `get_secret(secret_name)` - retrieves the value of a secret by name
- `set_secret(secret_name, secret_value)` - creates or updates a secret
- `list_secrets()` - lists all secret names in the vault



get_user()

This function is used to get a user from the MS AD B2C directory. It takes the user id as a parameter, removes the @odata.context field and returns the single user object.



compile_entire_user_list()

This function is used to get the entire list of users from the MS AD B2C directory. As a default, the MS Graph API returns 100 users per page, this function will use the @odata.nextLink field to get the next page of users until there are no more pages left. It returns a list of user objects, combined from each successive call made to the MS Graph API. This function uses the argument filter_extension to filter users by either company, user role, or nothing at all (return all users from the directory).



get_users()

This function is used to get a list of users from the MS AD B2C directory. It takes a company id and a user role as optional parameters and returns a list of user objects, possibly filtered by the company and user role. Based off of what parameters are passed, it will call the compile_entire_user_list() function with the appropriate filter_extension. The filter extension is added to the suffix of the MS Graph API call to filter the users.



create_user()

This function is used to create a new user in the MS AD B2C directory. It takes the user_details object from the 8am Web App front end, along with extension_id and b2c_prefix (B2C parameters) and returns the response from the MS Graph API.



create_users()

This function is used to create multiple users in the MS AD B2C directory. It takes a list of user_details objects from the 8am Web App front end, along with extension_id and b2c_prefix (B2C parameters) and returns the response from the MS Graph API.



update_user()

This function is used to update a user in the MS AD B2C directory. It takes the user_details object from the 8am Web App front end, along with extension_id and b2c_prefix (B2C parameters) and returns the response from the MS Graph API.



update_users()

This function is used to update multiple users in the MS AD B2C directory. It takes a list of user_details objects from the 8am Web App front end, along with extension_id and b2c_prefix (B2C parameters) and returns the response from the MS Graph API.



delete_user()

This function is used to delete a user from the MS AD B2C directory. It takes the user_id from the 8am Web App front end and returns the response from the MS Graph API.



delete_users()

This function is used to delete multiple users from the MS AD B2C directory. It takes a list of user_ids from the 8am Web App front end and returns the response from the MS Graph API.



