# Import from Okta (https://docs.idra.zone/docs/okta-import)

Bring people, groups and apps from an Okta org into IdRa, with a dry run before anything is written.

**Beta: tested against a fake only**

  This importer has only been tested against a simulated Okta API built from Okta's public
  documentation. It has never run against a live Okta org. Start with a preview, read the report and
  check the result before relying on it.

**Directory → People → Import from Okta** reads an Okta org through the Okta Management API, shows what would happen to every item, and only writes after you start the import.

## What you need

- An IdRa administrator role that can create people and write groups and apps: **Super Administrator** or **Organization Administrator**.
- Your Okta org URL, like `https://acme.okta.com`. IdRa accepts `okta.com`, `oktapreview.com`, `okta-emea.com`, `okta-gov.com` and `okta.mil` hosts only, so custom domains are refused: use the org's Okta address.
- An Okta API token (SSWS), created in Okta under **Security → API → Tokens** while signed in as a **Read-only Administrator**. A token acts with its creator's permissions, and IdRa only makes `GET` calls, to:
  - `/api/v1/users`
  - `/api/v1/groups` and `/api/v1/groups/{id}/users`
  - `/api/v1/apps` and `/api/v1/apps/{id}/groups`

The token stays in your browser tab for the preview and the import, and in server memory during each of those two requests. IdRa never stores it, logs it or returns it. Revoke it in Okta when you finish.

## Steps

1. Open **Directory → People** and select **Import from Okta**.
2. Enter the org URL and token, then select **Preview import**. This is the dry run: it writes nothing.
3. Read the report. Every user, group and app is marked **Create**, **Skip** or **Unsupported**, with a reason or what you must redo.
4. Select **Start import**. If Okta or IdRa changed since the preview, IdRa asks you to preview again, so what runs is what you reviewed.
5. Follow the progress. Download the list of what wasn't imported if you need it.
6. Run the import again whenever you like. Items already in IdRa are skipped, so items that failed get another try and nothing is duplicated.
7. Activate people when you're ready: **Activate** on the import page emails everyone imported who is still staged. See [activating people](#activating-people).

## What is migrated

| Okta | IdRa | Matched on |
| --- | --- | --- |
| Users, except suspended and deactivated ones | People in the **Staged** state, with first name, last name and any attribute also defined in your Profile Editor | Email, ignoring case |
| Okta-managed groups | Groups, with the same members | Name, ignoring case |
| An app's group assignments, for apps and groups this import creates | App assignments | Created together |
| Active custom SAML 2.0 apps | SAML apps | Entity ID |
| Active OIDC apps (web, single-page, native, service) | OIDC apps | Redirect URI, or name when an app has none |
| Active bookmark apps | Bookmark apps | URL |

An existing person is never changed, apart from joining the Okta groups they're missing.

**Joining an existing group**

  If an IdRa group already has the same name as an Okta group, the Okta members join it and get
  whatever it gives. The preview lists each of these groups with who joins and which apps, servers,
  secrets and policies it involves, and you must accept that before starting. Rename the IdRa group
  first if they aren't the same group. People already in IdRa get the access straight away.

## What you must redo

- **Passwords and MFA.** Okta doesn't export password hashes or factors. Imported people have no password and receive no email until you activate them, then they set a password and enroll again.
- **OIDC apps.** Each gets a new client ID. Okta doesn't export client secrets, so rotate the secret on the app's page in IdRa, then update the client ID and secret in the app.
- **SAML apps.** Install IdRa's metadata in the service provider.
- **App assignments.** Only a group this import creates keeps its Okta assignment, because it has the same members as in Okta. Assign these by hand; the report names the groups for each app: existing IdRa groups (their other members would gain the app), Everyone, and groups that weren't imported. Direct user assignments and per-assignment app attributes aren't read, so take them from Okta before you revoke the token.

## Activating people

**Activate** on the import page (it also appears on the first step, for later) sends an activation email to everyone the importer created who is still staged. It runs in the background and you can leave the page. Anyone already activated is left alone, so it's safe to run again, and someone whose email failed stays staged for the next try. It doesn't reach people made administrators since the import, or people whose import is older than your log retention: activate those from their own page.

## Not migrated

The report lists these as **Unsupported**, with the reason:

- Suspended and deactivated users, and users without a valid email or a first and last name.
- Okta's built-in Everyone group (IdRa has its own), and groups sourced from an app or a directory.
- Groups whose name matches an IdRa group managed elsewhere (SCIM, partners).
- Okta's own apps, inactive apps, and sign-on modes with no IdRa equivalent: password vaulting (`BROWSER_PLUGIN`, `SECURE_PASSWORD_STORE`), `AUTO_LOGIN`, `BASIC_AUTH`, `WS_FEDERATION` and `SAML_1_1`.
- SAML catalog integrations, because Okta doesn't expose their settings. Also SAML apps using single logout, signed requests, group filters or attribute expressions other than `user.<attribute>`.
- OIDC apps with wildcard redirect URIs.

These aren't read at all, and don't appear in the report:

- **Admin roles.** No imported person gets an IdRa admin role. Grant roles in **Security → Administrators**.
- Direct app assignments, policies, MFA factors, group rules, network zones, identity providers, API tokens, and profile attributes not defined in your Profile Editor.

## Limits

The read runs inside the preview and import requests, because the token isn't stored. A very large org could outlast a proxy's request limit; the read writes nothing, so running it again is safe. IdRa waits and retries when Okta answers `429`, following `X-Rate-Limit-Reset`, up to three times per call.