From 6f3015faa84e0e7a97dd09cc4a38d0f75a97c677 Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Fri, 20 Feb 2026 14:14:06 -0500 Subject: [PATCH 1/6] Add structure of doc and rough outline --- .../@okta/vuepress-site/docs/guides/index.md | 1 + .../docs/guides/oag-offline-mode/index.md | 9 + .../guides/oag-offline-mode/main/index.md | 220 ++++++++++++++++++ .../const/navbar.const.js | 9 + 4 files changed, 239 insertions(+) create mode 100644 packages/@okta/vuepress-site/docs/guides/oag-offline-mode/index.md create mode 100644 packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md diff --git a/packages/@okta/vuepress-site/docs/guides/index.md b/packages/@okta/vuepress-site/docs/guides/index.md index 18b49516a49..0b3fcf5611e 100644 --- a/packages/@okta/vuepress-site/docs/guides/index.md +++ b/packages/@okta/vuepress-site/docs/guides/index.md @@ -195,6 +195,7 @@ guides: - custom-passkeys - set-up-oauth-api - custom-smtp + - oag-offline-mode --- Learn how to accomplish a task with step-by-step instructions. diff --git a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/index.md b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/index.md new file mode 100644 index 00000000000..9af5a2d8bdc --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/index.md @@ -0,0 +1,9 @@ +--- +title: Configure offline mode for Access Gateway +meta: + - name: description + content: How to configure offline mode for Access Gateway. +layout: Guides +sections: + - main +--- diff --git a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md new file mode 100644 index 00000000000..50b7cf53555 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md @@ -0,0 +1,220 @@ +--- +title: Configure offline mode for Access Gateway +meta: + - name: description + content: How to configure offline mode for Access Gateway +layout: Guides +--- + +This guide explains how to configure offline mode for Access Gateway using Access Gateway APIs. Offline mode allows users to authenticate locally through Access Gateway and continue accessing protected on-premises applications, even when Access Gateway is unable to reach Okta. + +--- + +#### Learning outcomes + +Learn how to configure offline mode for Access Gateway using Access Gateway APIs. + +#### What you need + +An Okta org that's subscribed to Access Gateway + +--- + +## Overview + +This document outlines the API definitions required to support **Temporary Offline Access** (Disconnected Operations) for Okta Access Gateway (OAG). As defined in the Product Hub Document, OAG requires REST API endpoints to configure fallback IdP settings, manage offline sign-on policies, and handle extended offline mode triggers. +These endpoints extend the existing OAG Management APIs to support local authentication when the Okta service is unreachable. + +Temporary Offline Access enables users to authenticate locally on the Okta Access Gateway (OAG) and continue accessing protected on-premises applications, even when OAG is unable to reach Okta. This feature provides resiliency and business continuity for critical on-premises resources during internet outages or in disconnected environments, such as cruise ships, airplanes, or high-security facilities. + +**INTERNAL DOCUMENT OKTA CONFIDENTIAL** **Project:** OAG Offline Mode (Disconnected Operations) **Doc Type:** API Specification (Draft / RFC) **Based on Product Hub Document:** **Status:** In Design (Engineering Lead Input Required) + +## Set up Access Gateway for API access + +Set up Okta so that you can authenticate to Okta APIs and have the proper roles and scopes to manage labels: + +1. [Set up an app for OAuth 2.0 authentication](#set-up-an-app-for-oauth-2-0-authentication). +1. [Grant scopes required for labels](#scopes-required-for-labels). +1. [Assign roles to your API users](#assign-roles-to-your-api-users). +1. [Assign API users to a role and to your API access app](#assign-api-users-to-a-role-and-to-your-api-access-app). + +### Set up Access Gateway for API access + +Users can access OIG APIs by authenticating with an [OAuth 2.0 access token](https://developer.okta.com/docs/api/openapi/okta-management/guides/overview/#oauth-20-access-token). To obtain an OAuth 2.0 access token for API authentication, you need to have an app in Okta for API access: + +* If you don't have an app for API access, see [User-based API access setup](/docs/guides/set-up-oauth-api/main/#user-based-api-access-setup) to create an OIDC app. Grant the [scopes required for labels](#scopes-required-for-labels) to the OIDC app (in addition to any other scopes you may need). + +* If you already have an OIDC app for API access, ensure that your app is granted with the [scopes required for labels](#scopes-required-for-labels). + +* If you're using Okta Workflows, ensure that the **Okta Workflows OAuth** app is granted with the [scopes required for offline mode](#scopes-required-for-offline-mode). See [Authorization > Create a connection from the current Okta org](https://help.okta.com/okta_help.htm?type=wf&id=ext-okta-misc-authorization). + +### Scopes required for offline mode + +Your OAuth 2.0 access token must have the appropriate scopes for the [Labels API](https://developer.okta.com/docs/api/iga/openapi/governance.api/tag/Labels/) request. + +Ensure that the following scopes are granted to your app for API authentication: + +* `okta.governance.labels.manage` +* `okta.apps.read` +* `okta.groups.read` +* `okta.governance.entitlements.read` +* `okta.governance.collections.read` + +Assign the super admin (`SUPER_ADMIN`) role to your API users. + +### Configure offline mode for identity providers + +Configuration for enabling offline capabilities on specific Identity Providers (IdPs) associated with OAG. +**GET** /api/v1/idps/{idpId}/offline-config +Retrieves the current offline configuration for a specific IdP. +**PUT** /api/v1/idps/{idpId}/offline-config +Updates the offline access configuration. This endpoint facilitates the requirement that admins must explicitly configure the fallback local IdP. +**Request Body Schema:** + +``` +{ + "enabled": true, + "max_offline_duration_days": 30, + "fallback_mode": "automatic", + "sync_frequency_seconds": 3600 +} +``` + +* **enabled**: Toggles the capability for this IdP to switch to offline mode. +* **max_offline_duration_days**: Hard cap on offline duration (Note: Product hard limit is 1 year). +* **fallback_mode**: + * automatic: OAG dynamically detects connection loss and switches. + * manual: Requires admin intervention (Extended Mode). + * **Response:** 200 OK + +#### Request example + +```bash + +``` + +#### Response example + +```json + +``` + +### Configure offline sign-in policies + +As per the requirement, offline policies are **not** synced from Okta and must be explicitly configured on the OAG instance at the IdP level,. +**GET** /api/v1/idps/{idpId}/offline-policies +Fetches the list of offline sign-on policies. +**POST** /api/v1/idps/{idpId}/offline-policies +Creates a new offline policy rule. Validates that the authenticators specified are supported in offline mode (currently Password and Smart Card only,). +**Request Body Schema:** + +``` +{ + "name": "Emergency Access Policy", + "priority": 1, + "conditions": { + "user_groups": { + "include": ["Admins", "Emergency_Response_Team"] + } + }, + "requirements": { + "authenticators": [ + { + "type": "password", + "required": true + }, + { + "type": "smart_card", + "required": false + } + ] + } +} +``` + +* **constraints**: The API must reject fastpass or webauthn in this release, as they are Phase 2/3 goals. + + +#### Request example + +This example assigns two label values to two resources: + +```bash + +``` + +#### Response example + +```json + +``` + +### Monitor offline status and trigger extended offline mode + +Endpoints to monitor connectivity status and manually invoke "Extended Offline Mode" for scenarios like submarine deployments or intentional air-gapping,. + +**GET** /api/v1/system/offline-status +Returns the current connectivity state of the OAG appliance. +**Response Schema:** + +``` +{ + "connection_status": "disconnected", + "current_mode": "offline", + "offline_since": "2025-10-23T14:30:00Z", + "last_sync_timestamp": "2025-10-23T12:00:00Z", + "events_cached_count": 452 +} +``` + +**events_cached_count**: Monitoring for the system log events cached locally while disconnected. +**POST** /api/v1/system/offline-mode/extended +Triggers "Extended Offline Mode." This forces the system to remain offline regardless of connectivity until manually disabled. + +**Request Body:** + +``` +{ + "action": "enable", + "reason": "Planned Submarine Deployment" +} +``` + +#### Request example + +This example replaces the background color of `lblo3v6xlwdtEX2il1d1` (SOX) to purple. + +```bash + +``` + +#### Response example + +```json + +``` + +## Data models and limitations + + + +### Supported authenticators + +When configuring policies via the /offline-policies endpoint, the authenticator type must validate against: + +* PASSWORD: Validates against on-prem AD/LDAP hash. +* SMART\_CARD: PIV/CAC validation. +* *Future:* OKTA\_VERIFY (FastPass) \- **DISABLED in v1**. + +### User restrictions + +The API must enforce the following logic limitations: + +* **No App Creation:** POST /api/v1/apps requests must return 403 Forbidden or specific error E00\_OFFLINE\_MODE when current\_mode is "offline". +* **No User Onboarding:** Attempts to create new users via OAG during offline mode must be blocked unless specific local-only flows (Phase 2\) are enabled. + +## Security considerations + +* **Local Storage:** Cached credentials and logs must be encrypted at rest on the appliance. +* **Auth:** Access to these offline configuration APIs requires the standard OAG Admin Session Token. +* **Audit:** Changes to offline policies (e.g., weakening security by removing Smart Card requirements) must be logged locally and synced to Okta System Log immediately upon reconnection. diff --git a/packages/@okta/vuepress-theme-prose/const/navbar.const.js b/packages/@okta/vuepress-theme-prose/const/navbar.const.js index fbb8a88155d..4cd96e6cad1 100644 --- a/packages/@okta/vuepress-theme-prose/const/navbar.const.js +++ b/packages/@okta/vuepress-theme-prose/const/navbar.const.js @@ -895,6 +895,15 @@ export const guides = [ } ], }, + { + title: "Access Gateway", + subLinks: [ + { + title: "Configure offline mode", + guideName: "oag-offline-mode" + } + ] + }, { title: "Identity Governance", subLinks: [ From f1fd4eaf59bbe60384f9eea38155ed113685283e Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Mon, 23 Feb 2026 15:50:53 -0500 Subject: [PATCH 2/6] Improve on the first draft --- .../guides/oag-offline-mode/main/index.md | 306 ++++++++++-------- 1 file changed, 175 insertions(+), 131 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md index 50b7cf53555..26ab98e5e2d 100644 --- a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md @@ -6,13 +6,17 @@ meta: layout: Guides --- -This guide explains how to configure offline mode for Access Gateway using Access Gateway APIs. Offline mode allows users to authenticate locally through Access Gateway and continue accessing protected on-premises applications, even when Access Gateway is unable to reach Okta. + + +This guide explains how to configure Temporary Offline Access (offline mode) for Access Gateway using Access Gateway APIs. Offline mode allows users to authenticate locally through Access Gateway and continue accessing protected on-premises applications, even when Access Gateway is unable to reach Okta. + +> **Note:** The Access Gateway APIs that are used for offline mode configuration are in Early Access (EA). --- -#### Learning outcomes +#### Learning outcome -Learn how to configure offline mode for Access Gateway using Access Gateway APIs. +Learn how to configure Temporary Offline Access (offline mode) for Access Gateway using Access Gateway APIs. #### What you need @@ -22,199 +26,239 @@ An Okta org that's subscribed to Access Gateway ## Overview -This document outlines the API definitions required to support **Temporary Offline Access** (Disconnected Operations) for Okta Access Gateway (OAG). As defined in the Product Hub Document, OAG requires REST API endpoints to configure fallback IdP settings, manage offline sign-on policies, and handle extended offline mode triggers. -These endpoints extend the existing OAG Management APIs to support local authentication when the Okta service is unreachable. +Offline mode is a feature of Access Gateway that allows it to continue functioning with modified capabilities when the connection to the identity provider (IdP) is lost. It enables your users to authenticate locally through Access Gateway and continue accessing protected on-premises applications. -Temporary Offline Access enables users to authenticate locally on the Okta Access Gateway (OAG) and continue accessing protected on-premises applications, even when OAG is unable to reach Okta. This feature provides resiliency and business continuity for critical on-premises resources during internet outages or in disconnected environments, such as cruise ships, airplanes, or high-security facilities. +You can only configure offline mode for Access Gateway using Access Gateway APIs. This guide explains how to set up Access Gateway for API access and how to use Access Gateway APIs to configure offline mode. -**INTERNAL DOCUMENT OKTA CONFIDENTIAL** **Project:** OAG Offline Mode (Disconnected Operations) **Doc Type:** API Specification (Draft / RFC) **Based on Product Hub Document:** **Status:** In Design (Engineering Lead Input Required) - -## Set up Access Gateway for API access +## Set up Access Gateway APIs for offline mode configuration Set up Okta so that you can authenticate to Okta APIs and have the proper roles and scopes to manage labels: -1. [Set up an app for OAuth 2.0 authentication](#set-up-an-app-for-oauth-2-0-authentication). -1. [Grant scopes required for labels](#scopes-required-for-labels). -1. [Assign roles to your API users](#assign-roles-to-your-api-users). -1. [Assign API users to a role and to your API access app](#assign-api-users-to-a-role-and-to-your-api-access-app). - -### Set up Access Gateway for API access +1. [Enable the Access Gateway API](#enable-the-access-gateway-api). +1. [Scopes required for offline mode](#scopes-required-for-offline-mode). -Users can access OIG APIs by authenticating with an [OAuth 2.0 access token](https://developer.okta.com/docs/api/openapi/okta-management/guides/overview/#oauth-20-access-token). To obtain an OAuth 2.0 access token for API authentication, you need to have an app in Okta for API access: +### Enable the Access Gateway API -* If you don't have an app for API access, see [User-based API access setup](/docs/guides/set-up-oauth-api/main/#user-based-api-access-setup) to create an OIDC app. Grant the [scopes required for labels](#scopes-required-for-labels) to the OIDC app (in addition to any other scopes you may need). +To enable the Access Gateway API, follow the steps in [Enable the Access Gateway API](https://help.okta.com/okta_help.htm?type=oag&id=api-enable-disable). -* If you already have an OIDC app for API access, ensure that your app is granted with the [scopes required for labels](#scopes-required-for-labels). - -* If you're using Okta Workflows, ensure that the **Okta Workflows OAuth** app is granted with the [scopes required for offline mode](#scopes-required-for-offline-mode). See [Authorization > Create a connection from the current Okta org](https://help.okta.com/okta_help.htm?type=wf&id=ext-okta-misc-authorization). +You must create a JWT token to authenticate your API requests. For instructions, see [Build a JWT for Client Authentication](/docs/guides/build-self-signed-jwt/java/main/) and [How to generate a JWT for Okta Access Gateway APIs](https://support.okta.com/help/s/article/how-to-generate-jwt-for-okta-access-gateway-apis). ### Scopes required for offline mode -Your OAuth 2.0 access token must have the appropriate scopes for the [Labels API](https://developer.okta.com/docs/api/iga/openapi/governance.api/tag/Labels/) request. +After you enabled the Access Gateway API, add the following scopes to an access token to manage offline mode configuration and policies: -Ensure that the following scopes are granted to your app for API authentication: +* `okta.oag.app.manage` +* `okta.oag.idp.manage` +* `okta.oag.authenticationService.manage` -* `okta.governance.labels.manage` -* `okta.apps.read` -* `okta.groups.read` -* `okta.governance.entitlements.read` -* `okta.governance.collections.read` +To create an access token, use the [Access Tokens API](https://developer.okta.com/docs/api/openapi/oag/oag/tag/AccessTokens/). -Assign the super admin (`SUPER_ADMIN`) role to your API users. +## Configure offline mode for Access Gateway -### Configure offline mode for identity providers +The following sections explain which endpoints to use to configure offline mode for Access Gateway. -Configuration for enabling offline capabilities on specific Identity Providers (IdPs) associated with OAG. -**GET** /api/v1/idps/{idpId}/offline-config -Retrieves the current offline configuration for a specific IdP. -**PUT** /api/v1/idps/{idpId}/offline-config -Updates the offline access configuration. This endpoint facilitates the requirement that admins must explicitly configure the fallback local IdP. -**Request Body Schema:** +### Assign failover mode for the identity provider -``` -{ - "enabled": true, - "max_offline_duration_days": 30, - "fallback_mode": "automatic", - "sync_frequency_seconds": 3600 -} -``` +Set your Okta IdP to use automatic failover so that Access Gateway can switch to offline mode if the IdP becomes unavailable. Enabling offline mode on your existing IdP instructs Access Gateway to use a backup directory for authentication if the online IdP becomes unavailable. -* **enabled**: Toggles the capability for this IdP to switch to offline mode. -* **max_offline_duration_days**: Hard cap on offline duration (Note: Product hard limit is 1 year). -* **fallback_mode**: - * automatic: OAG dynamically detects connection loss and switches. - * manual: Requires admin intervention (Extended Mode). - * **Response:** 200 OK +Use the [Assign the failover mode for an IdP](/openapi/oag/oag/tag/IDPs-Offline-Mode/#tag/IDPs-Offline-Mode/operation/assignIdPOfflineModeFailoverMode) endpoint. #### Request example ```bash - +curl -i -X POST \ + 'https://oag.domain.tld/api/v2/idps/{idpId}/offline-mode' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "mode": "AUTOMATIC" + }' ``` -#### Response example +You have now enabled your Okta IdP to use automatic failover. This means that Access Gateway can switch to offline mode if the IdP becomes unavailable. -```json +### Create and configure the offline mode directory -``` +Create an offline mode directory for your IdP and configure the connection settings to your LDAP directory. The offline mode directory is a backup directory that Access Gateway uses for authentication when the connection to the online IdP is lost. -### Configure offline sign-in policies +You must define your LDAP directory connection and synchronization settings for authentication during offline mode. Refer to your LDAP directory credentials and structure and use those values in the request body parameters. -As per the requirement, offline policies are **not** synced from Okta and must be explicitly configured on the OAG instance at the IdP level,. -**GET** /api/v1/idps/{idpId}/offline-policies -Fetches the list of offline sign-on policies. -**POST** /api/v1/idps/{idpId}/offline-policies -Creates a new offline policy rule. Validates that the authenticators specified are supported in offline mode (currently Password and Smart Card only,). -**Request Body Schema:** +Use the [Create an offline mode directory](/openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createOfflineModeDirectory) endpoint. +#### Request example + +```bash +curl -i -X POST \ + 'https://oag.domain.tld/api/v2/idps/{idpId}/offline-mode/directories' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "type": "OPEN_LDAP", + "connection": { + "connectionUrl": "ldaps://dc1.example.com:636", + "bindDn": "cn=svc-oag,ou=service-accounts,dc=example,dc=com", + "bindCredential": "" + }, + "config": { + "usernameLDAPAttribute": "uid", + "uniqueIdAttribute": "entryUUID", + "userSearchDn": "ou=users,dc=example,dc=com", + "userObjectClasses": [ + "inetOrgPerson", + "organizationalPerson" + ], + "userObjectFilter": "(objectClass=inetOrgPerson)", + "groupNameLDAPAttribute": "cn", + "groupSearchDn": "ou=groups,dc=example,dc=com", + "groupObjectClasses": [ + "groupOfUniqueNames" + ], + "memberAttribute": "uniqueMember", + "memberUserAttribute": "uid", + "rdnLdapAttribute": "cn" + } + }' ``` + +These settings indicate that the offline mode directory is an OpenLDAP directory with the specified connection details and configuration for user and group attributes. Access Gateway uses this information to connect to the LDAP directory and synchronize user and group information for authentication during offline mode. + +Your offline mode directory is now created and configured. + +#### Response example + +```json { - "name": "Emergency Access Policy", - "priority": 1, - "conditions": { - "user_groups": { - "include": ["Admins", "Emergency_Response_Team"] - } + "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", + "type": "OPEN_LDAP", + "connection": { + "connectionUrl": "ldaps://dc1.example.com:636", + "bindDn": "cn=svc-oag,ou=service-accounts,dc=example,dc=com", + "bindCredential": "" }, - "requirements": { - "authenticators": [ - { - "type": "password", - "required": true - }, - { - "type": "smart_card", - "required": false - } - ] + "config": { + "usernameLDAPAttribute": "uid", + "uniqueIdAttribute": "entryUUID", + "userSearchDn": "ou=users,dc=example,dc=com", + "userObjectClasses": [ + "inetOrgPerson", + "organizationalPerson" + ], + "userObjectFilter": "(objectClass=inetOrgPerson)", + "groupNameLDAPAttribute": "cn", + "groupSearchDn": "ou=groups,dc=example,dc=com", + "groupObjectClasses": [ + "groupOfUniqueNames" + ], + "memberAttribute": "uniqueMember", + "memberUserAttribute": "uid", + "rdnLdapAttribute": "cn" } } ``` -* **constraints**: The API must reject fastpass or webauthn in this release, as they are Phase 2/3 goals. +Copy the connection URL in the response to use in the next step. +### Test the directory connection -#### Request example +Optional. Verify that your offline directory connection is functional before entering offline mode. -This example assigns two label values to two resources: +Use the [Create a test directory connection](/openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createTestDirectoryConnection) endpoint. -```bash +#### Request example +```bash +curl -i -X POST \ + 'https://oag.domain.tld/api/v2/idps/{idpId}/offline-mode/test-directory-connection' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "connectionUrl": "ldap://ldap.domain.tld:389", + "bindDn": "cn=admin,dc=domain,dc=tld", + "bindCredential": "" + }' ``` -#### Response example +The `connectionUrl` can be found in the [response](#create-and-configure-the-offline-mode-directory) from the previous step. The `bindDn` and `bindCredential` are the same credentials you used to create the offline mode directory. -```json +If your connection settings are correct, you receive an HTTP 204 No Content response. -``` +### Configure the offline mode health policy -### Monitor offline status and trigger extended offline mode +Optional. You can configure the health policy settings for offline mode to control how Access Gateway monitors the health of the connection to your IdP and when offline mode is triggered. -Endpoints to monitor connectivity status and manually invoke "Extended Offline Mode" for scenarios like submarine deployments or intentional air-gapping,. +Access Gateway sets default values for all health policy parameters, but you can adjust these settings based on your environment and needs. -**GET** /api/v1/system/offline-status -Returns the current connectivity state of the OAG appliance. -**Response Schema:** +1. Retrieve your current health policy settings using the [Retrieve an offline mode health policy](/openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/getOfflineModeHealthPolicy) endpoint. +1. Use the [Replace an offline mode health policy](/openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/replaceOfflineModeHealthPolicy) endpoint to make any necessary changes. -``` -{ - "connection_status": "disconnected", - "current_mode": "offline", - "offline_since": "2025-10-23T14:30:00Z", - "last_sync_timestamp": "2025-10-23T12:00:00Z", - "events_cached_count": 452 -} -``` - -**events_cached_count**: Monitoring for the system log events cached locally while disconnected. -**POST** /api/v1/system/offline-mode/extended -Triggers "Extended Offline Mode." This forces the system to remain offline regardless of connectivity until manually disabled. - -**Request Body:** +#### Request example -``` -{ - "action": "enable", - "reason": "Planned Submarine Deployment" -} +```bash +curl -i -X PUT \ + 'https://oag.domain.tld/api/v2/idps/{idpId}/offline-mode/health-policy' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "healthCheckInterval": 180, + "timeout": 4, + "maxRetries": 2, + "failureThreshold": 4, + "successThreshold": 3, + "recoveryCooldownInterval": 144000 + }' ``` -#### Request example +These health policy settings indicate that Access Gateway checks the health of the IdP connection every 3 minutes, with a timeout of 4 seconds. If there are 4 consecutive failures, Access Gateway enters offline mode. Access Gateway attempts to recover every 4 hours and requires 3 consecutive successful health checks to exit offline mode. -This example replaces the background color of `lblo3v6xlwdtEX2il1d1` (SOX) to purple. +### Enable the authentication service -```bash +The authentication service is a component of Access Gateway that handles user authentication when in offline mode. You need to enable the authentication service and provide the necessary configuration details for it to function properly. -``` +This step is needed only if your authentication service isn't already configured. Enabling the authentication service provides Access Gateway with the necessary information to set up the service, including server nodes, database connection details, public domain, and certificate information. -#### Response example +After the authentication service is enabled, Access Gateway can use it to authenticate users locally when in offline mode. -```json - -``` +Use the [Enable the authentication service setting](/openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/enableAuthenticationServiceSetting) endpoint. -## Data models and limitations +#### Request example +```bash +curl -i -X POST \ + https://oag.domain.tld/api/v2/settings/authentication-service \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "serverNodes": [ + "worker-node1.test-oag.com" + ], + "database": { + "type": "mysql", + "host": "db.domain.tld", + "port": 5432, + "username": "", + "password": "", + "name": "oagofflinemode" + }, + "publicDomain": "offline-idp-service.domain.tld", + "certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c" + }' +``` +These settings indicate that the authentication service is running on a server node at `worker-node1.test-oag.com`, using a MySQL database hosted at `db.domain.tld` with the specified credentials. The public domain for the authentication service is `offline-idp-service.domain.tld`, and it uses the certificate with the provided ID for secure communication. -### Supported authenticators +Users are directed to the public domain to authenticate when Access Gateway is in offline mode. -When configuring policies via the /offline-policies endpoint, the authenticator type must validate against: +### Monitor your offline mode status -* PASSWORD: Validates against on-prem AD/LDAP hash. -* SMART\_CARD: PIV/CAC validation. -* *Future:* OKTA\_VERIFY (FastPass) \- **DISABLED in v1**. +After you've configured offline mode, you can monitor the status of your IdP connection and the health of the authentication service. -### User restrictions +Monitor the health of your authentication service by using [Retrieve the authentication service health check](/openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/getAuthenticationServiceHealthCheck) endpoint. -The API must enforce the following logic limitations: +## Summary -* **No App Creation:** POST /api/v1/apps requests must return 403 Forbidden or specific error E00\_OFFLINE\_MODE when current\_mode is "offline". -* **No User Onboarding:** Attempts to create new users via OAG during offline mode must be blocked unless specific local-only flows (Phase 2\) are enabled. +You've successfully configured offline mode. Your IdP can now failover to offline mode if the connection to the online IdP is lost. And your LDAP directory is set up as the backup directory for authentication during offline mode. -## Security considerations +## See also -* **Local Storage:** Cached credentials and logs must be encrypted at rest on the appliance. -* **Auth:** Access to these offline configuration APIs requires the standard OAG Admin Session Token. -* **Audit:** Changes to offline policies (e.g., weakening security by removing Smart Card requirements) must be logged locally and synced to Okta System Log immediately upon reconnection. +* [Access Gateway API documentation](https://developer.okta.com/openapi/oag/guides/overview/) +* [Temporary Offline Access (Disconnected Mode)]() \ No newline at end of file From d026c0ba27c0030e4f869e7cc354a2aa771b36bb Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Tue, 24 Feb 2026 13:58:21 -0500 Subject: [PATCH 3/6] SME feedback --- .../guides/oag-offline-mode/main/index.md | 152 +++++++++++------- 1 file changed, 97 insertions(+), 55 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md index 26ab98e5e2d..36e5f049664 100644 --- a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md @@ -20,7 +20,9 @@ Learn how to configure Temporary Offline Access (offline mode) for Access Gatewa #### What you need -An Okta org that's subscribed to Access Gateway +* An Okta org that's subscribed to Access Gateway +* An LDAP server +* A MySQL database --- @@ -32,16 +34,16 @@ You can only configure offline mode for Access Gateway using Access Gateway APIs ## Set up Access Gateway APIs for offline mode configuration -Set up Okta so that you can authenticate to Okta APIs and have the proper roles and scopes to manage labels: +Set up Access Gateway so that you can authenticate to Access Gateway APIs and have the proper roles and scopes to manage labels: 1. [Enable the Access Gateway API](#enable-the-access-gateway-api). -1. [Scopes required for offline mode](#scopes-required-for-offline-mode). +2. [Scopes required for offline mode](#scopes-required-for-offline-mode). ### Enable the Access Gateway API To enable the Access Gateway API, follow the steps in [Enable the Access Gateway API](https://help.okta.com/okta_help.htm?type=oag&id=api-enable-disable). -You must create a JWT token to authenticate your API requests. For instructions, see [Build a JWT for Client Authentication](/docs/guides/build-self-signed-jwt/java/main/) and [How to generate a JWT for Okta Access Gateway APIs](https://support.okta.com/help/s/article/how-to-generate-jwt-for-okta-access-gateway-apis). +You must create a JWT token to authenticate your API requests. For instructions, see [Build a JWT for Client Authentication](http:///docs/guides/build-self-signed-jwt/java/main/) and [How to generate a JWT for Okta Access Gateway APIs](https://support.okta.com/help/s/article/how-to-generate-jwt-for-okta-access-gateway-apis). ### Scopes required for offline mode @@ -57,11 +59,83 @@ To create an access token, use the [Access Tokens API](https://developer.okta.co The following sections explain which endpoints to use to configure offline mode for Access Gateway. +### Configure an app for offline mode + +Before you can enable offline mode for Access Gateway, you need to configure an app in Access Gateway to represent your on-premises applications. This app is used to define the policies and settings for offline mode. + +#### Create an app + +Create an app in Access Gateway. + +Use the [Create an app](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Applications/#tag/Applications/operation/createApplication) endpoint. + +If you have an app that you want to use for testing offline mode, retrieve the app's ID and use that in the next steps. Use the [List apps](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Applications/#tag/Applications/operation/listApplication) endpoint to retrieve the app's ID. + +#### Assign the offline mode state for the app + +Set the offline mode state for your app. This setting indicates whether the app is enabled for offline mode. + +Use the [Assign the offline mode state for an app](/openapi/oag/oag/tag/Application-Offline-Mode/#tag/Application-Offline-Mode/operation/assignApplicationOfflineModeState) endpoint. + +##### Request example + +```bash +curl -i -X POST \ + 'https://oag.domain.tld/api/v2/apps/{applicationId}/offline-mode' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "state": "TEST" + }' +``` + +This setting indicates that the app is in a test state for offline mode. In this state, Access Gateway simulates offline mode for the app, but users can still authenticate through the online IdP. This allows you to verify that your offline mode configuration is working properly before fully enabling offline mode. + +When you want to enable offline mode for the app, change the `state` value to `ACTIVE`. In this state, Access Gateway uses the health policy settings to determine when to switch to offline mode for the app. + +### Enable the authentication service + +The authentication service is a component of Access Gateway that handles user authentication when in offline mode. You need to enable the authentication service and provide the necessary configuration details for it to function properly. + +This step is needed only if your authentication service isn't already configured. Enabling the authentication service provides Access Gateway with the necessary information to set up the service, including server nodes, database connection details, public domain, and certificate information. + +After the authentication service is enabled, Access Gateway can use it to authenticate users locally when in offline mode. + +Use the [Enable the authentication service setting](http:///openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/enableAuthenticationServiceSetting) endpoint. + +#### Request example + +```bash +curl -i -X POST \ + https://oag.domain.tld/api/v2/settings/authentication-service \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "serverNodes": [ + "worker-node1.test-oag.com" + ], + "database": { + "type": "mysql", + "host": "db.domain.tld", + "port": 5432, + "username": "", + "password": "", + "name": "oagofflinemode" + }, + "publicDomain": "offline-idp-service.domain.tld", + "certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c" + }' +``` + +These settings indicate that the authentication service is running on a server node at `worker-node1.test-oag.com`, using a MySQL database hosted at `db.domain.tld` with the specified credentials. The public domain for the authentication service is `offline-idp-service.domain.tld`, and it uses the certificate with the provided ID for secure communication. + +Users are directed to the public domain to authenticate when Access Gateway is in offline mode. + ### Assign failover mode for the identity provider Set your Okta IdP to use automatic failover so that Access Gateway can switch to offline mode if the IdP becomes unavailable. Enabling offline mode on your existing IdP instructs Access Gateway to use a backup directory for authentication if the online IdP becomes unavailable. -Use the [Assign the failover mode for an IdP](/openapi/oag/oag/tag/IDPs-Offline-Mode/#tag/IDPs-Offline-Mode/operation/assignIdPOfflineModeFailoverMode) endpoint. +Use the [Assign the failover mode for an IdP](http:///openapi/oag/oag/tag/IDPs-Offline-Mode/#tag/IDPs-Offline-Mode/operation/assignIdPOfflineModeFailoverMode) endpoint. #### Request example @@ -83,7 +157,7 @@ Create an offline mode directory for your IdP and configure the connection setti You must define your LDAP directory connection and synchronization settings for authentication during offline mode. Refer to your LDAP directory credentials and structure and use those values in the request body parameters. -Use the [Create an offline mode directory](/openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createOfflineModeDirectory) endpoint. +Use the [Create an offline mode directory](http:///openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createOfflineModeDirectory) endpoint. #### Request example @@ -156,13 +230,19 @@ Your offline mode directory is now created and configured. } ``` -Copy the connection URL in the response to use in the next step. +Copy the connection URL in the response to use when you [test the directory connection](#test-the-directory-connection). + +### Use a policy to assign groups to the app for offline mode + +Optional, but recommended. After you've created and configured the offline mode directory, assign groups to the offline mode policy of the app. When you assign groups to the offline mode policy of the app, only users in those groups are allowed to authenticate to the app when Access Gateway is in offline mode. + +Before you assign groups to the application, ensure that the groups exist in your LDAP directory. If your groups originate in Okta, you can sync them to your LDAP server using the [Okta LDAP agent](https://help.okta.com/okta_help.htm?type=oie&id=ext_LDAP_Provisioning). ### Test the directory connection -Optional. Verify that your offline directory connection is functional before entering offline mode. +Optional, but recommended. Verify that your offline directory connection is functional before entering offline mode. -Use the [Create a test directory connection](/openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createTestDirectoryConnection) endpoint. +Use the [Create a test directory connection](http:///openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createTestDirectoryConnection) endpoint. #### Request example @@ -188,8 +268,8 @@ Optional. You can configure the health policy settings for offline mode to contr Access Gateway sets default values for all health policy parameters, but you can adjust these settings based on your environment and needs. -1. Retrieve your current health policy settings using the [Retrieve an offline mode health policy](/openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/getOfflineModeHealthPolicy) endpoint. -1. Use the [Replace an offline mode health policy](/openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/replaceOfflineModeHealthPolicy) endpoint to make any necessary changes. +1. Retrieve your current health policy settings using the [Retrieve an offline mode health policy](http:///openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/getOfflineModeHealthPolicy) endpoint. +2. Use the [Replace an offline mode health policy](http:///openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/replaceOfflineModeHealthPolicy) endpoint to make any necessary changes. #### Request example @@ -204,55 +284,17 @@ curl -i -X PUT \ "maxRetries": 2, "failureThreshold": 4, "successThreshold": 3, - "recoveryCooldownInterval": 144000 - }' -``` - -These health policy settings indicate that Access Gateway checks the health of the IdP connection every 3 minutes, with a timeout of 4 seconds. If there are 4 consecutive failures, Access Gateway enters offline mode. Access Gateway attempts to recover every 4 hours and requires 3 consecutive successful health checks to exit offline mode. - -### Enable the authentication service - -The authentication service is a component of Access Gateway that handles user authentication when in offline mode. You need to enable the authentication service and provide the necessary configuration details for it to function properly. - -This step is needed only if your authentication service isn't already configured. Enabling the authentication service provides Access Gateway with the necessary information to set up the service, including server nodes, database connection details, public domain, and certificate information. - -After the authentication service is enabled, Access Gateway can use it to authenticate users locally when in offline mode. - -Use the [Enable the authentication service setting](/openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/enableAuthenticationServiceSetting) endpoint. - -#### Request example - -```bash -curl -i -X POST \ - https://oag.domain.tld/api/v2/settings/authentication-service \ - -H 'Authorization: Bearer ' \ - -H 'Content-Type: application/json' \ - -d '{ - "serverNodes": [ - "worker-node1.test-oag.com" - ], - "database": { - "type": "mysql", - "host": "db.domain.tld", - "port": 5432, - "username": "", - "password": "", - "name": "oagofflinemode" - }, - "publicDomain": "offline-idp-service.domain.tld", - "certificateId": "15cc2bc6-b280-4d94-a0bf-c91751b40d9c" + "recoveryCooldownInterval": 1440 }' ``` -These settings indicate that the authentication service is running on a server node at `worker-node1.test-oag.com`, using a MySQL database hosted at `db.domain.tld` with the specified credentials. The public domain for the authentication service is `offline-idp-service.domain.tld`, and it uses the certificate with the provided ID for secure communication. - -Users are directed to the public domain to authenticate when Access Gateway is in offline mode. +These health policy settings indicate that Access Gateway checks the health of the IdP connection every 3 minutes, with a timeout of 4 seconds. If there are 4 consecutive failures, Access Gateway enters offline mode. Access Gateway attempts to recover every three minutes. After three consecutive successful attempts, offline mode is exited after a cooldown period of 24 minutes. -### Monitor your offline mode status +### Monitor your authentication service status -After you've configured offline mode, you can monitor the status of your IdP connection and the health of the authentication service. +After you've configured offline mode, you can monitor the status of your authentication service. -Monitor the health of your authentication service by using [Retrieve the authentication service health check](/openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/getAuthenticationServiceHealthCheck) endpoint. +Monitor the health of your authentication service by using [Retrieve the authentication service health check](http:///openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/getAuthenticationServiceHealthCheck) endpoint. ## Summary @@ -261,4 +303,4 @@ You've successfully configured offline mode. Your IdP can now failover to offlin ## See also * [Access Gateway API documentation](https://developer.okta.com/openapi/oag/guides/overview/) -* [Temporary Offline Access (Disconnected Mode)]() \ No newline at end of file +* [Temporary Offline Access (Disconnected Mode)]() From 07fffc9d330f3eb9c7260327dbd817ae09c030b0 Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Fri, 27 Feb 2026 13:26:42 -0500 Subject: [PATCH 4/6] SME feedback --- .../guides/oag-offline-mode/main/index.md | 218 +++++++++--------- 1 file changed, 106 insertions(+), 112 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md index 36e5f049664..d7d4972a23c 100644 --- a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md @@ -8,7 +8,7 @@ layout: Guides -This guide explains how to configure Temporary Offline Access (offline mode) for Access Gateway using Access Gateway APIs. Offline mode allows users to authenticate locally through Access Gateway and continue accessing protected on-premises applications, even when Access Gateway is unable to reach Okta. +This guide explains how to configure Temporary Offline Access (offline mode) for Access Gateway using Access Gateway APIs. Offline mode allows users to authenticate locally through Access Gateway and continue accessing protected on-premises apps, even when Access Gateway is unable to reach Okta. > **Note:** The Access Gateway APIs that are used for offline mode configuration are in Early Access (EA). @@ -21,29 +21,31 @@ Learn how to configure Temporary Offline Access (offline mode) for Access Gatewa #### What you need * An Okta org that's subscribed to Access Gateway -* An LDAP server +* An [LDAP server](https://help.okta.com/okta_help.htm?type=oag&id=ext_oag_about_datastore) * A MySQL database +* An app, such as a [generic app](https://help.okta.com/okta_help.htm?type=oag&id=ext_oag_app_gen_header) +* An [Okta identity provider (IdP)](https://help.okta.com/okta_help.htm?type=oag&id=ext_oag_config_idp_okta) --- ## Overview -Offline mode is a feature of Access Gateway that allows it to continue functioning with modified capabilities when the connection to the identity provider (IdP) is lost. It enables your users to authenticate locally through Access Gateway and continue accessing protected on-premises applications. +Offline mode is a feature of Access Gateway that allows it to continue functioning with modified capabilities when the connection to the identity provider (IdP) is lost. It enables your users to authenticate locally through Access Gateway and continue accessing protected on-premises apps. You can only configure offline mode for Access Gateway using Access Gateway APIs. This guide explains how to set up Access Gateway for API access and how to use Access Gateway APIs to configure offline mode. ## Set up Access Gateway APIs for offline mode configuration -Set up Access Gateway so that you can authenticate to Access Gateway APIs and have the proper roles and scopes to manage labels: +Set up Access Gateway so that you can authenticate to Access Gateway APIs and manage offline mode configuration and policies. 1. [Enable the Access Gateway API](#enable-the-access-gateway-api). -2. [Scopes required for offline mode](#scopes-required-for-offline-mode). +1. [Scopes required for offline mode](#scopes-required-for-offline-mode). ### Enable the Access Gateway API To enable the Access Gateway API, follow the steps in [Enable the Access Gateway API](https://help.okta.com/okta_help.htm?type=oag&id=api-enable-disable). -You must create a JWT token to authenticate your API requests. For instructions, see [Build a JWT for Client Authentication](http:///docs/guides/build-self-signed-jwt/java/main/) and [How to generate a JWT for Okta Access Gateway APIs](https://support.okta.com/help/s/article/how-to-generate-jwt-for-okta-access-gateway-apis). +You must create a JWT token to authenticate your API requests. For instructions, see [Build a JWT for Client Authentication](/docs/guides/build-self-signed-jwt/java/main/) and [How to generate a JWT for Okta Access Gateway APIs](https://support.okta.com/help/s/article/how-to-generate-jwt-for-okta-access-gateway-apis). ### Scopes required for offline mode @@ -53,45 +55,24 @@ After you enabled the Access Gateway API, add the following scopes to an access * `okta.oag.idp.manage` * `okta.oag.authenticationService.manage` -To create an access token, use the [Access Tokens API](https://developer.okta.com/docs/api/openapi/oag/oag/tag/AccessTokens/). +To create an access token, use the [Access Tokens API](https://developer.okta.com/docs/api/openapi/oag/oag/accesstokens/createaccesstoken). -## Configure offline mode for Access Gateway - -The following sections explain which endpoints to use to configure offline mode for Access Gateway. - -### Configure an app for offline mode - -Before you can enable offline mode for Access Gateway, you need to configure an app in Access Gateway to represent your on-premises applications. This app is used to define the policies and settings for offline mode. - -#### Create an app - -Create an app in Access Gateway. +## Install and enable offline mode -Use the [Create an app](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Applications/#tag/Applications/operation/createApplication) endpoint. +To set up offline mode, you need to install the offline mode components on Access Gateway and enable the offline mode feature. -If you have an app that you want to use for testing offline mode, retrieve the app's ID and use that in the next steps. Use the [List apps](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Applications/#tag/Applications/operation/listApplication) endpoint to retrieve the app's ID. +1. Open your [Access Gateway Management console command line](https://help.okta.com/okta_help.htm?type=oag&id=command-line-reference). +1. Go to the [System menu](https://help.okta.com/okta_help.htm?type=oag&id=system-menu). +1. Enter `2` and install the `okta-accessgateway-offline-mode` package. +1. Then, contact [Okta Support](https://support.okta.com) to enable the offline mode feature. -#### Assign the offline mode state for the app +> **Note:** Perform these steps on your admin node and any server nodes where you want the authentication service to run. -Set the offline mode state for your app. This setting indicates whether the app is enabled for offline mode. - -Use the [Assign the offline mode state for an app](/openapi/oag/oag/tag/Application-Offline-Mode/#tag/Application-Offline-Mode/operation/assignApplicationOfflineModeState) endpoint. - -##### Request example - -```bash -curl -i -X POST \ - 'https://oag.domain.tld/api/v2/apps/{applicationId}/offline-mode' \ - -H 'Authorization: Bearer ' \ - -H 'Content-Type: application/json' \ - -d '{ - "state": "TEST" - }' -``` +Now that offline mode is installed and enabled, configure the offline mode settings. -This setting indicates that the app is in a test state for offline mode. In this state, Access Gateway simulates offline mode for the app, but users can still authenticate through the online IdP. This allows you to verify that your offline mode configuration is working properly before fully enabling offline mode. +## Configure offline mode for Access Gateway -When you want to enable offline mode for the app, change the `state` value to `ACTIVE`. In this state, Access Gateway uses the health policy settings to determine when to switch to offline mode for the app. +The following sections explain which endpoints to use to configure offline mode for Access Gateway. ### Enable the authentication service @@ -101,7 +82,7 @@ This step is needed only if your authentication service isn't already configured After the authentication service is enabled, Access Gateway can use it to authenticate users locally when in offline mode. -Use the [Enable the authentication service setting](http:///openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/enableAuthenticationServiceSetting) endpoint. +Use the [Enable the authentication service setting](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/enableAuthenticationServiceSetting) endpoint. #### Request example @@ -131,11 +112,17 @@ These settings indicate that the authentication service is running on a server n Users are directed to the public domain to authenticate when Access Gateway is in offline mode. +### Monitor your authentication service status + +After you've configured offline mode, you can monitor the status of your authentication service. + +Monitor the health of your authentication service by using [Retrieve the authentication service health check](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/getAuthenticationServiceHealthCheck) endpoint. + ### Assign failover mode for the identity provider Set your Okta IdP to use automatic failover so that Access Gateway can switch to offline mode if the IdP becomes unavailable. Enabling offline mode on your existing IdP instructs Access Gateway to use a backup directory for authentication if the online IdP becomes unavailable. -Use the [Assign the failover mode for an IdP](http:///openapi/oag/oag/tag/IDPs-Offline-Mode/#tag/IDPs-Offline-Mode/operation/assignIdPOfflineModeFailoverMode) endpoint. +Use the [Assign the failover mode for an IdP](https://developer.okta.com/docs/api/openapi/oag/oag/tag/IDPs-Offline-Mode/#tag/IDPs-Offline-Mode/operation/assignIdPOfflineModeFailoverMode) endpoint. #### Request example @@ -151,13 +138,63 @@ curl -i -X POST \ You have now enabled your Okta IdP to use automatic failover. This means that Access Gateway can switch to offline mode if the IdP becomes unavailable. +### Configure the offline mode health policy + +Optional. You can configure the health policy settings for offline mode to control how Access Gateway monitors the health of the connection to your IdP and when offline mode is triggered. You can configure the offline mode health policy at any time. + +Access Gateway sets default values for all health policy parameters, but you can adjust these settings based on your environment and needs. + +1. Retrieve your current health policy settings using the [Retrieve an offline mode health policy](https://developer.okta.com/docs/api/openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/getOfflineModeHealthPolicy) endpoint. +2. Use the [Replace an offline mode health policy](https://developer.okta.com/docs/api/openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/replaceOfflineModeHealthPolicy) endpoint to make any necessary changes. + +#### Request example + +```bash +curl -i -X PUT \ + 'https://oag.domain.tld/api/v2/idps/{idpId}/offline-mode/health-policy' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "healthCheckInterval": 180, + "timeout": 4, + "maxRetries": 2, + "failureThreshold": 4, + "successThreshold": 3, + "recoveryCooldownInterval": 1440 + }' +``` + +These health policy settings indicate that Access Gateway checks the health of the IdP connection every 3 minutes, with a timeout of 4 seconds. If there are 4 consecutive failures, Access Gateway enters offline mode. Access Gateway attempts to recover every three minutes. After three consecutive successful attempts, offline mode is exited after a cooldown period of 24 minutes. + +### Test the directory connection + +Optional, but recommended. Verify that your offline directory connection is functional before creating your offline mode directory. The `/idps/{idpId}/offline-mode/test-directory-connection` endpoint tests whether the authentication service can reach your offline mode directory. + +Use the [Create a test directory connection](https://developer.okta.com/docs/api/openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createTestDirectoryConnection) endpoint. + +#### Request example + +```bash +curl -i -X POST \ + 'https://oag.domain.tld/api/v2/idps/{idpId}/offline-mode/test-directory-connection' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "connectionUrl": "ldap://ldap.domain.tld:389", + "bindDn": "cn=admin,dc=domain,dc=tld", + "bindCredential": "" + }' +``` + +If your connection settings are correct, you receive an HTTP 204 No Content response. + ### Create and configure the offline mode directory -Create an offline mode directory for your IdP and configure the connection settings to your LDAP directory. The offline mode directory is a backup directory that Access Gateway uses for authentication when the connection to the online IdP is lost. +Create an offline mode directory for your Okta IdP and configure the connection settings to your LDAP directory. The offline mode directory is a backup directory that Access Gateway uses for authentication when the connection to the online IdP is lost. You must define your LDAP directory connection and synchronization settings for authentication during offline mode. Refer to your LDAP directory credentials and structure and use those values in the request body parameters. -Use the [Create an offline mode directory](http:///openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createOfflineModeDirectory) endpoint. +Use the [Create an offline mode directory](https://developer.okta.com/docs/api/openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createOfflineModeDirectory) endpoint. #### Request example @@ -189,7 +226,7 @@ curl -i -X POST \ ], "memberAttribute": "uniqueMember", "memberUserAttribute": "uid", - "rdnLdapAttribute": "cn" + "rdnLdapAttribute": "uid" } }' ``` @@ -198,109 +235,66 @@ These settings indicate that the offline mode directory is an OpenLDAP directory Your offline mode directory is now created and configured. -#### Response example - -```json -{ - "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", - "type": "OPEN_LDAP", - "connection": { - "connectionUrl": "ldaps://dc1.example.com:636", - "bindDn": "cn=svc-oag,ou=service-accounts,dc=example,dc=com", - "bindCredential": "" - }, - "config": { - "usernameLDAPAttribute": "uid", - "uniqueIdAttribute": "entryUUID", - "userSearchDn": "ou=users,dc=example,dc=com", - "userObjectClasses": [ - "inetOrgPerson", - "organizationalPerson" - ], - "userObjectFilter": "(objectClass=inetOrgPerson)", - "groupNameLDAPAttribute": "cn", - "groupSearchDn": "ou=groups,dc=example,dc=com", - "groupObjectClasses": [ - "groupOfUniqueNames" - ], - "memberAttribute": "uniqueMember", - "memberUserAttribute": "uid", - "rdnLdapAttribute": "cn" - } -} -``` - -Copy the connection URL in the response to use when you [test the directory connection](#test-the-directory-connection). - -### Use a policy to assign groups to the app for offline mode - -Optional, but recommended. After you've created and configured the offline mode directory, assign groups to the offline mode policy of the app. When you assign groups to the offline mode policy of the app, only users in those groups are allowed to authenticate to the app when Access Gateway is in offline mode. - -Before you assign groups to the application, ensure that the groups exist in your LDAP directory. If your groups originate in Okta, you can sync them to your LDAP server using the [Okta LDAP agent](https://help.okta.com/okta_help.htm?type=oie&id=ext_LDAP_Provisioning). +### Assign the offline mode state for the app -### Test the directory connection - -Optional, but recommended. Verify that your offline directory connection is functional before entering offline mode. +Set the offline mode state for your app. This setting indicates whether the app is enabled for offline mode. -Use the [Create a test directory connection](http:///openapi/oag/oag/tag/IDPs-Offline-Mode-Directory/#tag/IDPs-Offline-Mode-Directory/operation/createTestDirectoryConnection) endpoint. +1. Use the [List apps](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Applications/#tag/Applications/operation/listApplication) endpoint to retrieve your [app's ID](#what-you-need). +1. Then, use the [Assign the offline mode state for an app](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Application-Offline-Mode/#tag/Application-Offline-Mode/operation/assignApplicationOfflineModeState) endpoint. #### Request example ```bash curl -i -X POST \ - 'https://oag.domain.tld/api/v2/idps/{idpId}/offline-mode/test-directory-connection' \ + 'https://oag.domain.tld/api/v2/apps/{applicationId}/offline-mode' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ - "connectionUrl": "ldap://ldap.domain.tld:389", - "bindDn": "cn=admin,dc=domain,dc=tld", - "bindCredential": "" + "state": "TEST" }' ``` -The `connectionUrl` can be found in the [response](#create-and-configure-the-offline-mode-directory) from the previous step. The `bindDn` and `bindCredential` are the same credentials you used to create the offline mode directory. +This setting indicates that the app is in a test state for offline mode. In this state, Access Gateway simulates offline mode for the app, but users can still authenticate through the online IdP. This allows you to verify that your offline mode configuration is functional before fully enabling offline mode. -If your connection settings are correct, you receive an HTTP 204 No Content response. +When you want to enable offline mode for the app, change the `state` value to `ACTIVE`. -### Configure the offline mode health policy +### Use a policy to assign groups to the app for offline mode -Optional. You can configure the health policy settings for offline mode to control how Access Gateway monitors the health of the connection to your IdP and when offline mode is triggered. +After you've created and configured the offline mode directory, assign groups to the offline mode policy of the app. When you assign groups to the offline mode policy of the app, only users in those groups are allowed to authenticate to the app when Access Gateway is in offline mode. -Access Gateway sets default values for all health policy parameters, but you can adjust these settings based on your environment and needs. +Before you assign groups to the app, ensure that the groups exist in your LDAP directory. If your groups originate in Okta, you can sync them to your LDAP server using the [Okta LDAP agent](https://help.okta.com/okta_help.htm?type=oie&id=ext_LDAP_Provisioning). -1. Retrieve your current health policy settings using the [Retrieve an offline mode health policy](http:///openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/getOfflineModeHealthPolicy) endpoint. -2. Use the [Replace an offline mode health policy](http:///openapi/oag/oag/tag/IDPs-Offline-Mode-Health-Policy/#tag/IDPs-Offline-Mode-Health-Policy/operation/replaceOfflineModeHealthPolicy) endpoint to make any necessary changes. +1. Use the [List apps](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Applications/#tag/Applications/operation/listApplication) endpoint to retrieve your [app's ID](#what-you-need). +1. Use the [Assign groups to the offline mode policy of an app](https://developer.okta.com/docs/api/openapi/oag/oag/tag/Application-Offline-Mode/#tag/Application-Offline-Mode/operation/assignApplicationOfflineModeGroupPolicy) endpoint. #### Request example ```bash curl -i -X PUT \ - 'https://oag.domain.tld/api/v2/idps/{idpId}/offline-mode/health-policy' \ + 'https://oag.domain.tld/api/v2/apps/{applicationId}/offline-mode/group-policy' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ - "healthCheckInterval": 180, - "timeout": 4, - "maxRetries": 2, - "failureThreshold": 4, - "successThreshold": 3, - "recoveryCooldownInterval": 1440 + "groups": [ + { + "name": "Admins" + }, + { + "name": "Developers" + } + ] }' ``` -These health policy settings indicate that Access Gateway checks the health of the IdP connection every 3 minutes, with a timeout of 4 seconds. If there are 4 consecutive failures, Access Gateway enters offline mode. Access Gateway attempts to recover every three minutes. After three consecutive successful attempts, offline mode is exited after a cooldown period of 24 minutes. - -### Monitor your authentication service status - -After you've configured offline mode, you can monitor the status of your authentication service. - -Monitor the health of your authentication service by using [Retrieve the authentication service health check](http:///openapi/oag/oag/tag/Settings-Authentication-Service/#tag/Settings-Authentication-Service/operation/getAuthenticationServiceHealthCheck) endpoint. +This request assigns the "Admins" and "Developers" groups to the offline mode policy of the app. Only users in these groups can authenticate to the app when Access Gateway is in offline mode. ## Summary You've successfully configured offline mode. Your IdP can now failover to offline mode if the connection to the online IdP is lost. And your LDAP directory is set up as the backup directory for authentication during offline mode. +Users are able to sign in to the offline mode app and access resources when Access Gateway is in offline mode. + ## See also * [Access Gateway API documentation](https://developer.okta.com/openapi/oag/guides/overview/) -* [Temporary Offline Access (Disconnected Mode)]() +* [Okta Access Gateway documentation](https://help.okta.com/okta_help.htm?type=oag&id=ext_oag_main) From 19a7362edfc7e3bf163afba668bd8865fd2eb28a Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Fri, 27 Feb 2026 14:30:44 -0500 Subject: [PATCH 5/6] Edits to installation steps --- .../docs/guides/oag-offline-mode/main/index.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md index d7d4972a23c..7922f35481d 100644 --- a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md @@ -61,10 +61,19 @@ To create an access token, use the [Access Tokens API](https://developer.okta.co To set up offline mode, you need to install the offline mode components on Access Gateway and enable the offline mode feature. -1. Open your [Access Gateway Management console command line](https://help.okta.com/okta_help.htm?type=oag&id=command-line-reference). +1. Open your [Management Console](https://help.okta.com/okta_help.htm?type=oag&id=command-line-reference). 1. Go to the [System menu](https://help.okta.com/okta_help.htm?type=oag&id=system-menu). 1. Enter `2` and install the `okta-accessgateway-offline-mode` package. -1. Then, contact [Okta Support](https://support.okta.com) to enable the offline mode feature. + +After the package is installed, enable the offline mode feature in your Access Gateway environment. + +1. Open the Management Console. +1. Launch the [Access Gateway Privileged Shell](https://help.okta.com/oag/en-us/content/topics/access-gateway/command-line-console-reference-system.htm#LaunchShell). +1. Open the `/opt/oag/data/gui/specs/icsgw_spgw_features.json` file with `sudo` privileges using your text editor. For example, if you use the vi editor, use this command: `sudo vi /opt/oag/data/gui/specs/icsgw_spgw_features.json`. +1. Search for `offlinemode`. +1. Change `"show": false` to `"show": true`. +1. Save the file. The `"show": false` field is read-only. When you save the file, ensure that you override the read-only attribute to save it. For example, when using vi, use this command: `:w!`. +1. [Restart the Access Gateway Admin service](https://help.okta.com/oag/en-us/content/topics/access-gateway/command-line-console-reference-service.htm#Access) to apply your changes. > **Note:** Perform these steps on your admin node and any server nodes where you want the authentication service to run. From 4f13d2457fc4f875017bec7aabb4b28204b5158b Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Tue, 3 Mar 2026 11:11:55 -0500 Subject: [PATCH 6/6] SME feedback --- .../vuepress-site/docs/guides/oag-offline-mode/main/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md index 7922f35481d..dcca04d00b5 100644 --- a/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/oag-offline-mode/main/index.md @@ -10,7 +10,7 @@ layout: Guides This guide explains how to configure Temporary Offline Access (offline mode) for Access Gateway using Access Gateway APIs. Offline mode allows users to authenticate locally through Access Gateway and continue accessing protected on-premises apps, even when Access Gateway is unable to reach Okta. -> **Note:** The Access Gateway APIs that are used for offline mode configuration are in Early Access (EA). +> **Note:** The Access Gateway APIs that are used for offline mode configuration are in Limited Early Access (LEA). --- @@ -72,7 +72,7 @@ After the package is installed, enable the offline mode feature in your Access G 1. Open the `/opt/oag/data/gui/specs/icsgw_spgw_features.json` file with `sudo` privileges using your text editor. For example, if you use the vi editor, use this command: `sudo vi /opt/oag/data/gui/specs/icsgw_spgw_features.json`. 1. Search for `offlinemode`. 1. Change `"show": false` to `"show": true`. -1. Save the file. The `"show": false` field is read-only. When you save the file, ensure that you override the read-only attribute to save it. For example, when using vi, use this command: `:w!`. +1. Save the file. The file is read-only which means that when you save it, ensure that you override the read-only permission. For example, when using vi, use this command: `:w!`. 1. [Restart the Access Gateway Admin service](https://help.okta.com/oag/en-us/content/topics/access-gateway/command-line-console-reference-service.htm#Access) to apply your changes. > **Note:** Perform these steps on your admin node and any server nodes where you want the authentication service to run.