Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Or auth using a public/private keypair (OAuth 2.0 client credentials with `priva
```
BATON_AUTH_METHOD=private-key-group \
BATON_OKTA_CLIENT_ID=appClientID \
BATON_OKTA_PRIVATE_KEY='auth.key' \
BATON_OKTA_PRIVATE_KEY="$(cat auth.key)" \
BATON_OKTA_PRIVATE_KEY_ID=appKID \
BATON_DOMAIN=domain-1234.okta.com baton-okta
baton resources
Expand All @@ -37,7 +37,8 @@ baton resources
Notes for OAuth setup:

- `BATON_AUTH_METHOD=private-key-group` is required when authenticating via OAuth — without it the CLI defaults to the API Token field group and refuses to start with `field api-token of type string is marked as required but it has a zero-value`.
- The private key must be a PEM-encoded **RSA** key. Both **PKCS#1** (`-----BEGIN RSA PRIVATE KEY-----`) and **PKCS#8** (`-----BEGIN PRIVATE KEY-----`, what `openssl genrsa` produces by default) are accepted, so no conversion step is needed. Elliptic-curve keys are rejected — Okta's DPoP implementation requires RSA.
- `BATON_OKTA_PRIVATE_KEY` takes the key **contents**, not a path to the key file — hence `"$(cat auth.key)"` above. The private key must be a PEM-encoded **RSA** key. Both **PKCS#1** (`-----BEGIN RSA PRIVATE KEY-----`) and **PKCS#8** (`-----BEGIN PRIVATE KEY-----`, what `openssl genrsa` produces by default) are accepted, so converting between them is not necessary. Elliptic-curve keys are rejected — Okta's DPoP implementation requires RSA.
- Configuring through the C1 connector form instead of the CLI? The **Okta Private Key** field holds a single line, so the key goes in with each line break written as a literal `\n`; a pasted multi-line PEM fails with `no PEM block found`. See [`docs/connector.mdx`](docs/connector.mdx). The multi-line PEM above applies to the CLI and environment-variable paths only.
- **DPoP is supported** and needs no Okta-side change: leave the app's **Proof of Possession** setting at Okta's default. Earlier revisions of this file and of `docs/connector.mdx` told you to disable DPoP; that instruction described the pre-DPoP connector and was removed in CXH-2198.
- The API Services app **must be assigned an admin role** on its **Admin Roles** tab. Granting OAuth scopes is not sufficient. Without a role, most endpoints return `403`, but `GET /api/v1/users` returns `200` with an empty list — so the sync succeeds and finds zero accounts.
- See [`docs/connector.mdx`](docs/connector.mdx) for the complete Okta-side setup and [`docs/docs-info.md`](docs/docs-info.md) for the internal detail on key handling, DPoP, and scopes.
Expand Down
20 changes: 18 additions & 2 deletions docs/connector.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -370,7 +370,23 @@ If a sync finishes cleanly with no accounts, check the app's **Admin Roles** tab
You'll need the **Client ID**, **Private Key**, and **Private Key ID** when configuring the connector.

<Note>
**Private key format.** The connector accepts a PEM-encoded **RSA** private key in either format, so no conversion is needed:
**Private key format.** The **Okta Private Key** field in the C1 connector form holds a single line. Pasting a multi-line PEM into it replaces the line breaks with spaces, and the connector rejects the result with `oktaauth: parse private key: no PEM block found`.

Enter the key on one line, writing each line break as a literal `\n`:

```
-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE KEY-----
```

Convert a PEM file to that form with:

```bash
awk 'BEGIN{ORS="\\n"} {print}' key.pem | sed 's/\\n$//'
```

Running the connector self-hosted, pass the key unchanged: `BATON_OKTA_PRIVATE_KEY` and `--okta-private-key` accept the multi-line PEM as it is. The single-line form is a property of the connector form, not of the connector.

Either PEM encoding works, and converting between them is not necessary:

- **PKCS#1** — header line `-----BEGIN RSA PRIVATE KEY-----`
- **PKCS#8** — header line `-----BEGIN PRIVATE KEY-----` (what OpenSSL 3.0+ produces by default)
Expand Down Expand Up @@ -428,7 +444,7 @@ Enter your Okta domain hostname, e.g. `<YOUR DOMAIN>.okta.com`, into the **Okta
Enter your credentials:

- For **API Token**: paste your API token into the **API token** field.
- For **OAuth 2.0 Private Key**: enter your **Okta Client ID**, **Okta Private Key ID**, and paste the **Okta Private Key** (PEM-encoded).
- For **OAuth 2.0 Private Key**: enter your **Okta Client ID** and **Okta Private Key ID**, then enter your RSA private key into **Okta Private Key** on a single line, with each line break written as `\n`. See **Private key format** above.
</Step>
<Step>
**Optional.** If desired, click the checkbox to **Sync custom roles**.
Expand Down
Loading