**Purpose**: privacyIDEA is a modular authentication system. Using privacyIDEA you can enhance your existing applications like local login, VPN, remote access, SSH connections, access to web sites or web portals with a second factor during authentication.

!!! info "Assumptions"
    It is assumed you have a provisioned virtual machine / physical machine, running Ubuntu Server 22.04 to deploy a privacyIDEA server.

## AWX Deployment
### Add Server to Inventory and Pull Inventory/Playbook Updates from Gitea
You need to target the new server using a template in AWX (preferrably).  

- We will assume the FQDN of the server is `auth.bunny-lab.io` or just `auth`
- Be sure to add the host into the [AWX Homelab Inventory File](https://git.bunny-lab.io/GitOps/awx.bunny-lab.io/src/branch/main/inventories/homelab.ini)
- Update / Sync the "**Bunny-Lab**" project in AWX ([Resources > Projects > Bunny-Lab > Sync](https://awx.bunny-lab.io/#/projects/8/details))
- Update / Sync the git.bunny-lab.io Inventory Source ([Resources > Inventories > Homelab > Sources > git.bunny-lab.io > Sync](https://awx.bunny-lab.io/#/inventories/inventory/2/sources/9/details))

### Create a Template
Next, you want to make a template to automate the deployment of privacyIDEA on any servers that are members of the `[privacyideaServers]` inventory host group.  This is useful for development / testing, as well as rapid re-deployment / scaling.

- Navigate to **Resources > Templates > Add**

| **Field** | **Value** |
| :--- | :--- |
| Template Name | `Deploy PrivacyIDEA Server` |
| Description | `Ubuntu Server 22.04 Required` |
| Project | `Bunny-Lab` *(Click the Magnifying Lens)* |
| Inventory | `Homelab` |
| Playbook | `playbooks/Linux/Deployments/privacyIDEA.yml` |
| Execution Environment | `AWX EE (latest)` *(Click the Magnifying Lens)* |
| Credentials | `SSH: (LINUX) nicole` |

**Options**:

- [X] Privilege Escalation: Checked
- [X] Enable Fact Storage: Checked

### Launch the Template
Now we need to launch the template.  Assuming all of the above was completed, we can now deploy the playbook/template against the Ubuntu Server via SSH.

- Launch the Template (Rocket Button)
- As the template runs, you will see deployment progress output on the screen

!!! success
    You will know if everything was successful if you see something that looks like the following:
    ``` sh
    ok: [auth]
    TASK [Install wget and software-properties-common] *****************************
    ok: [auth]
    TASK [Download PrivacyIDEA signing key] ****************************************
    changed: [auth]
    TASK [Add signing key for Ubuntu 22.04LTS] *************************************
    changed: [auth]
    TASK [Add PrivacyIDEA repository] **********************************************
    changed: [auth]
    TASK [Update apt cache] ********************************************************
    changed: [auth]
    TASK [Install PrivacyIDEA with Apache2] ****************************************
    changed: [auth]
    PLAY RECAP *********************************************************************auth                       : ok=7    changed=5    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
    ```

## Admin Access to WebUI
### Create a privacyIDEA Administrator Account
You will need to use the CLI in the server in order to create the first administrative account.  Run the following command and provide a password for the administrator account.
``` sh
sudo pi-manage admin add nicole.rappe -e nicole.rappe@bunny-lab.io
```

### Log into the WebUI
Assuming you created an `A` record in the DNS server pointing to the IP address of the privacyIDEA server, Navigate to https://auth.bunny-lab.io and sign in with your newly-created username and password.  (e.g. `nicole.rappe`)

## Connect to Active Directory/LDAP
### Create a LDAP User ID Resolver
This is what will connect privacyIDEA to an LDAP backend to pull-down users for authentication in Active Directory.  Begin by navigating to "**Config > Users > New LDAP Resolver**"

| **Field** | **Value** |
| :--- | :--- |
| Resolver Name | `BunnyLab-LDAP` |
| Server URI | `ldap://bunny-dc-01.bunny-lab.io, ldap://bunny-db-02.bunny.lab.io` |
| Pooling Strategy | `ROUND_ROBIN` |
| StartTLS | `<Unchecked>` |
| Base DN | `CN=Users,DC=bunny-lab,DC=io` |
| Scope | `SUBTREE` |
| Bind Type | `Simple` |
| Bind DN | `CN=Nicole Rappe,CN=Users,DC=bunny-lab,DC=io`
| Bind Password | `<Domain Admin Password for "nicole.rappe">` |

- Click the "**Preset Active Directory**" button.
- Click the "**Test LDAP Resolver**" button.

### Associate User ID Resolver with a Realm
Now we need to create what is called a "**Realm**".  Users need to be in realms to have tokens assigned. A user, who is not member of a realm can not have a token assigned and can not authenticate.  You can combine several different User ID Resolvers (see UserIdResolvers) into a realm.  Navigate to "**Config > Realms**"

| **Field** | **Value** |
| :--- | :--- |
| Realm Name | `Bunny-Lab` |
| Resolver(s) | `BunnyLab-LDAP` |

## Configure Push Notifications
### Create Policies
You will need to create several policies, you can make them all individual, or merge the ones with identical scopes together to keep things more organized.  To begin, navigate to "**Config > Policies > Create New Policy**"

- **Scope**: `Enrollment` > "**push_firebase_configuration**" = `poll only`
- **Scope**: `Enrollment` > "**push_registration_url**" = `https://auth.bunny-lab.io/ttype/push`
- **Scope**: `Enrollment` > "**push_ssl_verify**" = `0`
- **Scope**: `Authentication` > "**push_allow_polling**" = `allow`

## Enrolling the First Token
!!! bug "Push Notifications Broken"
    Currently, the push notification system (e.g. Cisco DUO") is not behaving as-expected.  For now, you can use other authentication methods for the tokens, such as HOTP (on-demand MFA codes) or TOTP (conventional time-based MFA codes).

### TOTP Token
Navigate to "**Tokens > Enroll Token**"

| **Field** | **Value** |
| :--- | :--- |
| Token Type | `TOTP` |
| Realm | `Bunny-Lab` |
| Username | `[256da6f8-9ddb-4ec5-9409-1a95fea27615] nicole.rappe (Nicole Rappe)` |

Use any MFA authenticator app like Bitwarden or Google Authenticator to add the code and store the secret key somewhere safe.

## Install Credential Provider
### Install Credential Provider Subscription File
In order to use the Credential Provider, you have to upload a subscription file.  The free-tier allows up to 50 devices using the Credential Provider, but you can alter the source code of privacyIDEA to ignore subscriptions and just unlock everything (custom python code planned).

When you want to leverage MFA in an environment using the server, you need to have a domain-joined computer running the Credential Provider, which can be found on the [Official Credential Provider Github Page](https://github.com/privacyidea/privacyidea-credential-provider/releases).

- Download the MSI
- Run the installer on the computer
- Click "**Next**"
- Check the "**Agree**" checkbox, then click "**Next**"
- Hostname: `auth.bunny-lab.io`
- Path: `/path/to/pi` 
- [x] Ignore Unknown CA Errors when Using SSL
- [x] Ignore Invalid Common Name Errors when Using SSL
- Click "**Next**" > "**Next**" > "**Next**"
- Click "**Install**" then "**Finish**"

You can now log out and verify that the credential provider is displayed as an option, and can log in using your domain username, domain password, and TOTP that you configured in the privacyIDEA WebUI.