.. yubienroll-okta.rst


.. _okta-config:

=====================
YubiEnroll with Okta
=====================

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

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

The configuration steps involve the following:

1. :ref:`Registering the YubiEnroll application in Okta <okta-register>`. 
2. :ref:`Configuring the YubiEnroll permissions in Okta <okta-permissions>`. 
3. :ref:`Adding the Okta provider in YubiEnroll <okta-add>`. 

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

.. _okta-register:

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

.. note:: To register the YubiEnroll app in the Okta tenant as described in the following, you will need *Super Admin* or *Application Admin* permissions. For more information, see :ref:`okta-permissions`.

When configuring the Okta provider in YubiEnroll, the following parameter values are needed:

* ``client_id``
* ``domain``
* ``redirect_uri``

These parameter values are created when registering the YubiEnroll (OAuth) application in Okta. To register the YubiEnroll app, open the **Admin Console**, go to **Applications** > **Applications**, and click **Create App Integration**.

* When registering YubiEnroll, ensure to select “OIDC - OpenID Connect” as the **Sign-in method** and “Native Application” as the **Application type** in the **Create new app integration** dialog.

   .. image:: graphics/okta-new-app-integration.png
      :width: 800

* When adding the redirect URI in the **New Native App Integration** dialog, the **Sign-in redirect URIs** must start with “http://localhost”. You also need to specify a port, for example “http://localhost:8080/yubienroll-redirect”.

* Ensure to select the “Refresh Token” option under **Grant type** > **Core Grants** so that the YubiEnroll app will issue a refresh token once it expires.

   .. image:: graphics/okta-app-refresh-token1.png
      :width: 800

For more details on how to register the YubiEnroll app, see `Create an OAuth 2.0 app in Okta (Okta documentation) <https://developer.okta.com/docs/guides/implement-oauth-for-okta/main/#create-an-oauth-2-0-app-in-okta>`_.

During registration, the following values needed to configure YubiEnroll are created:

* Application (client) ID 
* Directory (tenant) ID 
* Sign-in redirect URI 


.. _okta-permissions:

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

The permissions required by YubiEnroll in Okta are *okta.users.manage* and *okta.users.read*. To configure these, open the YubiEnroll app in Okta, select “Okta API scopes”, locate the scopes and click **Grant** for each of them.

.. image:: graphics/okta-permissions.png
   :width: 800

To be able to perform enroll on behalf of an end user, the user (IT admin for example) must have either the *Super Administrator*, *Group Administrator*, or *Organization Administrator* role in Okta.

.. _okta-add:

Adding the Okta Provider
==========================

Before you can run YubiEnroll with Okta, you must add the provider configuration in YubiEnroll. 

When adding a provider configuration in YubiEnroll you will need the following values, created when the :ref:`app was registered <okta-register>`: 

* Application (client) ID 
* Directory (tenant) ID 
* Redirect URI 

The “Client ID” and “Redirect URI” can be found in the **General** tab in the **Applications** view in Okta. The “Okta Domain (tenant ID)” can be found in the Okta admin dashboard when clicking on the admin profile in the upper right corner, it will be displayed under the email address.

For information on how to add a provider configuration in YubiEnroll, see :ref:`idp-config-add`. 


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

If you are using a custom domain with Okta, some applications might still require an “\*\.okta.com” sub-domain instead of a custom second level domain.

The FIDO2 credentials are registered per domain, and in cases with two domains the credentials must be registered on both. For more information, see `Register FIDO2 (WebAuthN) Keys under both Custom Domain URL and Okta Org URL (Okta documentation) <https://support.okta.com/help/s/article/To-register-FIDO2-WebAuthN-Keys-under-both-URLs-Custom-Domain-and-Okta-Org-URL?language=en_US>`_.

In a scenario when using YubiEnroll with a default Okta domain and a custom domain, you will need to register two FIDO2 credentials for an end user account. You can address this by having two enrollment profiles pointing to the same Okta tenant, but with different domains. This will result in two FIDO2 credentials being pre-registered on the YubiKey for the end user. For more information, see :ref:`enrollment-profile-create` and :ref:`command-profiles`.


.. _okta-user-search:

Searching for Users
======================

The Okta user listing shows an email address as ``username``, and ``first name + last name`` as display name. Searching for the username email address for a user does not return any results, while searching for the ``primary email address`` does.

This is because username and primary email address can be set to different values in Okta, and the YubiEnroll search does not include the username. Therefore, when searching for a user, either enter the ``firstname + lastname`` or the ``primary email address`` as search criteria to retrieve the desired results.