diff --git a/packages/@okta/vuepress-site/docs/guides/index.md b/packages/@okta/vuepress-site/docs/guides/index.md index cc0d089974b..f8aced909e5 100644 --- a/packages/@okta/vuepress-site/docs/guides/index.md +++ b/packages/@okta/vuepress-site/docs/guides/index.md @@ -72,6 +72,7 @@ guides: - submit-app - submit-app-prereq - submit-oin-app + - update-oin-app - add-private-app - deployment-checklist - deploy-your-app diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/index.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/index.md new file mode 100644 index 00000000000..4efa88cbfbe --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/index.md @@ -0,0 +1,9 @@ +--- +title: Update a published integration with the OIN Wizard +meta: + - name: description + content: Learn how to update your published integration in the Okta Integration Network (OIN). The update and submit tasks are performed in the Okta Admin Console through the OIN Wizard. +layout: Guides +sections: + - main +--- diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/index.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/index.md new file mode 100644 index 00000000000..89f15f040fd --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/index.md @@ -0,0 +1,159 @@ +--- +title: Update a published integration with the OIN Wizard +meta: + - name: description + content: Learn how to update your published integration in the Okta Integration Network (OIN). You can make updates and resubmit your integration in the OIN Wizard. The OIN team reviews your submission and updates the OIN catalog after your integration has been verified. +layout: Guides +--- + +Learn how to update an OIDC, SAML 2.0, or SCIM 2.0 published integration in the Okta Integration Network (OIN) using the OIN Wizard. + +--- + +#### What you need + +* A published OIDC, SAML 2.0, or SCIM integration in the OIN that was [submitted using the OIN Wizard](/docs/guides/submit-oin-app/). +* The [Okta Developer Edition org](https://developer.okta.com/signup/) from where you originally submitted your published integration. The OIN Wizard is only available in Okta Developer Edition orgs. +* An admin user in the Okta Developer Edition org with either the super admin or the app and org admin roles + +--- + +## Overview + +If you have a published Single Sign-On (SSO) or lifecycle management integration in the OIN catalog, you can update and resubmit it with the OIN Wizard. + +The OIN Wizard currently supports updates for integrations that use the following protocols: + +* OIDC +* SAML 2.0 +* SCIM 2.0 + +When you edit a published OIN integration, test the flows for the updated version and the published version for backwards compatibility. Testing the published version for backwards compatibility ensures that your integration still works for users who have already installed it. See [Update integration considerations](#update-integration-considerations) before you edit your published integration. After you successfully test the updated and published versions of your integration, resubmit it to the OIN team. + +> **Note:** When you edit your published OIN integration, your previous PUBLISHED status and date are overwritten with the DRAFT status and current date. + +To update a previously published OIN integration: + +1. Sign in to your Okta Developer Edition org as a user with either app admin or super admin roles. + > **Note:** Edit your integration from an Okta account that has your company domain in the email address. You can't use an account with a personal email address. The OIN team doesn't review submission edits from a personal email account. +1. In the Admin Console, go to **Applications** > **Your OIN Integrations**. + + > **Note:** If you don't need to edit your submission and want to jump to testing, see [Navigate directly to test your integration](#navigate-directly-to-test-your-integration). + +1. Click your published integration to update from the dashboard. Your published OIN submission appears in read-only mode. +1. From the **This integration is read-only** information box, click **Edit integration**. + > **Note:** If you open a submission in **DRAFT** status, it's not in read-only mode and the **Edit integration** option isn't available. + + Continue to edit your draft submission as a new submission. See [Start a submission](#start-a-submission). +1. If the OIN Wizard doesn't detect an instance to test your published integration in the org, then an **Application instance not detected** dialog appears. Click **Generate instance** to create an app instance based on your published OIN integration. See [Add existing app integrations](https://help.okta.com/okta_help.htm?type=oie&id=csh-apps-add-app) to create an instance for backwards-compatibility testing. + > **Note:** The **Generate instance** option is disabled if you have five active instances in your org. [Deactivate instances](#deactivate-an-app-instance-in-your-org) that you're not using. + + If the OIN Wizard detects an instance based on your published integration, the dialog doesn't appear. This is usually the case if you tested and submitted your published integration from the same org. + +1. Continue to update your integration in the **Select protocol**, **Configure your integration**, and **Test integration** pages. See [Update integration considerations](#update-integration-considerations) for backwards compatibility with integration variables. + + The **Required app instances** box contains the following items: + * The instances that you need to test the **PUBLISHED VERSION** of your OIN integration. + * The instances that you need to test the **CURRENT VERSION** of your integration submission. + + See [Required app instances](#required-app-instances). + > **Note:** If the OIN Submission Tester session expired, click **Refresh tester session** for a new test session. + + Backwards-compatible test instances that were generated from your published integration appear in the **Application instances for testing** list. + +1. Click **Generate Instance** to create an instance required for the **CURRENT VERSION** from the **Required app instances** status box. + + See [Generate an instance for testing](#generate-an-instance-for) to create instances for your current submission. + > **Note:** There's a maximum of five active app instances allowed in a Developer Edition org. Deactivate any instances that you don't need for testing. + +1. Test your integration protocol: + + * For SSO testing, click **Add to Tester** for each required test instance. See [Add to Tester](#add-to-tester).
The required tests appear for each test instance. Run your tests from the OIN Submission Tester. See [OIN Submission Tester](#oin-submission-tester). If you encounter errors, see [Failed tests](#failed-tests) for help with resolving the issues. + + * For SCIM testing, see [Test your SCIM integration](#test-your-scim-integration) for all the test requirements. + +1. [Submit your updates](#submit-your-updates) if all your tests passed. + +## Update integration considerations + +* For published integrations that were migrated from the OIN Manager, if you need to update configured properties that aren't available the OIN Wizard, contact . + +* You can't update a published SCIM integration with Basic authentication. This breaks the integration for existing customers. For any updates, you must submit a new SCIM integration that implements header authentication or OAuth 2.0 authentication. You can use either token or bearer token format for header authentication. + +* If you edit a published SCIM integration that was migrated from the OIN Manager, the **Import users** (and **Import groups** if groups are managed) capability is automatically enabled in the OIN Wizard. You must support and test this capability if your previous SCIM integration didn't support it. If you need help with implementing this feature, contact . + +* When you update an integration that's already published, be mindful to preserve backwards compatibility for your integration. Older instances of your integration could be in use by Okta customers. + + * If you modify the **Name** (`name`) property of your [integration variables](#integration-variables), Okta removes the original variable and creates a variable with your updated name. This action negatively impacts your existing customers if you use the original variable in your integration dynamic properties. + + * Migrated published integrations from the OIN Manager don't have some OIN Wizard restrictions. For instance: + + * Published integrations can have more than three integration variables + * Published integrations can have variable names with uppercase letters + * Published integrations can use `http` (instead of enforced `https`) in URLs and Expression Language-supported properties + + * If your update introduces new variables and you're using dynamic URLs, ensure that your tests cover various scenarios with different possible values for those variables. See [Dynamic properties with Okta Expression Language](#dynamic-properties-with-okta-expression-language). The newly introduced variables aren't populated for older instances of your integration. + + For example: + + + +## Submit your updates + +After you successfully test your updated integration, you're ready to submit. + +The OIN Wizard checks the following for SSO submissions: + +* All required instances are detected. +* All required instances are active. +* All required tests passed within the last 48 hours. + +The OIN Wizard checks the following for SCIM submissions: + +* All required instances are detected. +* All required instances are active. +* The **Link to Runscope spec test results** field is specified. +* The **Link to Runscope CRUD test results** field is specified. + +> **Note:** See [Test your SCIM integration](#test-your-scim-integration) for SCIM submission requirements. + +**Submit integration** is enabled after all these requirements are met. + +1. Select **I certify that I have successfully completed required tests**. +1. Click **Submit integration** to submit your integration. +1. Click **Close wizard**. + The **Your OIN Integration** dashboard appears. + +After you submit your integration, your integration is queued for OIN initial review. Okta sends you an email with the expected initial review completion date. + +The OIN review process consists of two phases: + +1. The initial review phase +1. The QA testing phase + +Okta sends you an email at each phase of the process to inform you of the status, the expected phase completion date, and any issues for you to fix. If there are issues with your integration, make the necessary corrections and resubmit in the OIN Wizard. + +> **Note:** Sometimes, your fix doesn't include OIN Wizard edits to your integration submission. In this case, inform the OIN team of your fix so that they can continue QA testing. + +Check the status of your submission on the **Your OIN Integrations** dashboard. + +See [Understand the submission review process](/docs/guides/submit-app-overview/#understand-the-submission-review-process). + +## Submission support + +If you need help during your submission, Okta provides the following support stream for the various phases of your OIN submission: + +1. Building an integration phase + + * When you're constructing your SSO app integration, you can post a question on the [Okta Developer Forum](https://devforum.okta.com/) or submit your question to . + +1. Using the OIN Wizard to submit an integration phase + + * If you need help with the OIN Wizard, review this document or see [Publish an OIN integration](/docs/guides/submit-app-overview/). + * Submit your OIN Wizard question to if you can't find an answer in the documentation. + * If you have an integration status issue, contact . + +1. Testing an integration phase + + * If you have issues during your integration testing phase, you can post a question on the [Okta Developer Forum](https://devforum.okta.com/) or submit your question to . + diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/backward-compatible-eg.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/backward-compatible-eg.md new file mode 100644 index 00000000000..969092af031 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/backward-compatible-eg.md @@ -0,0 +1,9 @@ + Your integration update introduced a new variable (`companyId`), and you use it in your updated redirect URL. The redirect URL changed from `https://login.myapp.io` to `https://login.myapp.io?connection={app.companyId}`. In this case, ensure that the dynamic redirect URL is also valid for existing instances where the `companyId` value isn't set. + + To handle empty `companyId` values, you can define the redirect URL as: + + ```bash + https://{String.len(app.companyId) == 0 ? 'login.myapp.io' : 'login.myapp.io?connection=' + app.companyId} + ``` + + This expression handles both scenarios where `companyId` is populated or empty. \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-fullname.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-fullname.md new file mode 100644 index 00000000000..2f8bbd40ed5 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-fullname.md @@ -0,0 +1 @@ +OpenID Connect (OIDC) \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-name.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-name.md new file mode 100644 index 00000000000..1b007617e10 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-name.md @@ -0,0 +1 @@ +OIDC \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-test-flow.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-test-flow.md new file mode 100644 index 00000000000..4784eb9d3fc --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/protocol-test-flow.md @@ -0,0 +1,13 @@ +In the **OIDC tests** section, specify the following sign-in flow details: + +|
Property
|   | Description | +| ----------------- | --: | ------------ | +| **Supported sign-in flows** | | Indicates which sign-in flow your integration supports | +| | **IdP** | Sign-in flow is initiated from the Okta End-User Dashboard. If you specified **Initiate login URI** previously from the [OIDC properties](#properties) section, then this flow is selected. | +| | **SP** | Sign-in flow is initiated from your app sign-in page. This flow is selected and read-only because all OIDC SSO integrations must support the SP-initiated flow. | +| **Supports Just-In-Time provisioning?** `*` | | Indicate if your integration supports Just-In-Time (JIT) provisioning. With JIT provisioning, user profiles are created when they sign in for the first time. This eliminates the need to create user accounts in advance. | +| | **Yes** | Your integration supports JIT. | +| | **No** | Your integration doesn't support JIT. | +| **SP Initiate URL** | | Specify the URL for SP-initiated sign-in flows. This URL is required for the SP-initiated flow.
The maximum URL length is 512 characters. | + +`*` Required properties diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/test-instance.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/test-instance.md new file mode 100644 index 00000000000..a4548233886 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/test-instance.md @@ -0,0 +1,14 @@ +2. Specify the **Application label** and any app properties required in the **General settings** tab. +3. Click **Done**. The **Assignments** tab appears. + You can assign users to your integration later, see the next [Assign test users to your integration](#assign-test-users-to-your-integration-instance) task. +4. Click the **Sign On** tab to view and copy the OIDC client ID and secret. +5. Click **View Setup Instructions** to open a new tab to your integration setup instructions. This is the customer configuration guide that you previously specified in the OIN Wizard. +6. Follow the instructions in your guide to set up the SSO integration on your app with the OIDC client ID and secret provided. +7. Follow these steps if you have an Identity Engine Developer Edition org: + 1. Click the **Sign On** tab, scroll to the **User authentication** section, and click **Edit**. + 1. Select **Password only** from the **Authentication policy** dropdown menu. + [[style="list-style-type:lower-alpha"]] + 1. Click **Save**. + > **Note:** Most recent Okta Developer Edition orgs are Identity Engine orgs. See [OIN Wizard authentication policy for testing](/docs/guides/submit-app-prereq/main/#oin-wizard-authentication-policy-for-testing). + +8. [Assign test users to your instance](#assign-test-users-to-your-integration-instance) before you start testing your SSO flows. \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/variable-desc.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/variable-desc.md new file mode 100644 index 00000000000..a938af561e5 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/openidconnect/variable-desc.md @@ -0,0 +1,13 @@ +For example, if you have an OIDC configuration variable called `subdomain`, then you can set your **Redirect URI** string to `https://{app.subdomain}.example.org/strawberry/login`. When your customer sets their `subdomain` variable value to `berryfarm`, then `https://berryfarm.example.org/strawberry/login` is their redirect URL. + +> **Note**: A variable can include a complete URL (for example, `https://example.com`). This enables you to use global variables, such as `app.baseURL`. + +The following are Expression Language specifics for OIDC properties: + +* OIDC [integration variables](#integration-variables) you define in the OIN Wizard are considered [Application properties](/docs/reference/okta-expression-language/#application-properties) and have the `app.` prefix when you reference them in Expression Language. For example, if your integration variable name is `subdomain`, then you can reference that variable with `app.subdomain`. + +* OIDC properties support [Expression Language conditional expressions](/docs/reference/okta-expression-language/#conditional-expressions) and evaluates everything between curly brackets. For example, the following is an expression for the **Redirect URI** property: + + ```js + {String.stringContains(app.environment, 'PROD') ? 'https://app.data.one/' : 'https://app-sandbox.data.one/'} + ``` \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/backward-compatible-eg.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/backward-compatible-eg.md new file mode 100644 index 00000000000..5c246d9d52a --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/backward-compatible-eg.md @@ -0,0 +1,9 @@ + Your integration update introduced a new variable (`companyId`), and you use it in your updated ACS URL. The ACS URL changed from `https://login.myapp.io` to `https://login.myapp.io?connection={org.companyId}`. In this case, ensure that the dynamic ACS URL is also valid for existing instances where the `companyId` value isn't set. + + To handle empty `companyId` values, you can define the ACS URL as: + + ```bash + https://${empty org.companyId ? 'login.myapp.io' : 'login.myapp.io?connection=' += org.companyId} + ``` + + This expression handles both scenarios where `companyId` is populated or empty. \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-fullname.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-fullname.md new file mode 100644 index 00000000000..43347ef91d7 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-fullname.md @@ -0,0 +1 @@ +Security Assertion Markup Language (SAML) \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-name.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-name.md new file mode 100644 index 00000000000..f1ee2b8e0e3 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-name.md @@ -0,0 +1 @@ +SAML \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-test-flow.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-test-flow.md new file mode 100644 index 00000000000..f01784fa403 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/protocol-test-flow.md @@ -0,0 +1,14 @@ +In the **SAML tests** section, specify the following sign-in flow details: + +|
Property
|   | Description | +| ----------------- | --: | ------------ | +| **Supported sign-in flows** | | Indicate which sign-in flow your integration supports. You must select at least one of the following flows. | +| | **IdP** | Sign-in flow is initiated from the Okta End-User Dashboard. | +| | **SP** | Sign-in flow is initiated from your app sign-in page. | +| **Supports Just-In-Time provisioning?** `*` | | Indicate if your integration supports Just-In-Time (JIT) provisioning. With JIT provisioning, you can use a SAML assertion to create users the first time they try to sign in. This eliminates the need to create user accounts in advance. | +| | **Yes** | Your integration supports JIT. | +| | **No** | Your integration doesn't support JIT. | +| **SP Initiate URL** | | Specify the URL for SP-initiated sign-in flows. This URL is required for the SP flow.
The maximum URL length is 512 characters. | +| **SP Initiate flow description** | | Provide instructions on how to sign in to your app using the SP-initiated flow.
The maximum description length is 2048 characters. This field is required for the SP flow.| + +`*` Required properties diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/test-instance.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/test-instance.md new file mode 100644 index 00000000000..57e756ed537 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/test-instance.md @@ -0,0 +1,16 @@ +2. Specify the **Application label** and any integration properties required in the **General settings** tab. +3. Click **Done**. The **Assignments** tab appears. + You can assign users to your integration later, see [Assign test users to your integration](#assign-test-users-to-your-integration-instance). +4. Click the **Sign On** tab. +5. Click **View SAML setup instructions** to open a new tab to your integration setup instructions. This is the customer configuration guide that you previously specified in the OIN Wizard. +6. Follow the instructions in your guide to set up the SAML SSO integration on your app. + * Click **Copy** next to **Metadata URL** to copy the full SAML metadata URL required for the integration. + * To view specific SAML metadata details, click the **More details** arrow. +7. Follow these steps if you have an Identity Engine Developer Edition org: + 1. Click the **Sign On** tab, scroll to the **User authentication** section, and click **Edit**. + 1. Select **Password only** from the **Authentication policy** dropdown menu. + [[style="list-style-type:lower-alpha"]] + 1. Click **Save**. + > **Note:** Most recent Okta Developer Edition orgs are Identity Engine orgs. See [OIN Wizard authentication policy for testing](/docs/guides/submit-app-prereq/main/#oin-wizard-authentication-policy-for-testing). + +8. [Assign test users to your instance](#assign-test-users-to-your-integration-instance) before you start testing your SSO flows. \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/variable-desc.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/variable-desc.md new file mode 100644 index 00000000000..5c77bf74ad0 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/saml2/variable-desc.md @@ -0,0 +1,31 @@ +For example, if you have a SAML configuration variable called `subdomain`, then you can set your **ACS URL** string to `https://${org.subdomain}.example.org/strawberry/login`. When your customer sets their `subdomain` variable value to `berryfarm`, then `https://berryfarm.example.org/strawberry/login` is their ACS URL. + +> **Note**: A variable can include a complete URL (for example, `https://example.com`). This enables you to use global variables, such as `org.baseURL`. + +The following are Expression Language specifics for SAML properties: + +* SAML [integration variables](#integration-variables) you define in the OIN Wizard are considered [Organization properties](/docs/reference/okta-expression-language/#organization-properties) and have the `org.` prefix when you reference them in Expression Language. For example, if your integration variable name is `subdomain`, then you can reference that variable with `org.subdomain`. + +* SAML properties support [Expression Language conditional expressions](/docs/reference/okta-expression-language/#conditional-expressions) and evaluates everything between `${` and `}`. For example, the following is an expression for the **ACS URL** property: + + ```js + ${empty org.baseUrl ? 'https://app.mydomain.com' : org.baseUrl} + ``` + +* SAML properties don't support Expression Language [String functions](https://developer.okta.com/docs/reference/okta-expression-language/#string-functions). Use [JSTL functions](https://docs.oracle.com/javaee/5/jstl/1.1/docs/tlddocs/fn/tld-summary.html) instead. For example: + + ```js + ${fn:substringAfter(org.base_url, '//')} + ``` + + ```js + ${fn:substringBefore(user.userName, '@')}@example.com + ``` + + ```js + https://${fn:endsWith(org.site_url, 'host1.com') ? 'host1.com' : fn:endsWith(org.site_url, 'host2.com') ? 'host2.com' : '.host.com'}/sso/saml + ``` + + ```js + https://${fn:contains(org.environment, 'production') ? 'productiondomain.com' : 'previewdomain.com'}/sso/saml + ``` diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/backward-compatible-eg.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/backward-compatible-eg.md new file mode 100644 index 00000000000..2f18e423586 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/backward-compatible-eg.md @@ -0,0 +1,9 @@ + Your integration update introduced a new variable (`companyId`), and you use it in your updated SCIM server base URL. The base URL changed from `https://fruits.example.com/scim2/myapp/` to `https://fruits.example.com/scim2/myapp?connection={app.companyId}`. In this case, ensure that the dynamic base URL is also valid for existing instances where the `companyId` value isn't set. + + To handle empty `companyId` values, you can define the base URL as: + + ```js + 'https://fruits.example.com/scim2/myapp' + (String.len(app.companyId) == 0 ? '/' : '?connection=' + app.companyId) + ``` + + This expression handles scenarios where `companyId` is populated or empty. diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-fullname.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-fullname.md new file mode 100644 index 00000000000..822178edab0 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-fullname.md @@ -0,0 +1 @@ +SCIM 2.0 \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-name.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-name.md new file mode 100644 index 00000000000..31ab7a9f854 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-name.md @@ -0,0 +1 @@ +SCIM \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-properties.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-properties.md new file mode 100644 index 00000000000..45dfff58fcc --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-properties.md @@ -0,0 +1,10 @@ +|
Property
| Description | +| ----------------- | ------------ | +| **Base URL** `*` | Specify the base URL for your SCIM server.
If you're using a per tenant design, include the variable names that you created in your URL. For example:` 'https://' + app.subdomain + '.example.com/scim2/' `. See [Dynamic properties with Okta Expression Language](#dynamic-properties-with-okta-expression-language).
The maximum field length is 1024 characters. | +| **What objects do you want Okta to manage in your integration?** `*` | Select the objects that you want Okta to manage with your SCIM integration.
  • **Users**: Okta manages users in your app by default.
  • **Groups**: Select this option if you also want Okta to manage groups in your app.
| +| **Authentication mode** `*` | Select the authentication mode to make outbound calls to your SCIM server.
  • **Header**: Uses authorization header with a customer-provided token in the following format: `Authorization: {API token}`
  • **Bearer**: Uses authorization header with a customer-provided bearer token in the following format: `Authorization: Bearer {API token}`
  • **OAuth 2**: Uses OAuth 2.0 authorization code grant flow with the following:
    • **Authorize endpoint**: Specify the authorize endpoint. For example: `https://myexample.com/oauth2/auth`
      You can specify a dynamic endpoint URL. See [Dynamic properties with Okta Expression Language](#dynamic-properties-with-okta-expression-language).
    • **Token endpoint**: Specify the token endpoint. For example: `https://myexample.com/oauth2/token`
      You can specify a dynamic endpoint URL. See [Dynamic properties with Okta Expression Language](#dynamic-properties-with-okta-expression-language).
    • **Client ID**: Specify the client ID.
    • **Client secret**: Specify the client secret.
**Note**: Basic authentication isn't supported. See [SCIM integration limitations](/docs/guides/submit-app-prereq/main/#scim-integration-limitations). | +| **User operations** `*` | Select user operations for your SCIM integration.
  • **Create**: Okta can create users in your app.
  • **Read** `*`: Okta can read users from your app.
  • **Update**: Okta can update users in your app.
  • **Change password**: Okta can update user passwords in your app.
  • **Deactivate**: Okta can deactivate users in your app.
  • **Support PATCH for User**: Okta can update users with the PATCH method in your app.
**Note**: **Import users** capability is enabled by default. **Profile sourcing** isn't supported, contact the [OIN team](mailto:oin@okta.com) if your integration must support this capability.| +| **Group operations** | Group operations for your SCIM integration. These are all selected by default if your integration manages the **Groups** object.
  • **Create**: Okta can create groups in your app.
  • **Read** `*`: Okta can read groups from your app.
  • **Update (Uses PATCH)**: Okta can update groups in your app with the PATCH method.
  • **Delete**: Okta can delete groups in your app.
**Note**: **Import groups** capability is enabled by default.| +| **Link to configuration guide** `*` | Specify the URL link to your customer-facing instructions on how to configure SCIM provisioning between Okta and your app. See [Customer configuration document guidelines](/docs/guides/submit-app-prereq/main/#customer-configuration-document-guidelines).| + +`*` Required properties diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-test-flow.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-test-flow.md new file mode 100644 index 00000000000..997c48dab48 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/protocol-test-flow.md @@ -0,0 +1,3 @@ +Before you test your Okta SCIM integration, confirm that your SCIM API service is operational. Okta provides a SCIM API specification test suite in Runscope. See [Test your SCIM API](/docs/guides/scim-provisioning-integration-prepare/main/#test-your-scim-api). + +After you've successfully run the Okta SCIM API specification test suite in Runscope, save the URL of the test results. This Runscope test results URL is one of the requirements to submit your integration. diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/test-instance.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/test-instance.md new file mode 100644 index 00000000000..1c7ea8a49e7 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/test-instance.md @@ -0,0 +1,75 @@ +2. In the **General settings** tab, enter an **Application label** and any other required integration properties. +3. Click **Done**. Your generated test instance appears with more tabs for configuration. +4. Click **Provisioning** > **Configure API Integration**. +5. Select **Enable API integration**. + * For custom or bearer authentication, specify the **API token** for your instance. + * For OAuth 2.0 authentication, click **Authenticate with {yourApp}** and provide credentials for your test instance. +1. Click **Test API Credentials** to test authentication to your SCIM service. If there's an error, verify that the credentials are correct. +1. Click **Save**. +1. Select **Settings** > **To Okta** from the updated **Provisioning** tab. +1. In the **General** section, click **Edit** to schedule imports and configure the username format for imported users. + + You can also define a percentage of acceptable assignments before the [import safeguards](https://help.okta.com/okta_help.htm?id=csh-eu-import-safeguard) feature is automatically triggered. + +1. Click **Save**. Next, [configure attribute mappings](#configure-attribute-mappings). + +> **Note:** Your SCIM app must support redirect URIs that include the app name (`{appName}`) that's generated after you create your app instance. See SCIM service [authentication](/docs/guides/scim-provisioning-integration-prepare/main/#authentication) for a list of redirect URIs required. Your app name appears in the **General settings** tab or in the Admin Console URL when you're viewing the instance page. + +#### Configure attribute mappings + +> **Note:** Configure attribute-mapping instructions are only for SCIM integrations. + +SCIM integrations that are submitted through the OIN Wizard have a default set of user attribute mappings. The user schema in your SCIM app might not support all of these attributes. Ensure the integration that you're submitting to Okta reflects the attributes that are supported by your app. The OIN team uses the attribute mappings in your test instance for your integration provisioning settings in the OIN catalog. + +After you've enabled the provisioning API connection in your test instance, configure user attribute mappings to and from Okta in the **Provisioning** tab of your instance: + +* **To App**: User attribute mappings from Okta to your app +* **To Okta**: User attribute mappings from your app to Okta + +1. Select **To App** on the left **Settings** panel of the **Provisioning** tab. + The **Provisioning to App** settings appear. The provisioning operations are already set by default from the [SCIM properties](#properties) section when you configured your integration. + +1. Scroll to the **{yourApp} Attribute Mappings** section. + + * Delete attributes: + 1. Click **X** next to the attribute that you want to delete, and then click **OK** to confirm. + + Repeat this step until you remove all the mappings for the attributes that you want to delete. + + 1. After removing all the mappings for the attributes that you want to delete, click **Go to Profile Editor**. + + 1. In the Profile Editor, delete all the corresponding attributes from the mapping by clicking **X** next to the attribute and then **Delete Attribute** to confirm. + + Repeat this step for all the attributes that you want to delete. + + * Add attributes: + + 1. In the Profile Editor, click **Add Attribute**. + + 1. Enter the information for the new attribute that you’re adding and then click **Save**. + + > **Note:** The **Scope** property determines whether the attribute that you're adding can be assigned at a group level or per user. If you want your admins to assign a value for this attribute at a group level, don't select the **User personal** checkbox. + + 1. After adding attributes, go back to the **{yourApp} Attribute Mappings** section and click **Edit** to map your new attributes. A dialog appears with two dropdown fields. + + 1. Select **Map from Okta Profile** in the first dropdown list. + 1. In the second dropdown list, select the Okta profile attribute that you want to map over to the SCIM attribute. + 1. Click **Save**. + + Repeat these steps for all SCIM attributes that you want to map (from Okta to your app). + +
+ + ![Displays the map attribute dialog.](/img/oin/scim_check-attributes-14.png) + +
+ + 5. After you update the mappings from Okta to your app, click **To Okta** in the **Settings** section. + 6. Scroll to the **{yourApp} Attribute Mappings** section. Find the attribute that you want to update and click **Edit**. A dialog appears with two dropdown fields next to **Attribute value**. + 7. Select **Map from {yourApp} App Profile** from the first dropdown list. + 8. In the second dropdown list, select the SCIM attribute that you want to map to the Okta attribute. + 9. Click **Save**. + + Repeat these steps for all SCIM attributes that you want to map from your app to Okta. + +After you complete your attribute mappings, you're ready to [test your SCIM integration](#test-your-scim-integration). diff --git a/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/variable-desc.md b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/variable-desc.md new file mode 100644 index 00000000000..52049aedf51 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/update-oin-app/main/scim/variable-desc.md @@ -0,0 +1,27 @@ +For example, if you have a SCIM configuration variable called `subdomain`, then you can set your **Base URL** string to ` 'https://' + app.subdomain + '.example.org/strawberry/scim2/'`. When your customer sets their `subdomain` variable value to `berryfarm`, then `https://berryfarm.example.org/strawberry/scim2/` is their base URL. + +> **Note**: A variable can include a complete URL (for example, `https://example.com/scim2/`). This enables you to use global variables, such as `app.baseURL`. + +The following are Expression Language specifics for SCIM properties: + +* Any SCIM [integration variables](#integration-variables) that you define in the OIN Wizard are considered [application properties](/docs/reference/okta-expression-language/#application-properties). They have an `app.` prefix when you reference them in Expression Language. For example, if your integration variable name is `subdomain`, then you can reference that variable using `app.subdomain`. + +* SCIM properties support [Expression Language conditional expressions](/docs/reference/okta-expression-language/#conditional-expressions). For example: + + ```js + 'https://' + app.subdomain + '.example.org/strawberry/scim2/'` + ``` + + ```js + 'https://' + (app.region == 'us' ? 'myfruit' : 'myveggie') + '.example.com/strawberry/oauth/token' + ``` + +* SCIM properties support Expression Language [String functions](https://developer.okta.com/docs/reference/okta-expression-language/#string-functions). For example: + + ```js + (String.len(app.baseUrl) == 0 ? 'https://fruit.example.com/scim2/' : app.baseUrl) + 'v1/oauth_token' + ``` + + ```js + (String.stringContains(app.environment,"PROD") ? 'https://fruit.example.com' : 'https://fruit-sandbox.example.com') + '/v1/oauth2/token' + ``` diff --git a/packages/@okta/vuepress-theme-prose/const/navbar.const.js b/packages/@okta/vuepress-theme-prose/const/navbar.const.js index 88d03347f77..f0724ee9416 100644 --- a/packages/@okta/vuepress-theme-prose/const/navbar.const.js +++ b/packages/@okta/vuepress-theme-prose/const/navbar.const.js @@ -689,6 +689,10 @@ export const guides = [ title: "OIN Wizard: Submit an integration", guideName: "submit-oin-app", }, + { + title: "OIN Wizard: Update an integration", + guideName: "update-oin-app", + }, { title: "OIN Manager: Submit an integration", guideName: "submit-app",