# Introduction

This guide walks you through the steps to configure a Synqly Identity connector for your Okta tenant. You can authenticate the connector either using an [API Service Integration](https://help.okta.com/en-us/content/topics/apiservice/api-service-integrations.htm), or using an [App Integration](https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/#create-a-service-app-integration). For most use cases API Service Integration based authentication should be preferred, but App Integrations are available for advanced Okta users who need more control over how the connector authenticates.

# Set Up Okta Authentication

API Service Integration (Recommended)
To connect with Okta, add the Synqly Identity Connector application to your Okta instance. This is an API Service Integration that gives Synqly the required access and privileges.

Log in to Okta with a user that has admin privileges and navigate to the Admin portal. From the Admin portal, follow these steps:

* Go to **Applications > API Service Integrations**
* Click **Add Integration**
* Find and select the 'Synqly Identity Connector', then click **Next**
* Click **Install and Authorize**


Once the application is installed and authorized, note your **Client Secret**, **Client ID**, and **Okta Domain** in a safe location. You will supply these values to your Synqly powered application to complete setup.

## Configuring the Integration

| Integration Parameters | Description |
|  --- | --- |
| Client ID | The **Client ID** you noted earlier. |
| Client Secret | The **Client Secret** you noted earlier. |
| Base URL | THe **Okta Domain** you noted earlier. |


App Integration
You can connect with Okta using a service app integration. While this setup process is more involved, it allows you to exercise finer-grained control over the permissions assigned to the Synqly integration. This can be valuable if you need to disable permissions associated with Synqly features you do not plan to use.

This authorization method is intended for advanced use cases. You should only use this approach if the API Service Integration is not suitable for your needs.

To connect to Okta using a service app integration, follow the steps below:

1. Follow the [Okta documentation for creating a service app integration](https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/#create-a-service-app-integration).
2. Navigate to the main page for your app integration, navigate to the **General** tab.
3. Note down the **Client ID**.
4. Edit the **Client Credentials > Client authentication** setting to **Public key / Private key**.
5. Click on **PUBLIC KEYS > Add**.
6. In the dialog that appears, click **Generate new key**.
7. Click the **PEM** buttun under **Private key**. Note down the **Private key**.
8. Click **Save**.
9. Uncheck **General Settings > Proof of posession > Require Demonstrating Proof of Posession (DPoP) header in token requests**.
10. Navigate to the **Okta API Scopes** tab, then grant the scopes you would like to enable. You may wish to consider granting the following scopes:
  * `okta.groups.read` - required to list groups, list group members.
  * `okta.users.manage` - required to force password reset, expire sessions, and enable/disable users.
  * `okta.users.read` - required to list users, read individual users. Not required if `okta.users.manage` is also granted.
  * `okta.roles.read` - required to read individual users.
  * `okta.logs.read` - required to access the audit log.
11. Navigate to the **Admin roles** tab.
12. Click **Admin assignments granted to this app > Edit assignments**.
13. Assign the desired admin roles.
  * To access audit logs, you must assign the **Read-only Admin** role, or another standard administrator role which has the **View System Log (system events)** permission. Consult [the Okta documentation](https://help.okta.com/en-us/content/topics/security/administrators-admin-comparison.htm) for a complete list of applicable roles. Keep in mind that [custom admin roles may not be assigned the **View System Log (system events)** permission](https://support.okta.com/help/s/article/Can-custom-Admin-roles-view-system-logs?language=en_US).
  * To list users, you must assign a role with the **User > View users  and their details** permission.
  * To list groups, you must assign a role with the **Group > View groups and their details** permission.
  * To read individual users, you must assign a role with the **Identity and Access Management > View roles, resources, and admin assignments** permission. You will need to [create a custom admin role](https://help.okta.com/oie/en-us/content/topics/security/custom-admin-role/custom-admin-roles.htm) with this permission.
  * If you plan to create a custom admin role, you may also wish to [create a resource set](https://help.okta.com/en-us/content/topics/security/custom-admin-role/create-resource-set.htm) to use with it's role assignment.
14. Click **Save Changes**.
15. Now you are ready to create your Okta integration in Synqly. The correct provider configuration structure is shown below.


## Configuring the Integration

| Integration Parameters | Description |
|  --- | --- |
| Client ID | The **Client ID** you noted earlier. |
| Client Secret | The **Private Key** you noted earlier. |
| Base URL | The **Okta Domain** you noted earlier. |