Skip to content

Commit fc11b6f

Browse files
thomascavanagh-oktathomascavanagh-okta
authored
Merge pull request #6231 from okta/tc-okta-1166344-oag-offline-app-guide
[OKTA-1166344] OIDC and SAML guides
2 parents 2517a56 + 7cd3302 commit fc11b6f

17 files changed

Lines changed: 469 additions & 18 deletions

File tree

‎packages/@okta/vuepress-site/docs/guides/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,7 @@ guides:
220220
- set-up-oauth-api
221221
- custom-smtp
222222
- oag-offline-mode
223+
- oag-configure-apps-offline-mode
223224
- configure-identity-claims-sourcing-policy
224225
---
225226

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Add an app for Access Gateway offline mode
3+
meta:
4+
- name: description
5+
content: Learn how to create a SAML or OIDC app for use with Access Gateway offline mode.
6+
layout: Guides
7+
sections:
8+
- main
9+
---

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/main/index.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Add an app for Access Gateway offline mode
3+
meta:
4+
- name: description
5+
content: Learn how to create a SAML or OIDC app for use with Access Gateway offline mode.
6+
layout: Guides
7+
---
8+
9+
<ApiLifecycle access="ea" />
10+
11+
This guide explains how to create an app for use with Access Gateway offline mode.
12+
13+
> **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.
14+
15+
---
16+
17+
#### Learning outcomes
18+
19+
<StackSnippet snippet="learningoutcomes" />
20+
21+
#### What you need
22+
23+
* Offline mode configured for Access Gateway. See [Configure offline mode for Access Gateway](/docs/guides/oag-offline-mode/main/).
24+
* An identity provider (IdP) in your Access Gateway instance with failover mode set to `AUTOMATIC`.
25+
* <StackSnippet snippet="wun" />
26+
27+
---
28+
29+
## Learn about offline mode apps
30+
31+
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.
32+
33+
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.
34+
35+
Offline mode apps require you to configure the authentication service and directory sync before you create the app. See [Configure offline mode for Access Gateway](/docs/guides/oag-offline-mode/main/).
36+
37+
## Overview
38+
39+
<StackSnippet snippet="overview" />
40+
41+
## What to know before creating the app
42+
43+
<StackSnippet snippet="requirements" />
44+
45+
## Create the app
46+
47+
<StackSnippet snippet="procedure" />
48+
49+
## See also
50+
51+
* [Configure offline mode for Access Gateway](/docs/guides/oag-offline-mode/main/)
52+
* [Access Gateway API documentation](https://developer.okta.com/docs/api/openapi/oag/guides/overview)
53+
* [Okta Access Gateway documentation](https://help.okta.com/okta_help.htm?type=oag&id=ext_oag_main)

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/main/openidconnect/apptype.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
OIDC

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/main/openidconnect/learningoutcomes.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
* Create an OpenID Connect (OIDC) app in Access Gateway using the Access Gateway API
2+
* Configure your client app using the Access Gateway OIDC discovery document

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/main/openidconnect/overview.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
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.
2+
3+
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/).
4+
5+
This is the typical flow to configure an OIDC app in Access Gateway:
6+
7+
1. Retrieve your IdP's `idpId`, then create the app, specifying the app type and redirect URIs. See [Create the app](#create-the-app).
8+
1. Retrieve the client secret that Access Gateway generated for your app. See [Retrieve the client secret](#retrieve-the-client-secret).
9+
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).
10+
11+
You can only create and configure OIDC apps in Access Gateway 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.

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/main/openidconnect/procedure.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
In this example, create a web app that supports the authorization code with PKCE flow and refresh tokens.
2+
3+
Access Gateway generates the `clientId` and `clientSecret` for your app. You don't set these values yourself. Retrieve them after you create the app. See [Retrieve the client secret](#retrieve-the-client-secret).
4+
5+
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`. You need this value to create the app.
6+
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.
7+
1. In the request body, set the following values for your app:
8+
1. Set `label` as the display name for the app.
9+
1. Set `idpId` to the value that you retrieved in the first step.
10+
1. In the `oidc` object, set `applicationType` to `web`, `native`, or `spa`.
11+
1. In the `oidc` object, set `redirectUris` as your client app's callback URL.
12+
1. In the `oidc` object, for `allowedScopes`, include any combination of `openid`, `profile`, `email`, and `offline_access`. This determines which scopes the app can request.
13+
1. In the `oidc` object, for `accessTokenLifetime` and `refreshTokenLifetime`, set the desired values in seconds. These determine how long tokens issued for this app are valid.
14+
[[style="list-style-type:lower-alpha"]]
15+
1. Send the POST request.
16+
17+
### Request example
18+
19+
```bash
20+
curl -i -X POST \
21+
'https://{oaghostname}/api/v2/apps' \
22+
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
23+
-H 'Content-Type: application/json' \
24+
-d '{
25+
"type": "OAG_OIDC",
26+
"label": "Test OIDC App - Auth Code",
27+
"description": "OIDC app using authorization code flow with PKCE",
28+
"idpId": "<idp-id>",
29+
"oidc": {
30+
"applicationType": "web",
31+
"redirectUris": [
32+
"https://example.com/callback"
33+
],
34+
"responseTypes": [
35+
"code"
36+
],
37+
"grantTypes": [
38+
"authorization_code",
39+
"refresh_token"
40+
],
41+
"tokenEndpointAuthMethod": "client_secret",
42+
"pkceRequired": true,
43+
"allowedScopes": [
44+
"openid",
45+
"profile",
46+
"email",
47+
"offline_access"
48+
],
49+
"accessTokenLifetime": 3600,
50+
"refreshTokenLifetime": 86400
51+
}
52+
}'
53+
```
54+
55+
### Response example
56+
57+
```json
58+
{
59+
"id": "app-oidc-123",
60+
"type": "OAG_OIDC",
61+
"label": "Test OIDC App - Auth Code",
62+
"description": "OIDC app using authorization code flow with PKCE",
63+
"status": "ACTIVE",
64+
"idpId": "<idp-id>",
65+
"oidc": {
66+
"applicationType": "web",
67+
"clientId": "<generated-client-id>",
68+
"redirectUris": [
69+
"https://example.com/callback"
70+
],
71+
"responseTypes": [
72+
"code"
73+
],
74+
"grantTypes": [
75+
"authorization_code",
76+
"refresh_token"
77+
],
78+
"tokenEndpointAuthMethod": "client_secret",
79+
"pkceRequired": true,
80+
"allowedScopes": [
81+
"openid",
82+
"profile",
83+
"email",
84+
"offline_access"
85+
],
86+
"accessTokenLifetime": 3600,
87+
"refreshTokenLifetime": 86400,
88+
"clientCredentialsEnabled": false
89+
},
90+
"_embedded": {
91+
"behavior": {
92+
"singleLogout": false,
93+
"universalLogout": false,
94+
"globalTokenRevocation": false
95+
}
96+
}
97+
}
98+
```
99+
100+
Note the `clientId` in the response. You need it, along with the app's `id`, to retrieve the client secret in the next step.
101+
102+
## Retrieve the client secret
103+
104+
Access Gateway generates the `clientSecret` for your app when you create it, but doesn't return it in the create response. Retrieve it separately, then store it securely. Your client app needs both `clientId` and `clientSecret` to authenticate.
105+
106+
1. Send a `GET` request to the Retrieve the client secret [endpoint](https://developer.okta.com/docs/api/openapi/oag/oag/tags/applications/other/getclientsecret), using the app's `id` as the path parameter.
107+
1. Store the returned `clientSecret` securely. You can't retrieve the same secret value again after you rotate it.
108+
109+
> **Note:** If you need to invalidate the current secret, for example, after a suspected compromise, generate a new one using the Generate a client secret [endpoint](https://developer.okta.com/docs/api/openapi/oag/oag/tags/applications/other/generateclientsecret). This immediately invalidates the previous secret.
110+
111+
### Client secret request example
112+
113+
```bash
114+
curl -i -X GET \
115+
'https://{oaghostname}/api/v2/apps/{applicationId}/credentials/secret' \
116+
-H 'Authorization: Bearer <YOUR_JWT_HERE>'
117+
```
118+
119+
### Client secret response example
120+
121+
```json
122+
{
123+
"clientSecret": "<generated-client-secret>"
124+
}
125+
```
126+
127+
## Configure your client app
128+
129+
After you create the app in Access Gateway and retrieve its client secret, configure your client to use Access Gateway as its OIDC provider.
130+
131+
You must point your client app 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.
132+
133+
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.
134+
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).
135+
1. Use the endpoint URLs to configure your client's OIDC settings. The document includes the following endpoints:
136+
1. `authorization_endpoint`: Where the client sends the user to sign in
137+
1. `token_endpoint`: Where the client exchanges an authorization code for tokens
138+
1. `userinfo_endpoint`: Where the client retrieves claims about the signed-in user
139+
1. `jwks_uri`: Where the client retrieves Access Gateway's public keys to validate token signatures
140+
1. `introspection_endpoint`: Where the client checks whether a token is still valid
141+
1. `revocation_endpoint`: Where the client invalidates a token when the user signs out
142+
[[style="list-style-type:lower-alpha"]]
143+
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 that it receives.
144+
145+
> **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.
146+
147+
### OIDC discovery document response example
148+
149+
```json
150+
{
151+
"issuer": "https://oag.example.com/realms/3f63f461-c7fc-483b-b2ae-961633d251ac",
152+
"authorization_endpoint": "https://oag.example.com/realms/3f63f461-c7fc-483b-b2ae-961633d251ac/protocol/openid-connect/auth",
153+
"token_endpoint": "https://oag.example.com/realms/3f63f461-c7fc-483b-b2ae-961633d251ac/protocol/openid-connect/token",
154+
"userinfo_endpoint": "https://oag.example.com/realms/3f63f461-c7fc-483b-b2ae-961633d251ac/protocol/openid-connect/userinfo",
155+
"jwks_uri": "https://oag.example.com/realms/3f63f461-c7fc-483b-b2ae-961633d251ac/protocol/openid-connect/certs",
156+
"introspection_endpoint": "https://oag.example.com/realms/3f63f461-c7fc-483b-b2ae-961633d251ac/protocol/openid-connect/token/introspect",
157+
"revocation_endpoint": "https://oag.example.com/realms/3f63f461-c7fc-483b-b2ae-961633d251ac/protocol/openid-connect/revoke",
158+
"scopes_supported": [
159+
"openid",
160+
"profile",
161+
"email",
162+
"offline_access"
163+
],
164+
"response_types_supported": [
165+
"code"
166+
],
167+
"grant_types_supported": [
168+
"authorization_code",
169+
"refresh_token",
170+
"client_credentials"
171+
],
172+
"token_endpoint_auth_methods_supported": [
173+
"client_secret"
174+
]
175+
}
176+
```

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/main/openidconnect/requirements.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
Before you create the app, ensure that you have the following information:
2+
3+
* The redirect URI for your client app.
4+
* The redirect URI is required if your app uses the authorization code flow.
5+
* It's not required for apps that only use the client credentials flow.
6+
* 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.
7+
8+
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.
9+
10+
### Scopes and claims
11+
12+
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.
13+
14+
The following claims are included in tokens based on the granted scopes:
15+
16+
| Claim | Scope | Description |
17+
| --- | --- | --- |
18+
| `sub` | `openid` | Subject identifier |
19+
| `name` | `profile` | Full name of the user |
20+
| `email` | `email` | Email address of the user |
21+
22+
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.
23+
24+
### Token lifetimes and behavior
25+
26+
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:
27+
28+
| Token | Default lifetime |
29+
| --- | --- |
30+
| Access token | 1 hour |
31+
| Refresh token | 1 day |
32+
33+
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.
34+
35+
### Types of OIDC apps
36+
37+
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.
38+
39+
| App type | Supported flows | Client secret |
40+
| --- | --- | --- |
41+
| `web` (server-side web apps) | Authorization Code + PKCE, client credentials, refresh token | Required |
42+
| `native` (mobile or desktop apps) | Authorization Code + PKCE, refresh token | Optional |
43+
| `spa` (single-page apps) | Authorization Code + PKCE only | Not used |

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/main/openidconnect/wun.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
An OIDC client app and its redirect URI

‎packages/@okta/vuepress-site/docs/guides/oag-configure-apps-offline-mode/main/saml2/apptype.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
SAML

0 commit comments

Comments
 (0)