docs: Restore and polish Okta first-party integration docs (#4011)

docs/docs/system-administration/authentication/02-Okta.md

@@ -3,28 +3,46 @@ title: Okta
 ---
 
 Flagsmith can integrate with your Okta single sign-on (SSO) by using [SAML](/system-administration/authentication/SAML).
+We provide a [first-party Okta integration](https://www.okta.com/integrations/flagsmith/) to simplify the setup.
 
 ## Prerequisites (SaaS)
 
-Get in touch with Flagsmith support to obtain the single sign-on URL and audience URI to use when creating your Okta
-SAML application.
+Get in touch with Flagsmith support to obtain the single sign-on URL and audience URI to use when configuring your Okta
+application.
 
 ## Prerequisites (self-hosted)
 
 Create a SAML configuration by following the
 [instructions to set up SAML](/system-administration/authentication/01-SAML/index.md#setup-self-hosted). Leave the
 identity provider metadata blank for now.
 
-## Setup
+## Procedure
 
-[Create an Okta SAML application](https://help.okta.com/oag/en-us/content/topics/access-gateway/add-app-saml-pass-thru-add-okta.htm)
-from the Okta management to represent your Flagsmith organisation with the following settings:
+Add the [first-party Flagsmith integration](https://www.okta.com/integrations/flagsmith/) to your Okta account. Then,
+open it in the Okta dashboard and:
 
-- **Single sign-on URL**: Obtain this URL from Flagsmith support, or from your
-  [SAML configuration if self-hosting](/system-administration/authentication/SAML/#assertion-consumer-service-url)
-- **Audience URI (SP Entity ID)**: Obtain this from Flagsmith support, or use your
-  [SAML configuration name](/system-administration/authentication/SAML/#setup-self-hosted) if self-hosting
+- Select the "Sign On" tab and click "Edit"
+- Scroll down to "Advanced Sign-on Settings", fill out the two fields and then click Save:
+  - **API Base URL** should be `https://api.flagsmith.com` on SaaS, or your API root URL otherwise
+  - **SAML Organisation** will be provided by Flagsmith support on SaaS. Otherwise, this refers to the "Organisation
+    name" field [when creating a SAML Configuration](/system-administration/authentication/SAML/#setup-self-hosted)
+- Staying on the "Sign On" tab, find the "Metadata URL" in the "Sign on methods" section. Save this metadata to a file
+  and send it to [Flagsmith support](mailto:[email protected]), or add it to the "IdP Metadata XML" field of your
+  Flagsmith SAML Configuration if self-hosting
 
-Once your Okta application is created, you can
-[download its corresponding identity provider metadata](https://support.okta.com/help/s/article/Location-to-download-Okta-IDP-XML-metadata-for-a-SAML-app-in-the-new-Admin-User-Interface?language=en_US)
-and send it to Flagsmith support, or add it to your SAML configuration if self-hosting.
+Once Flagsmith support have confirmed that the metadata has been uploaded, your users will be able to sign in via the
+Okta applications dashboard and the Flagsmith dashboard by entering the organisation name given to you by Flagsmith
+support, or the SAML configuration name if self-hosting.
+
+## User attributes
+
+By default, Flagsmith's Okta integration will map your users' email address, given name and surname so that they are
+visible within Flagsmith. If you need to map different attributes, please
+[contact support](mailto:[email protected]) or refer to the
+[documentation on SAML attribute mappings](/system-administration/authentication/SAML/#attribute-mapping).
+
+## Troubleshooting
+
+If your users are unable to sign in to the Flagsmith application via Okta, it’s important to check if they already have
+a user account in Flagsmith with their Okta email address. If they do, make sure that they are not a member of any other
+organisations than the one set up in the Okta integration.