Define app behaviors
App behaviors define the actions to perform in response to an event.
Add a behavior to an app
- Go to Access Gateway Admin UI console.
- Open the app from either the Topology or Applications tab.
- In the Settings pane, expand Behaviors.
- Choose one of the following custom behaviors:
Login
Define login endpoints that help create the user session.
| Field | Description |
|---|---|
| Login | Select this option from the dropdown menu. |
| Login path | The path to the login endpoint URL. It can be relative or fully qualified, depending on what you use it for. It's executed after the user successfully signs in. The URL must be unique across the login, logout, and error behaviors. Access Gateway doesn't support using the same URL for multiple behaviors. The URL can't overlap with an existing defined policy. See Manage application policies. |
Login supports the following behaviors:
| Value | Behavior |
Login path |
|---|---|---|
| Don't define login behavior | Don't use a login behavior. | Not applicable. |
| Use Okta Access Gateway login page | Show the Auth Module login page. | Enter a valid relative path in the protected app. The Auth module must refer to a previously defined Auth Module. |
| Use Application login page | Use the associated unprotected path to an app-hosted login page. | Enter a valid relative path in the protected app. |
| Define a custom login URL | Access Gateway forwards the user to the Custom URL when they sign in. | Enter a valid relative path in the protected app. The Custom URL must contain a valid fully qualified URL. |
Logout
Define logout endpoints that help terminate user sessions.
Access Gateway uses the primary email address from the Okta org to create and identify the user session. For security reasons, don't use the same primary email address in multiple user accounts. Instead, use a unique primary email address for each user account. This prevents all user accounts with the same primary email address in their profile from having their session terminated if any one of those users signs out, or if their session is terminated by Okta, such as when Universal Logout is enabled.
| Field | Description |
|---|---|
| Logout | Select this option from the dropdown menu. |
| Logout path | The path to the relative endpoint URL. Redirect users to this path when users log out. The URL must be unique across the login, logout, and error behaviors. Access Gateway doesn't support using the same URL for multiple behaviors. The URL can't overlap with an existing defined policy. See Manage application policies. |
| Single Logout |
|
|
Universal Logout |
Terminate the user's Access Gateway and app sessions when the user signs out. Users must sign back in to use Access Gateway or their apps. Universal Logout doesn't sign the user out of Okta. |
|
Global Token Revocation |
Terminate the user's Access Gateway and app sessions from Okta. Users must sign back in to use Access Gateway or their apps. The app must be accessible to Okta from the internet so that Okta can send the logout request. If the app is only accessible from your intranet, Okta can't send the request. See Configure Universal Logout for supported apps. Verify that the <your-org>-admin.okta.com URL is excluded from SSL decryption. This ensures that Access Gateway can access your Okta org. |
| Post Logout URL | This option appears when you select Define a custom logout URL. Enter the URL in the field. |
|
Value |
Behavior |
End page |
|---|---|---|
| Show Logout page | Reset Okta and Access Gateway sessions based on the value of Single Logout. | After a session cleanup, display the Access Gateway logout page to show that the logout was successful. |
|
Show Login page |
Reset Okta and Access Gateway sessions based on the value of Single logout. |
After a session cleanup, Access Gateway displays the Okta sign-in page when Single Logout is enabled. When it's disabled, Access Gateway redirects the user to the Access Gateway logout page. |
| Use Application Logout page | Terminate Okta and Access Gateway sessions based on the value of Single Logout. The value of Logout path must be a valid relative path in the protected app. |
After a session cleanup, Access Gateway displays the page specified by the Logout path field. Use this option if your app already has a logout page or if custom logic is required for actions taken after the end user logs out. For example, when you clear sessions in a third-party service or write to an external audit log. |
| Define a custom Logout URL | Terminate Okta and Access Gateway sessions based on the value of Single Logout. The value of the Logout path must be a fully qualified URL. |
This is the URL that end users are directed to after logging out. By default, this is the Post Login value. When users log out, redirect them to the specified Post Logout URL. The Access Gateway and Okta sessions are terminated according to the Single Logout behavior that you selected before redirecting users to this URL. |
| Don't define any logout behavior | Neither the Access Gateway app session, nor the Okta session, are terminated when the user signs out. | Not applicable. |
Logout state transitions:
Post Logout URL
This is the default URL that end users are directed to after they sign out. This defaults to the Post Login value.
Enable this field and enter an appropriate URL. Redirect the user to a central logout page hosted by the customer, to the home page of your company, or something similar.
Error
This behavior allows you to define error endpoints to call when errors occur. Redirect the user to a central logout page hosted by the customer, to the home page of your company, or something similar.
| Field | Description |
|---|---|
| Error | Select this option from the dropdown menu. |
| Error path | This is the path to the error endpoint URL. It can be relative or fully qualified, depending on what you use it for. The URL must be unique across the login, logout, and error behaviors. Access Gateway doesn't support using the same URL for multiple behaviors. The URL can't overlap with an existing defined policy. See Manage application policies. |
| Dropdown value | Behavior |
Error Path |
|---|---|---|
| Use Okta Access Gateway error page | Define an error path for this app. By default, it shows the generic Access Gateway error page. | Not applicable. |
| Use Application error page | Display an app-hosted error page. The Error path must be a valid path in your app. | A valid relative path must exist in the protected app. |
| Define a custom error URL | This option redirects the end user to a custom error path URL path. | In addition to the Error path, enter a fully qualified path that is used as an error handler. This option must contain a valid, fully qualified URL. |
| Don't define any Error Behavior | Access Gateway doesn't perform any error behavior. | Not applicable. |
Error state transitions
No Session/Session Expired
Define the end-user experience when Access Gateway has no session or the current session expires for this app.
| Dropdown list values | |
|---|---|
| Redirect to IDP | This option redirects the end user to Okta to reauthenticate. If their Okta session is still active, the end user is silently redirected back to the app with a refreshed app session. |
| Force reauthentication at IDP | This option redirects the end user to Okta to reauthenticate, even if their Okta session is active. |
| Show default no session page | Display the Access Gateway "no session" page. |
| Redirect to custom URL | Redirect the end user to a custom URL. |
Session state transitions
Policy Denied
Define the end-user experience when Access Gateway denies access to a resource if the user doesn't meet the requirements of a policy.
| Dropdown list values | |
|---|---|
| Show default policy failure page | Display the default Access Gateway policy failure page. |
| Return 403 status code | Return a blank page with the HTTP 403 status code. |
| Redirect to custom URL | Redirect the end user to a custom URL when the user doesn't fulfill the requirements of a policy. |
Session Integrity Failed
Define the end-user experience when Access Gateway detects a session integrity failure. This is common when end users change networks while maintaining an active app session. Access Gateway fingerprints the remote-IP and denies access.
| Dropdown list values | |
|---|---|
| Show default Security warning page | Display the default Access Gateway security warning page. |
| Return 405 status code | Return a blank page with the 405 status code. |
| Redirect to IDP | Redirect the end user to a custom URL when a session integrity error is detected. |
| Force reauthentication at IDP | Force the end user to reauthenticate. The user is returned to the app. |
| Do not enforce | Don't enforce session integrity. |
Certificate validation behavior
Certificate validation behavior is an Early Access feature. To enable it, contact Okta Support.
This behavior allows you to define the fields and behaviors for validating requests using certificate chains.
By specifying incoming and outgoing certificate header fields, and a certificate behavior, you're implicitly defining that the associated app uses Client Certificate chains for additional authentication.
| Field | Description |
|---|---|
| Client Certificate Validation Failed | Select this option from the dropdown menu. |
| Custom URL/URI | This is the path to a custom endpoint. It can be relative or fully qualified, depending on what you use it for. It's executed when the user is redirected to a custom URL. |
| Incoming Header Field Name | This is the header attribute that contains the PEM format certificate. The value in this attribute is compared to certificate chain certificates. |
| Outgoing Header Field Name | The header attribute is used to hold the certificate after validation. The value of the incoming header field is copied to the value of this header field on redirect to the requested back-end resource. |
Client Certificate Validation Failed supports the following behaviors:
| Value | Behavior |
|---|---|
| Disable certificate checking | Disable certificate checking for this app. |
| Redirect the end user to a custom URL | When there's a certificate validation failure, redirect the user to the custom URL. |
| Return a blank page with an HTTP 405 status code | When there's a certificate validation failure, redirect the user to a blank (empty) page and return the HTTP 405 status to the caller. |
| Present a default error page with an "Invalid certificate message" | When there's a certificate validation failure, display the Invalid certificate error page to the end user. |
App Maintenance
Define the end-user experience when the app is in maintenance mode.
| Dropdown list values | |
|---|---|
| Default Application Maintenance page | Display the default Okta Access Gateway app maintenance page. |
| Redirect to custom URL | Redirect the end user to a custom URL when Access Gateway is in maintenance mode. |