Okta

Xokepoint reads users and groups from Okta with an API Services app of your org. Okta accepts only a signed key for these apps, never a client secret: you generate the key in Okta and paste it once in the form. People who log in from a coding harness go through a second app, an OIDC Web app, because an API Services app does not sign people in.

ConnectionCopy Anchor Link

• Connection name and Enable connection, as in other connections.
• Okta org URL: the address of your org, such as https://acme.okta.com, or your custom domain. Not the Admin Console address: remove -admin from it. Find your Okta domain

Okta API Services appCopy Anchor Link

The form guides you through four steps, each with a link to the Okta guide:

1. Create an API Services app: in the Okta Admin Console, Applications, Applications, Create App Integration, API Services. Copy its Client ID. Okta guide: create a service app
2. Generate a key: in the app, General tab, Client Credentials, Edit, then Public key / Private key. Under Save keys in Okta, select Add key and Generate new key. Copy the private key in JSON format at once, because Okta shows it only once. Keep DPoP required: each Okta token is then bound to a key that only Xokepoint holds. Okta guide: generate the key
3. Grant the scopes okta.users.read and okta.groups.read in the Okta API Scopes tab. Only a Super Administrator can grant them. Both are read only. Okta guide: grant scopes
4. Assign an admin role: Admin roles tab, Edit assignments, Read-only Administrator. Okta requires a role before the scopes work. Okta guide: assign admin roles

A person is identified by the Okta user ID, the same value in the harness login, in the tokens of your services and in the Okta directory. A new login name or e-mail address does not change it.

Deactivated people are not listed. The Everyone group of Okta is not listed either, so an agent can not be opened to the whole org by mistake. Groups that Okta imports from Active Directory or LDAP are listed with the others.

Check connectionCopy Anchor Link

Check connection reads the metadata and signing keys of the org, gets an Okta token with the private key and DPoP, reads one user, reads the groups and reads the groups of that user. Each message points to the step that fixes it:

Request authenticationCopy Anchor Link

Only needed when a service of yours exchanges an Okta access token of a user for an agent token. Okta does not let other parties validate the access tokens of the org authorization server, so this needs a custom authorization server, part of Okta API Access Management. Okta guide: custom authorization server

• Accept tokens from your services: off by default. Harness login and the directory work without it.
• Custom authorization server issuer: the Issuer shown in Security, API, Authorization Servers. It must belong to the same org, <org URL>/oauth2/<ID>, for example https://acme.okta.com/oauth2/default.
• Accepted audiences: the Audience of that server, api://default by default. Add audience adds another one.

The access policy of the server must allow the service of yours that asks for the token. The token must come from a person of the org: a token with no user, such as a client credentials token, is refused.

Harness loginCopy Anchor Link

People log in from a coding harness with their Okta account (Harness login). The login goes through an OIDC Web Application, not the API Services app:

1. In the Okta Admin Console, Applications, Create App Integration, OIDC - OpenID Connect, Web Application, with the Authorization Code grant and client secret authentication. Okta guide: create an OIDC app
2. Paste the Redirect URI of the form in Sign-in redirect URIs.
3. In Assignments, assign the groups of the people who may log in. Okta refuses everyone else before Xokepoint sees the login.
4. Copy its Client ID and Client secret into Login client ID and Login client secret.

At each login, Xokepoint reads the groups of the person with okta.groups.read of the API Services app. Every group except Everyone can be chosen in an agent.

Changing the orgCopy Anchor Link

If you change the org URL of a saved connection, the people associated before belong to the previous org and lose access. Xokepoint does not block the change.