[v13] Okta documentation.

docs/config.json

@@ -958,6 +958,24 @@
             }
           ]
         },
+        {
+          "title": "Protect Okta Applications and Groups with Teleport",
+          "slug": "/application-access/okta/",
+          "entries": [
+            {
+              "title": "Guide",
+              "slug": "/application-access/okta/guide/"
+            },
+            {
+              "title": "Architecture",
+              "slug": "/application-access/okta/architecture/"
+            },
+            {
+              "title": "Reference",
+              "slug": "/application-access/okta/reference/"
+            }
+          ]
+        },
         {
           "title": "Access Controls",
           "slug": "/application-access/controls/"

docs/cspell.json

@@ -163,6 +163,7 @@
     "SLAVEOF",
     "SLOWLOG",
     "SSUBSCRIBE",
+    "SSWS",
     "SUNSUBSCRIBE",
     "Shockbyte",
     "Slackbot",

docs/pages/application-access/okta.mdx

@@ -0,0 +1,9 @@
+---
+title: Okta Integration with Application Access
+description: Guides for using Teleport Okta integration.
+layout: tocless-doc
+---
+
+- [Guide](./okta/guide.mdx): A guide for setting up a simple Okta service in Teleport.
+- [Architecture](./okta/architecture.mdx): The architecture of the Okta service.
+- [Reference](./okta/reference.mdx): A reference for the Okta service.

docs/pages/application-access/okta/architecture.mdx

@@ -0,0 +1,74 @@
+---
+title: Architecture of the Okta Service
+description: An overview of the architecture of the Okta Service.
+---
+
+This document will go into details on how the Okta Service is organized and how
+it functions.
+
+## How does the Okta integration work?
+
+Teleport provides an Okta Service that is responsible for dealing with all
+interactions with Okta. There are three main components of the Okta Service:
+
+- Synchronization
+- User access
+- Access Requests
+
+![Okta architecture](../../../img/application-access/okta/okta-architecture.png)
+
+{/*
+Uncomment this once mermaid support is in.
+```mermaid
+flowchart TB
+  Okta[Okta API]
+
+  subgraph Svc[Okta Service]
+    direction TB
+    UA[User Access]
+    Sync[Synchronization]
+    AR[Access Requests]
+  end
+
+  Teleport[Teleport Cluster]<-- Reverse Tunnel -->Svc
+
+  Okta-- Import applications and groups-->Sync
+  UA-- Longer lived permissions-->Okta
+  AR-- Short lived permissions-->Okta
+```
+*/}
+
+The Okta Service uses an Okta API token and endpoint in order to interact
+with Okta's API. The API is used to import applications and user groups and
+manage assignments.
+
+### Synchronization
+
+The synchronization process runs periodically in the Okta Service, occurring every
+2 minutes. This service will import both Okta applications and user groups into
+Teleport, cleaning up any resources that no longer exist in Okta.
+
+#### Okta Import Rules
+
+During synchronization, labels can be customized for imported applications and user
+groups through the use of Okta Import Rules. These objects can be created by
+administrators of the Teleport cluster and they will be automatically picked up
+during the next synchronization run.
+
+(!docs/pages/includes/okta-import-rule.mdx!)
+
+### User access
+
+Upon logging into Teleport, users will be granted access to the Okta applications
+and user groups that they have access to within Teleport. If a user has RBAC access to
+an application or user group, it will be reflected within Okta.
+
+### Access Requests
+
+Users can use Teleport's Just-in-time Access Requests in order to
+request temporary access to Okta applications and user groups. Upon expiration of the
+access request, the access granted will be revoked within Okta.
+
+## Guide
+
+A guide for setting up a simple Okta Service can be found [here](./guide.mdx).

docs/pages/application-access/okta/guide.mdx

@@ -0,0 +1,185 @@
+---
+title: Setting up the Okta Service
+description: How to set up the Okta Service with some basic configurations
+---
+
+Teleport can import and grant access to Okta applications and user groups. Okta applications
+can be accessed through Teleport's application access UI, and access to these applications along
+with user groups can be managed by Teleport's RBAC along with access requests.
+
+This guide will help you set up the Okta Service and provide some basic
+configurations to enable it.
+
+## Prerequisites
+
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+- (!docs/pages/includes/tctl.mdx!)
+
+- An Okta organization with an [Okta API token](https://developer.okta.com/docs/guides/create-an-api-token) provisioned.
+- A running Teleport cluster with Okta login configured.
+- An instance where you will run the Okta Service. This can live anywhere
+  with outbound access to Okta and must be running Linux.
+
+## Step 1/3. Create Okta import rules
+
+Before setting up the Okta Service, you should create Okta import rules in order
+to ensure that our Okta applications are set up with appropriate labeling before
+you attempt to synchronize them. First, you'll need to get the group and application
+IDs from Okta. The easiest way to do this is to use the <Var name="okta-api-token" />
+provisioned earlier.
+
+To get group IDs:
+
+```
+$ curl -H "Authorization: SSWS <Var name="okta-api-token" />" <Var name="okta-endpoint-url" />/api/v1/groups | jq '[.[] |  {"id": .id, "label": .profile.name}]'
+...
+[
+  {
+    "id": "111111",
+    "label": "Developers"
+  },
+  {
+    "id": "222222",
+    "label": "Admins"
+  },
+  {
+    "id": "333333",
+    "label": "Everyone"
+  },
+  {
+    "id": "444444",
+    "label": "HR"
+  },
+  ...
+]
+```
+
+```
+$ curl -H "Authorization: SSWS <Var name="okta-api-token" />" <Var name="okta-endpoint-url" />/api/v1/apps | jq '[.[] |  {"id": .id, "label": .label}]'
+...
+[
+  {
+    "id": "111111",
+    "label": "Okta Admin Console"
+  },
+  {
+    "id": "222222",
+    "label": "Okta Browser Plugin"
+  },
+  {
+    "id": "333333",
+    "label": "Okta Dashboard"
+  },
+  {
+    "id": "444444",
+    "label": "SAML test"
+  },
+  ...
+]
+```
+
+From here, you can copy the IDs from the output of the `curl` commands and use
+these to create the Okta import rule. Put this in a file called `okta-import-rule.yaml`:
+
+```yaml
+kind: okta_import_rule
+version: v1
+metadata:
+  name: import-rule
+  description: "Okta import rule for all groups and applications"
+spec:
+  mappings:
+  - match:
+    - app_ids: ["111111", "222222", "333333"] # Replace these with your Okta application IDs.
+    add_labels:
+      app_label: app-label-value
+  - match:
+    - group_ids: ["111111", "222222", "333333"] # Replace these with your Okta group IDs.
+    add_labels:
+      group_label: group-label-value
+```
+
+This will ensure that the applications and groups, once synchronized to Teleport,
+will be given the specified labels.
+
+## Step 2/3. Set up the Okta Service
+
+In this step, you'll set up the Okta Service. The Okta Service will interact with Okta's
+API to import applications and groups, as well as update memberships to those applications
+and groups. The Okta Service connects back to the Teleport cluster over a reverse tunnel.
+
+### Get a join token
+
+Establish trust between your Teleport cluster and the new Okta Service
+instance by creating a join token:
+
+```code
+$ tctl tokens add --type=okta --ttl=1h --format=text
+(=presets.tokens.first=)
+```
+
+On the host where you will install the Teleport Okta Service, create a
+file called `/tmp/token` that consists only of your token:
+
+```code
+$ echo <Var name="join-token" /> | sudo tee /tmp/token
+```
+
+### Configure the Okta Service
+
+First, on the host where you will run the Okta Service , create a file at
+<Var name="okta-api-token-path" /> with the contents of the API token.
+
+Next, on the same host, create a file at `/etc/teleport.yaml` with the
+following content:
+
+```yaml
+version: v3
+teleport:
+  join_params:
+    token_name: "/tmp/token"
+    method: token
+  proxy_server: "teleport.example.com:443"
+auth_service:
+  enabled: no
+proxy_service:
+  enabled: no
+ssh_service:
+  enabled: no
+okta_service:
+  enabled: yes
+  api_endpoint: <Var name="okta-endpoint-url" />
+  api_token_path: <Var name="okta-api-token-path" />
+```
+
+Edit `/etc/teleport.yaml` to replace `teleport.example.com:443` with the host
+and port of your Teleport Proxy Service or Teleport Cloud tenant, e.g.,
+`mytenant.teleport.sh:443`.
+
+### Run the Teleport Application Service
+
+(!docs/pages/includes/start-teleport.mdx service="the Teleport Application Service"!)
+
+## Step 3/3. Connect to the Teleport web UI
+
+Navigate to the application access page within the Teleport web UI to see the list of
+of synchronized Okta applications. If you're unable to see the applications, please refer
+to the application [Access Controls](../controls.mdx) and update your roles to match the
+labels given to your applications by the above specified Okta import rules.
+
+You can also try Access Requests by navigating to the Access Requests page and creating
+a new Access Request. From here, you can navigate to applications and see the Okta
+applications in the request list:
+
+![Requesting Okta applications](../../../img/application-access/okta/okta-application-access-request.png)
+
+Or you can navigate to user groups and see the user groups in the request list:
+
+![Requesting Okta groups](../../../img/application-access/okta/okta-user-group-access-request.png)
+
+## Next steps
+
+- Learn more about [accessing APIs](../guides/api-access.mdx) with the Teleport
+  Application Service.
+- Take a look at application-related [Access Controls](../controls.mdx).