okta · thomascavanagh-okta · Jun 12, 2026 · Jun 14, 2026 · Jun 14, 2026 · Jun 17, 2026
@@ -205,6 +205,7 @@ guides:
  - set-up-oauth-api
  - custom-smtp
  - oag-offline-mode
+ - oag-configure-apps-offline-mode
  - configure-identity-claims-sourcing-policy
 ---
 

@@ -0,0 +1,9 @@
+---
+title: Add an app for Access Gateway offline mode
+meta:
+  - name: description
+    content: Learn how to create a SAML or OIDC app for use with Access Gateway offline mode.
+layout: Guides
+sections:
+ - main
+---
@@ -0,0 +1,53 @@
+---
+title: Add an app for Access Gateway offline mode
+meta:
+  - name: description
+    content: Learn how to create a SAML or OIDC app for use with Access Gateway offline mode.
+layout: Guides
+---
+
+<ApiLifecycle access="ea" />
+
+This guide explains how to create an app for use with Access Gateway offline mode.
+
+> **Note:** The Access Gateway APIs used in this guide are available in a Limited Early Access program and may be updated or changed based on feedback.
+
+---
+
+#### Learning outcomes
+
+<StackSnippet snippet="learningoutcomes" />
+
+#### What you need
+
+* Offline mode configured for Access Gateway. See [Configure offline mode for Access Gateway](/docs/guides/oag-offline-mode/main/).
+* An identity provider (IdP) in your Access Gateway instance with failover mode set to `AUTOMATIC`.
+* <StackSnippet snippet="wun" />
+
+---
+
+## Learn about offline mode apps
+
+By default, apps behind Access Gateway require a connection to Okta to authenticate users. If Okta is unreachable, authentication fails and users can't access the app.
+
+Offline mode apps are configured with a local directory as a fallback authentication source. When Access Gateway detects that Okta is unavailable, it switches to offline mode and authenticates users against the local directory instead. From the user's perspective, the sign-in flow looks the same regardless of whether Okta is reachable.
+
+Offline mode apps require the authentication service and directory sync to be configured before you create the app. See [Configure offline mode for Access Gateway](/docs/guides/oag-offline-mode/main/).
+
+## Overview
+
+<StackSnippet snippet="overview" />
+
+## What to know before creating the app
+
+<StackSnippet snippet="requirements" />
+
+## Create the app
+
+<StackSnippet snippet="procedure" />
+
+## See also
+
+* [Configure offline mode for Access Gateway](/docs/guides/oag-offline-mode/main/)
+* [Access Gateway API documentation](https://developer.okta.com/docs/api/openapi/oag/guides/overview)
+* [Okta Access Gateway documentation](https://help.okta.com/okta_help.htm?type=oag&id=ext_oag_main)
@@ -0,0 +1 @@
+OIDC
@@ -0,0 +1,2 @@
+* Create an OpenID Connect (OIDC) app in Access Gateway using the Access Gateway API
+* Configure your client app using the Access Gateway OIDC discovery document
@@ -0,0 +1,10 @@
+When the connection to Okta is unavailable, users can still sign in through Access Gateway and access OIDC apps. Access Gateway uses an embedded OIDC provider to issue tokens and falls back to local directory authentication when Okta is unreachable.
+
+OIDC tokens issued by Access Gateway have the `iss` claim set to the Access Gateway authorization server domain, not your Okta tenant domain. Configure your client app to expect tokens from Access Gateway. For an overview of OIDC, see [OAuth 2.0 and OpenID Connect overview](/docs/concepts/oauth-openid/).
+
+This is the typical flow to configure an OIDC app in Access Gateway:
+
+1. Create the app, specifying the app type, redirect URIs, and client credentials. See [Create the app](#create-the-app).
+1. Configure your client app to use Access Gateway as the OIDC provider. Retrieve the discovery document from Access Gateway to get the endpoint URLs that your client needs. See [Configure your client app](#configure-your-client-app).
+
+OIDC apps in Access Gateway can only be created and configured using the Access Gateway API. You can view OIDC apps in the Access Gateway UI console, but you can't add or edit them there.
@@ -0,0 +1,150 @@
+In this example, create a web app that supports the authorization code with PKCE flow and refresh tokens.
+
+Before you begin, have your `clientId` and `clientSecret` ready. You define these values when you set up your OIDC client app. Access Gateway doesn't generate them. Store the `clientSecret` securely before you make the request.
+
+1. Create the OIDC app in Access Gateway by sending a `POST` request to the Create an application [endpoint](https://developer.okta.com/docs/api/openapi/oag/oag/tags/applications/other/createapplication). Use the following [request example](#request-example) as a template.
+1. In the request body, set the following values for your app:
+    1. Set `label` as the display name for the app.
+    1. Set `clientId` as a unique identifier for your client app.
+    1. Set `clientSecret` to the value you defined before making this request.
+    1. Set `redirectUris` as your client app's callback URL.
+    1. For `allowedScopes`, include any combination of `openid`, `profile`, `email`, and `offline_access`. This determines which scopes the app can request.
+    1. For `accessTokenLifetime` and `refreshTokenLifetime`, set the desired values in seconds. These determine how long tokens issued for this app are valid.
+    [[style="list-style-type:lower-alpha"]]
+1. Send the POST request.
+
+### Request example
+
+```bash
+curl -i -X POST \
+  'https://{oaghostname}/api/v2/apps' \
+  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "type": "OAG_OIDC",
+    "label": "Test OIDC App - Auth Code",
+    "description": "OIDC application using authorization code flow with PKCE",
+    "applicationType": "web",
+    "clientId": "<client-id>",
+    "clientSecret": "<client-secret>",
+    "redirectUris": [
+      "https://example.com/callback"
+    ],
+    "responseTypes": [
+      "code"
+    ],
+    "grantTypes": [
+      "authorization_code",
+      "refresh_token"
+    ],
+    "tokenEndpointAuthMethod": "client_secret_post",
+    "pkceRequired": true,
+    "allowedScopes": [
+      "openid",
+      "profile",
+      "email",
+      "offline_access"
+    ],
+    "accessTokenLifetime": 3600,
+    "refreshTokenLifetime": 86400
+  }'
+```
+
+### Response example
+
+```json
+{
+  "id": "app-oidc-123",
+  "type": "OAG_OIDC",
+  "label": "Test OIDC App - Auth Code",
+  "description": "OIDC application using authorization code flow with PKCE",
+  "applicationType": "web",
+  "status": "ACTIVE",
+  "clientId": "<client-id>",
+  "redirectUris": [
+    "https://example.com/callback"
+  ],
+  "responseTypes": [
+    "code"
+  ],
+  "grantTypes": [
+    "authorization_code",
+    "refresh_token"
+  ],
+  "tokenEndpointAuthMethod": "client_secret_post",
+  "pkceRequired": true,
+  "allowedScopes": [
+    "openid",
+    "profile",
+    "email",
+    "offline_access"
+  ],
+  "accessTokenLifetime": 3600,
+  "refreshTokenLifetime": 86400,
+  "deviceFlowEnabled": false,
+  "clientCredentialsEnabled": false,
+  "_embedded": {
+    "session": {
+      "maxIdleTimeMinutes": 60
+    },
+    "behavior": {
+      "reAuthenticateOnAccessDenied": false
+    },
+    "healthCheck": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## Configure your client app
+
+After you create the app in Access Gateway, configure your client to use Access Gateway as its OIDC provider.
+
+Your client app must be pointed at Access Gateway, not your Okta tenant, for authentication to work. Use the OIDC discovery document to configure your client's OIDC settings. It's a JSON file that's served at `/.well-known/openid-configuration` on your Access Gateway authorization server. It contains all the endpoint URLs that your client needs.
+
+1. Retrieve your `idpId` by using the List all IdPs [endpoint](https://developer.okta.com/docs/api/openapi/oag/oag/tags/idps/other/listidps). Select the IdP that has failover mode set to `AUTOMATIC`.
+1. Use the Retrieve the OpenID Connect discovery document [endpoint](https://developer.okta.com/docs/api/openapi/oag/oag/tags/oidc/other/getopenidconnectdiscovery) with your `idpId` as the path parameter.
+1. In the response from the discovery document endpoint, note the endpoint URLs that are returned. See the following [response example](#oidc-discovery-document-response-example).
+1. Use the endpoint URLs to configure your client's OIDC settings. The document includes the following endpoints:
+    1. `authorization_endpoint`: Where the client sends the user to sign in
+    1. `token_endpoint`: Where the client exchanges an authorization code for tokens
+    1. `userinfo_endpoint`: Where the client retrieves claims about the signed-in user
+    1. `introspection_endpoint`: Where the client checks whether a token is still valid
+    1. `revocation_endpoint`: Where the client invalidates a token on sign-out
+    [[style="list-style-type:lower-alpha"]]
+1. Set your client's issuer to the `issuer` value from the discovery document. Your client uses this value to validate the `iss` claim in tokens it receives.
+
+> **Note:** Access Gateway sets the `iss` claim to its own authorization server domain, not your Okta tenant domain. If your client is configured to validate tokens from Okta, update the issuer to the Access Gateway domain.
+
+### OIDC discovery document response example
+
+```json
+{
+  "issuer": "https://oag.example.com/realms/{idpId}",
+  "authorization_endpoint": "https://oag.example.com/realms/{idpId}/protocol/openid-connect/auth",
+  "token_endpoint": "https://oag.example.com/realms/{idpId}/protocol/openid-connect/token",
+  "userinfo_endpoint": "https://oag.example.com/realms/{idpId}/protocol/openid-connect/userinfo",
+  "jwks_uri": "https://oag.example.com/realms/{idpId}/protocol/openid-connect/certs",
+  "introspection_endpoint": "https://oag.example.com/realms/{idpId}/protocol/openid-connect/token/introspect",
+  "revocation_endpoint": "https://oag.example.com/realms/{idpId}/protocol/openid-connect/revoke",
+  "scopes_supported": [
+    "openid",
+    "profile",
+    "email",
+    "offline_access"
+  ],
+  "response_types_supported": [
+    "code"
+  ],
+  "grant_types_supported": [
+    "authorization_code",
+    "refresh_token",
+    "client_credentials"
+  ],
+  "token_endpoint_auth_methods_supported": [
+    "client_secret_post",
+    "client_secret_basic"
+  ]
+}
+```
@@ -0,0 +1,41 @@
+Before you create the app, ensure that you have the following information:
+
+* The redirect URI for your client app.
+* The `applicationType` for your client app (`web`, `native`, or `spa`). This determines which OAuth 2.0 flows are supported and whether a client secret is required.
+
+Review the following sections to understand the requirements for your app and how to configure the app settings in Access Gateway when you create it.
+
+### Scopes and claims
+
+Access Gateway supports the `openid`, `profile`, `email`, and `offline_access` scopes. Include `offline_access` in `allowedScopes` when you create the app to enable refresh tokens.
+
+The following claims are included in tokens based on the granted scopes:
+
+| Claim | Scope | Description |
+| --- | --- | --- |
+| `sub` | `openid` | Subject identifier |
+| `name` | `profile` | Full name of the user |
+| `email` | `email` | Email address of the user |
+
+Include the `offline_access` scope in `allowedScopes` to enable refresh tokens. Without this scope, Access Gateway doesn't issue a refresh token. When a mode transition occurs, existing refresh tokens are invalidated and users must re-authenticate.
+
+### Token lifetimes and behavior
+
+You can configure access token and refresh token lifetimes per app using `accessTokenLifetime` and `refreshTokenLifetime` in the request body when you create the app. If you omit these fields, the following default settings apply:
+
+| Token | Default lifetime |
+| --- | --- |
+| Access token | 15 minutes |
+| Refresh token | 7 days |
+
+Also note that refresh tokens are mode-specific. A refresh token that's issued in online mode can't be used after Access Gateway switches to offline mode. When a mode transition occurs, users must re-authenticate.
+
+### Types of OIDC apps
+
+You can create three different types of OIDC apps. The `applicationType` determines which OAuth 2.0 flows are supported and whether a client secret is required.
+
+| App type | Supported flows | Client secret |
+| --- | --- | --- |
+| `web` (server-side web apps) | Authorization Code + PKCE, client credentials, refresh token | Required |
+| `native` (mobile or desktop apps) | Authorization Code + PKCE, refresh token; device grant optional | Optional |
+| `spa` (single-page apps) | Authorization Code + PKCE only | Not used |
@@ -0,0 +1 @@
+An OIDC client app and its redirect URI
@@ -0,0 +1 @@
+SAML
@@ -0,0 +1,2 @@
+* Create a SAML app in Access Gateway using the Access Gateway API
+* Configure your Service Provider (SP) using the IdP metadata returned by Access Gateway
@@ -0,0 +1,9 @@
+When the connection to Okta is unavailable, users can still sign in through Access Gateway and access SAML apps. Access Gateway uses the authentication service to authenticate users against your offline directory and issues a SAML assertion to the SP. For background on SAML, see [Understanding SAML](/docs/concepts/saml/).
+
+Configuring a SAML app involves establishing a mutual trust between Access Gateway, which acts as the IdP, and your client app, which acts as the SP. This is the typical flow when you configure a SAML app in Access Gateway:
+
+1. You provide the SP's entity ID and certificate to Access Gateway when you create the app. See [Create the app](#create-the-app).
+1. You define attributes to specify what user data Access Gateway includes in the SAML assertion it sends to the SP. See [Create attributes and configure the client app](#create-attributes-and-configure-the-client-app).
+1. Access Gateway returns its own IdP metadata for you to configure in the SP. See [Configure your client app with Access Gateway IdP metadata](#configure-your-client-app-with-access-gateway-idp-metadata).
+
+SAML apps in Access Gateway can only be created and configured using the Access Gateway API. You can view SAML apps in the Access Gateway UI console, but you can't add or edit them there.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		* Create an OpenID Connect (OIDC) app in Access Gateway using the Access Gateway API
		* Configure your client app using the Access Gateway OIDC discovery document
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		* Create a SAML app in Access Gateway using the Access Gateway API
		* Configure your Service Provider (SP) using the IdP metadata returned by Access Gateway