Okta Onboarding Runbook

What this achieves

Learners open a training address, sign in with the Okta credentials they already have, and go straight into their course. We never see or store a password, and we hold no client secret — the connection is a public OpenID Connect client using PKCE.

You create and configure the app integration below.
You send us two values: your issuer URL and the client ID.
We connect it and run an automated check against your org.

Create the app integration

Admin → Applications → Applications → Create App Integration

Choose OIDC – OpenID Connect, then Single-Page Application. The application type matters more than it looks — see the note at the bottom.

Sign-in method is OIDC, application type is Single-Page Application Not Web Application. A Web app is issued a client secret and is treated as confidential, which is a different flow from the one we use.
Grant type: Authorization Code is ticked PKCE is required automatically for a SPA. Leave Implicit unticked.
No client secret was generated If one was, the application type is wrong. Recreate it as a SPA rather than trying to remove the secret.

Add the sign-in redirect URIs we send you

The app → General → Sign-in redirect URIs

We will send an exact list with this document — one per training address. Okta matches these character for character, so paste them rather than retyping.

Shape of the values — use the list we send, not these

https://<training-address>/auth/callback

Every redirect URI from our list is present, exactly as written No wildcards, no trailing slash after /auth/callback, always https.
They went into “Sign-in redirect URIs”, not “Sign-out redirect URIs” Two fields on the same screen. Filling only the second is the most common half-completion, and it fails in a way that looks like our problem rather than a missing setting.

Assign people to the application

The app → Assignments

An Okta app that nobody is assigned to is fully configured and completely unusable. Every automated check passes and every real person is refused at sign-in.

The right groups or people are assigned Whoever should be able to reach the training. This is the single most common reason a correct-looking Okta setup refuses everyone.

Confirm the scopes and the name claims

Security → API → Authorization Servers

We request openid, email and profile. The profile scope is what carries the learner's name, and the name is what a completion certificate prints — without it a certificate shows an email address.

openid, email and profile are all available on the authorization server
Users have a first and last name in the directory Okta puts these into given_name and family_name automatically, but only where the profile actually holds them.

Decide which authorization server you are using

Security → API → Authorization Servers

This decides the issuer URL you send us, and it is the value most often sent wrong. Okta has two kinds and they produce different issuers:

Org authorization server

https://<your-org>.okta.com

A custom authorization server, including the one named “default”

https://<your-org>.okta.com/oauth2/<server-id>

You have copied the Issuer URI shown in the console, not assembled one The console displays the exact value. A hand-built issuer is the difference between working and a discovery failure that looks like an outage at our end.
The app integration is scoped to that same authorization server If you use a custom server, its access policy must include this application, or every sign-in is refused.

Sign-out URLs — usually nothing to do

The app → General → Sign-out redirect URIs

Signing out of training clears the training session only and leaves your Okta session alone, so no sign-out URL is required. Tell us if you would rather signing out of training also ended the Okta session — be aware that would sign them out of anything else using it — and we will send exact values to register.

Point your DNS at us

Your DNS provider · one CNAME per training address

Only needed if the training runs on your own domain. If we have given you an address ending in .learn.skyline-ats.dev, that is already live — skip this step.

One CNAME per address, all to the same target

academy.example.com CNAME connect.skyline-ats.dev

You have told us the exact addresses before making the change We build the redirect URIs in step 2 from them, so this has to come first.
CNAME changed to connect.skyline-ats.dev No TXT records and no verification step — pointing the CNAME at us is itself the proof of ownership. The certificate is issued automatically, which takes a minute or two, so pick a quiet moment.

Value	Where to find it	Example
Issuer URI	Security → API → Authorization Servers, the Issuer URI column	https://acme.okta.com/oauth2/default
Client ID	The app integration → General	0oa1b2c3d4EfGhIjK5d7

Why this usually takes a second attempt

These share a shape: the configuration looks complete, every obvious check passes, and something still fails when a real person tries to sign in.

Nobody is assigned to the application

The commonest Okta failure by a distance. Everything validates — the issuer resolves, the redirect URI is accepted, the scopes exist — and every actual person is refused, because an Okta app grants nothing until people or groups are assigned to it.

Created as a Web Application instead of a SPA

A Web app is issued a client secret and treated as confidential. We are a public client using PKCE and hold no secret, so sign-in fails at the token exchange — after the person has already typed their password, which makes it look like our fault.

Recreate it as a Single-Page Application. The secret cannot be removed from a Web app.

The wrong issuer, or an app outside the authorization server's policy

https://acme.okta.com and https://acme.okta.com/oauth2/default are different issuers with different signing keys. Send the one the console shows.

And if you use a custom authorization server, its access policy has to include this application — otherwise every sign-in is refused with a message that reads like a scope problem.

Sign-in and sign-out redirect URIs are different fields

They sit next to each other and accept identical-looking values. Filling only the sign-out field leaves sign-in failing with a redirect mismatch while the console looks correctly completed.

Connecting Okta to a training portal