Configure Okta OIDC sign-in

Text size

Configure Okta OIDC sign-in

This guide walks you through creating an OpenID Connect (OIDC) app integration in Okta so your users can sign in to StackGen with Okta. When you finish, you send StackGen Support three values: Client ID, Client Secret, and Issuer URL.

Most organizations need only sign-in (SSO). For SSO, use your Okta org authorization server, which is built into every Okta org and needs no extra setup. A custom authorization server is rarely needed; see Optional: Use a custom authorization server.

Callback URL (sign-in redirect URI):

The callback URL has the following form:

https://<stackgen-host>/auth/callback

StackGen Support confirms the exact callback URL for your organization. It depends on whether your organization uses a dedicated or a shared StackGen instance. Ask Support for it before you start, and enter it exactly as Support provides it. Do not build the hostname from your organization or tenant name.

Before you begin

• An Okta admin account that can create app integrations and assign users to them (for example, Super Administrator or Application Administrator).
• The exact callback URL from StackGen Support.

Steps to configure Okta OIDC sign-in

Create the app integration

1. Sign in to the Okta Admin Console.

2. Go to Applications > Applications. Newer Admin Consoles label this menu Applications and Resources > Applications.

3. Click Create App Integration. If Okta asks you to choose an experience, select Classic experience.

4. For Sign-in method, select OIDC - OpenID Connect.

5. For Application type, select Web Application, then click Next.

   note

   Select Web Application. Do not select Single-Page Application or Native Application, and do not create a SAML 2.0 integration. StackGen signs users in from the server side and authenticates to Okta with a client secret.

Configure general settings

On the New Web App Integration page:

1. App integration name: Enter a descriptive name (for example, StackGen).

2. Grant type: Keep Authorization Code selected. This integration does not need Refresh Token, Implicit (hybrid), Client credentials, or Device Authorization, so leave them cleared.

3. Sign-in redirect URIs: Remove any sample value and enter the exact callback URL from StackGen Support.

   Okta matches this value exactly. Do not add a trailing slash, and do not enable Allow wildcard in sign-in redirect URI.

4. Sign-out redirect URIs: Remove any sample value and leave the field empty.

5. Assignments: Choose who can use the app:

   • Limit access to selected groups, then add the Okta groups whose members should sign in to StackGen (recommended).
   • Allow everyone in your organization to access, if every user in your Okta org should be able to sign in.

6. Click Save.

Copy the Client ID

After you save, Okta opens the app integration's General tab.

• In the Client Credentials section, copy the Client ID. This is your OIDC Client ID.

Copy the Client Secret

1. On the General tab, confirm that Client authentication is set to Client secret.

2. In the Client Secrets section, copy the secret value. If no secret is shown, click Generate new secret.

   warning

   • Treat the Client Secret like a password. Do not paste it into email, chat, support tickets, or screenshots.
   • Store it in your organization's secret manager until you hand it off to StackGen Support.
   • If the secret is exposed, generate a new secret, send the new value to StackGen Support, and then deactivate the old secret.

Find the Issuer URL

For SSO, StackGen uses your Okta org authorization server. Its Issuer URL is your Okta org URL:

https://<your-okta-domain>

Use your Okta org domain (for example, example.okta.com, or your custom Okta domain if you use one), not the admin domain that contains -admin. The Issuer URL is not the token endpoint or the authorize endpoint, so do not send a URL that ends in /v1/token or /v1/authorize.

To confirm the Issuer URL:

1. Open the org authorization server's OpenID configuration in a browser:

   https://<your-okta-domain>/.well-known/openid-configuration

2. Copy the issuer value from the response exactly as shown. StackGen rejects sign-in if the configured issuer differs from this value, including a trailing slash.

note

The org authorization server is not the same as the custom authorization server named default, whose issuer is https://<your-okta-domain>/oauth2/default. For standard SSO, send the org issuer, which has no /oauth2/ path. Use a /oauth2/... issuer only if StackGen Support has agreed that you need the optional custom authorization server path.

Scopes

This integration requests the following standard OIDC scopes:

Scope	Purpose
openid	Required for OIDC sign-in.
profile	User's name.
email	User's email address, used to identify the user in StackGen.

These scopes exist by default in Okta. You do not need to create custom scopes. Make sure every user who signs in to StackGen has an email address in their Okta profile.

Assign users and groups

Only users assigned to the app integration can sign in to StackGen. To change assignments after you create the app:

1. Open the app integration and go to the Assignments tab.
2. Click Assign > Assign to Groups or Assign to People.
3. Select the groups or users, click Assign, and then click Done.

Send the values to StackGen Support

Send the following three values to your StackGen Support representative to complete the configuration:

Value	Label in Okta	Location
Client ID	Client ID	App integration > General > Client Credentials
Client Secret	Secret	App integration > General > Client Secrets
Issuer URL	issuer	https://<your-okta-domain>/.well-known/openid-configuration (the org authorization server issuer, https://<your-okta-domain>)

Send the Client ID and Issuer URL in your support request. Share the Client Secret only through a secure channel that StackGen Support confirms with you, such as a one-time secret link or your secret manager's sharing feature. Contact support@stackgen.com to start.

Test sign-in

After StackGen Support confirms that Okta sign-in is enabled, they also provide the exact sign-in URL for your organization. Then:

1. Open that sign-in URL in a private browser window.
2. Select the Okta sign-in option.
3. Sign in with an Okta user who is assigned to the app integration.
4. Confirm that StackGen opens and shows your name and email address.

Also test with a user who is not assigned to the app. Okta should block that user.

Optional: Use a custom authorization server

Skip this section unless StackGen Support has asked you to use a custom authorization server.

A custom authorization server is needed only if your organization has a security requirement to also protect API calls with Okta authentication. Most organizations do not need it. Before you set one up, contact StackGen Support to discuss your API protection requirements. Using a custom authorization server issuer for sign-in does not, by itself, make StackGen accept Okta access tokens for API calls.

Custom authorization server requirements

• The Okta API Access Management feature. Custom authorization servers require it, and it is an optional add-on for production Okta orgs. If your org does not have it, contact your Okta account team.
• An Okta admin account that can edit authorization servers and their access policies (for example, Super Administrator).
• The app integration from Create the app integration.

Find the custom authorization server Issuer URL

A custom authorization server's issuer has the following form:

https://<your-okta-domain>/oauth2/<authorization-server-id>

Okta orgs that have API Access Management include a preconfigured custom authorization server named default. Its issuer is https://<your-okta-domain>/oauth2/default. Despite its name, this is a custom authorization server, not the org authorization server.

To find and confirm the Issuer URL:

1. Go to Security > API > Authorization Servers.

2. Select the custom authorization server agreed with StackGen Support, and note its Issuer URI and ID.

3. Open the server's OpenID configuration in a browser:

   https://<your-okta-domain>/oauth2/<authorization-server-id>/.well-known/openid-configuration

4. Copy the issuer value from the response exactly as shown, and send it to StackGen Support as the Issuer URL instead of the org issuer.

Allow StackGen in the access policy

A custom authorization server only issues tokens to apps that match one of its access policies. To allow StackGen:

1. Go to Security > API > Authorization Servers and select the custom authorization server from the previous section.
2. Open the Access Policies tab.
3. Use an existing policy that applies to All clients, or click Add Policy, enter a name, and under Assign to, select The following clients and add your StackGen app integration. Click Create Policy.
4. In the policy, click Add Rule (or edit an existing rule) and confirm:
   • Grant type is includes Authorization Code.
   • User is includes the users or groups assigned to the StackGen app.
   • Scopes requested allows openid, profile, and email.
5. Click Create Rule or Update Rule.

Troubleshooting

Symptom	Likely cause	Fix
Okta shows The 'redirect_uri' parameter must be a Login redirect URI in the client app settings	The sign-in redirect URI does not match exactly.	Set Sign-in redirect URIs to the exact callback URL from StackGen Support, with no trailing slash.
Okta shows User is not assigned to the client application	The user is not assigned to the app integration.	Assign the user or one of their groups on the Assignments tab.
Okta shows Policy evaluation failed for this request (custom authorization server only)	No access policy rule on the custom authorization server matches the app, user, grant type, or scopes. The org authorization server does not use these access policies.	Review Allow StackGen in the access policy.
Sign-in returns to StackGen with an error after Okta authentication	The Issuer URL, Client ID, or Client Secret that StackGen has does not match Okta. A common cause is sending a /oauth2/default issuer for standard SSO instead of the org issuer, or the reverse. A rotated or deactivated secret also causes this.	Confirm the issuer value in the OpenID configuration of the authorization server you use, then send the current values to StackGen Support.
User signs in but their email is missing or wrong	The user's Okta profile has no email, or (custom authorization server only) the access policy blocks the email scope.	Add an email to the Okta profile. If you use a custom authorization server, allow the email scope in its access policy.

If the issue persists, contact support@stackgen.com with the time of the failed attempt and the error text. Do not include the Client Secret.

Related resources

• Okta: Create OIDC app integrations
• Okta: Authorization servers
• Okta: Configure an access policy
• Configure Your Microsoft Entra ID (Azure AD) OAuth 2.0