Security > Authentication

Okta

Configure 3forge Enterprise to authenticate logins to the Web through an Okta identity provider, using the Okta plugin.

Prerequisites

• An application registered in Okta: It must use the authorization code flow, and its sign-in redirect URI must match oauth.redirect.uri exactly. Its client ID and client secret are needed in the steps below.
• The Okta plugin bundle: amiokta.tar.gz, delivered by 3forge. See Installing Plugins for where bundles go and which files are accepted.
• No other SSO plugin: Only one sso.plugin.class can be active, so the Okta plugin and the generic OAuth plugin cannot both be used. The Okta plugin is a separate plugin with its own id and class, and it reads a smaller set of properties.

Steps

1. Copy amiokta.tar.gz into the installation's plugins/ directory without extracting it.

2. Add the Okta connection details to config/local.properties:

   # Load the Okta plugin as the SSO plugin
   sso.plugin.class=com.f1.amioktaauth.AmiOktaOauthPlugin
   
   # The Okta domain, and the application registered in Okta
   oauth.server.domain=https://your-org.okta.com
   oauth.client.id=your-client-id
   oauth.client.secret=your-client-secret
   
   # Where Okta sends the browser back. The path after the host is where 3forge Enterprise expects the response
   oauth.redirect.uri=https://your-ami-host:33333/oauthRedirectUrl
   
   # The claim that becomes the user name
   oauth.username.field=email
   

3. Restart AmiCore.

4. Open the Web's address in a browser. The login redirects to Okta.

Result

After a successful sign-in, Okta redirects the browser back to the Web, already signed in as the user named by oauth.username.field.

To confirm the plugin loaded, run ami_web.showPlugins() in the f1 console. The SSO manager lists the plugin OKTA with the class com.f1.amioktaauth.AmiOktaOauthPlugin.

Endpoints

The endpoints default to Okta's default authorization server, /oauth2/default/v1/authorize and /oauth2/default/v1/token. To use a custom authorization server, set both properties:

oauth.authorization.endpoint=/oauth2/your-server-id/v1/authorize
oauth.token.endpoint=/oauth2/your-server-id/v1/token

Start every endpoint with /. The plugin joins the domain and the endpoint with a further / when it signs a user in, so that address contains a double slash. It uses the domain and the endpoint as written when it renews a token, so an endpoint without a leading slash breaks renewal.

Scope

The default scope is openid profile email offline_access. The offline_access scope requests a refresh token, which the session uses to renew. Set oauth.scope to change the scopes requested.

Mapping Okta claims to roles

Set a role property to the claim that carries it, then a values property listing the values that mean yes:

oauth.ami.isadmin.field=groups
oauth.ami.isadmin.values=ami-admins
oauth.ami.isdev.field=groups
oauth.ami.isdev.values=ami-devs

Set the field and values properties together. A field without its values property fails the sign-in with an error.

Claim names can be nested with a dot. Claims from the ID token are also added to the user's attributes as amiscript.variable.<claim>, for example amiscript.variable.email.

Session renewal

An open session renews its access token when the token expires, using the refresh token, and the session ends if the renewal fails.

Other properties

• oauth.code.challenge.method: Leave it unset. It defaults to S256, but the plugin also reads the same key as the digest algorithm name, so setting it, even to S256, breaks the code challenge.
• oauth.dynamic.redirect: When true, the redirect URI is built from the address the browser used to reach the Web, keeping the path from oauth.redirect.uri. It defaults to false.
• oauth.debug: When true, the log records the authorization exchange in detail, including the token request's Authorization header, which encodes the client secret, and the refresh token. It defaults to false. Turn it off after setup.

What this plugin does not support

• No sign-out at Okta: The plugin has no logout handling, so signing out of 3forge Enterprise does not call Okta's logout endpoint.
• Fewer properties than the OAuth plugin: It does not read oauth.logout.*, oauth.refresh.*, oauth.ami.roles.*, oauth.validate.certs, or oauth.session.check.period.seconds, so setting them has no effect.
• Certificates are always validated: Okta's TLS certificate is validated on token requests, and there is no option to turn that off.
• No REST or WebSocket login: This is a browser-redirect flow, so it authenticates the Web only. See Authentication if REST or WebSocket clients need authenticating too.