.. yubienroll-pingone.rst


.. _pingone-config:

===========================================
Configuring YubiEnroll with PingID PingOne
===========================================

The following describes how to set up YubiEnroll in the PingID PingOne tenant and configure the required user permissions.

Configuration Steps 
===================

The configuration steps involve the following:

1. :ref:`pingone-register-oauth`
2. :ref:`pingone-permissions`
3. :ref:`pingone-register-in-yubienroll`
4. Optional, :ref:`pingone-mfa-fido-policies`
5. Optional, :ref:`pingone-custom-domains`

When you have successfully completed these steps, you are ready to :ref:`enroll YubiKeys on behalf of end users in your organization <using-cli>`.


.. _pingone-register-oauth:

Registering the YubiEnroll App
================================

Register the YubiEnroll app as an OAuth2 app. Complete the steps:

#. Create a new application. 

   a. Log in to the PingOne Console. 
   b. From the left panel, select **Applications**.
   c. Click the plus (**+**) to add a new application.
   d. Enter an **Application Name**. The example shows ``YubiEnroll-Demo-Worker-App``.
   e. Select Application Type, **Worker**.  
   f. Click **Save**.

   .. image:: graphics/pingone-add-app-1.png
      :width: 600

#. Set the Configuration. 

   a. Select the **Configuration** tab. 

   b. In OIDC Settings, select:

      * Response Type, check **Code**.
      * Grant Type:

         * Check **Authorization Code**
         * Select PKCE Enforcement under Authorization Code, **S256_REQUIRED**.
         * Check **Refresh Token**. 
      
      .. image:: graphics/pingone-edit-config-1.png
          :width: 600

   c. Enter a Redirect URI. For example, http://localhost:9443/yubienroll-callback.

      You must specify a port if you are not using URI patterns. 

   d. Select Token Endpoint Authentication Method, **None**.

   e. Click **Save**.
   
   .. image:: graphics/pingone-edit-config-2.png
      :width: 600


#. Activate the app. Click the activation toggle **On**.

   .. image:: graphics/pingone-activation-toggle.png
      :width: 800

For PingOne source content, see PingOne `Adding an Application <https://docs.pingidentity.com/pingone/applications/p1_applications_add_applications.html>`_.



.. _pingone-permissions:

Configuring Permissions 
========================

To enroll YubiKeys on behalf of an end user, the YubiEnroll app user, for example an IT admin, must have PingOne roles: ``Identity Data Admin`` and ``Environment Admin``.



.. _pingone-register-in-yubienroll:

Preparing to Add the PingOne Provider
======================================

When adding a provider configuration in YubiEnroll you need the following values from PingOne. These were created in step :ref:`pingone-register-oauth`.

#. From the PingOne Console, select the YubiEnroll app you created. The example name is ``YubiEnroll-Worker-App``. 

#. Locate required values:

   .. table:: 
       :class: longtable

       +--------------------+------------------------------------+
       | Item               | Location                           |
       +====================+====================================+
       | ``Client ID``      | General section                    |
       +--------------------+------------------------------------+
       | ``Environment ID`` | General section                    |
       +--------------------+------------------------------------+
       | ``Redirect URI``   | OIDC Settings section              |
       +--------------------+------------------------------------+
       | ``custom_domain``  | optional value                     |
       +--------------------+------------------------------------+
       | ``policy_id``      | optional value                     |
       +--------------------+------------------------------------+

   Most of the value are listed on the Configuration tab.

   .. image:: graphics/pingone-reqd-values.png
      :width: 400


To add PingOne in YubiEnroll, see :ref:`idp-config-add`.



.. _pingone-mfa-fido-policies:

Enabling MFA and FIDO2 Policies 
=================================

To enable authentication with FIDO2 devices one must create a FIDO2 policy and include it in the relevant MFA policy. By default YubiEnroll uses the default MFA policy. It is possible to use non-default policy by specifying the ``policy_id`` when creating/editing the PingOne provider. More info on FIDO2 policies can be found at `Adding a FIDO policy <https://docs.pingidentity.com/pingone/authentication/p1_creating_a_fido_policy.html>`_.


.. _pingone-custom-domains:

Using Custom Domains
=======================

PingOne supports the mapping of customer-owned and controlled domain names that are used to access user interfaces and services. By default YubiEnroll assumes no custom domains are used. It is possible to specify a custom domain by specifying the custom_domain when creating/editing the PingOne provider. More info on custom domains can be found at `Setting up a custom domain <https://docs.pingidentity.com/pingone/settings/p1_set_up_custom_domain.html>`_.