Okta Documentation

Welcome! This step-by-step guide will walk you through the process of configuring your Okta integration with Surface AI. It provides step-by-step instructions to ensure your Okta environment is properly configured and ready for use with your cloud application.

Questions or concerns? Reading this guide will help you understand your Okta integration setup. If you still have any questions or concerns, please contact us at admin@getsurface.ai.

Note: Each section contains examples for OIDC, SAML, or SCIM content. You can use the examples as an initial template. Copy and paste the example markdown text into your customer configuration document and customize the content for your integration.

1. Prerequisites

In this section, specify any prerequisites required before your customer configures your integration in Okta. Examples may include enabling specific Okta features, enabling API access to your SCIM server, or adding a particular version of an integration in Okta.

SAML prerequisite example

## Prerequisites

When you use SAML as the SSO mode with provisioning, you need to enable a specific account plan on the app side for silent activation.

2. Supported features

In this section of your guide, list the features that your app supports and include any restrictions or limitations.

Note: You can also briefly describe what each feature does.

OIDC supported feature example

## Supported features

* SP-initiated SSO (Single Sign-On)
* IdP-initiated SSO (through [Third-party Initiated Login](https://openid.net/specs/openid-connect-core-1_0.html#ThirdPartyInitiatedLogin))
* Just-In-Time provisioning
* SP-initiated SLO (Single Logout)

For more information on the listed features, visit the [Okta Glossary](https://help.okta.com/okta_help.htm?type=oie&id=ext_glossary).

SAML supported feature example

## Supported features

* IdP-initiated SSO
* SP-initiated SSO
* Just-In-Time provisioning
* SP-initiated SLO
* Force authentication

For more information on the listed features, visit the [Okta Glossary](https://help.okta.com/okta_help.htm?type=oie&id=ext_glossary).

SCIM supported feature example

## Supported features


* Create users
* Update user attributes
* Deactivate users
* Import users
* Import groups
* Sync password
* Profile sourcing
* Group push

Okta can't update user attributes for Admin users. This is an API limitation.

For more information on the listed features, visit the [Okta Glossary](https://help.okta.com/okta_help.htm?type=oie&id=ext_glossary).

3. Configuration steps

This section helps you define how your customers get set up with your integration. Detail all settings and include any images that can assist the user. Include any best practices for your procedure, such as SCIM guidance on mappings for attributes, especially required attributes that don’t have a default mapping.

For SCIM integrations, provide steps for your customer to obtain their SCIM server credentials. Your customer admin needs this information before they can configure your SCIM integration in Okta. See SCIM examples.

Note: If your Service Provider is configured as a “Big Bang”, you need to provide a warning note to your customer. See SAML configuration warning example.

SAML configuration warning example

If you only allow sign-in through Okta (Big Bang configuration), ensure that you provide a warning note before the configuration steps. For example:

### Read this before you enable SAML

Enabling SAML affects all users who use this app.
Users won't be able to sign in through their regular sign-in page.
They are able to access the app through the Okta service.

### Backup URL

{appName} doesn't provide a backup sign-in URL where users can sign in using their regular username and password.
If necessary, contact {appName} Support (support@{appName}.com) to turn off SAML.

SAML configuration steps example

The following is an example of a simple SAML customer procedure:

## Configuration steps

1. Copy the Metadata URL from the Okta Admin Console, SAML 2.0 Sign on methods section.
2. Contact the {appName} support team (for example, support@{appName}.com) and request that they enable SAML 2.0 for your account. Include the "Metadata URL" value from the previous step.
   The {appName} support team processes your request and provides you with an SSO ID and an encryption certificate.
3. In your Okta Admin Console, select the Sign on tab for the {appName} SAML app, then click "Edit" and follow the steps below:
   * "Encryption Certificate": Upload the certificate provided by {appName} support in the previous step.
   * Scroll down to Advanced Sign-on Settings and enter your "SSO ID".
   * Application username format: Select "email".
   * Click "Save".
4. Your SAML configuration for {appName} is complete. You can start assigning people to the app.

Note: The Sign On tab for your app integration may have different fields from the previous example. Adjust your configuration guide as required from the example template.

For a complete customer configuration guide example that requires support to configure SAML, see How to Configure SAML 2.0 Template with company support (opens new window).

SAML admin configuration steps example

For some integrations, the customer admin needs to configure SAML settings in your app. The following is an example of an admin procedure to configure SAML settings:

## Configuration steps

1. Copy the Metadata URL from the SAML 2.0 Metadata details section in the Admin Console and save this value for the next few steps.
2. Sign in to {appName}.
3. Navigate to Admin >  Settings > SAML SSO.
4. Specify the following:
   * ENABLE SAML SSO: Select "Yes".
   * IDP Provider: Select "Okta".
   * Metadata URL: Copy and paste the metadata URL value from step one.
4. Click "Save Changes".

The SAML setting is complete in {appName}.

Note: Your app integration may require specific SAML settings instead of the SAML Metadata URL. These SAML settings include Sign on URL, Sign out URL, Issuer, and Signing Certificate.
You can find these SAML settings at Applications > Applications > your SAML app > Sign-On Options tab > Sign on methods > SAML 2.0 > Metadata details in the Admin Console. Adjust your configuration guide to include these settings as required.

For a complete customer admin configuration guide example, see How to Configure SAML 2.0 Template for admins (opens new window).

SAML configuration steps note example

## Note

* Ensure that you entered the correct value in the "Subdomain" field under the General tab. The wrong subdomain value prevents you from authenticating through SAML to {appName}.

* Since only SP-initiated flow is supported, Okta recommends hiding the app icon for users.

* The following SAML attributes are supported:

   | Name      | Value          |
   | --------- | -------------- |
   | email     | user.email     |
   | firstName | user.firstName |
   | lastName  | user.lastName  |

SCIM configuration steps note example

## Note

The External ID is a required attribute, but it doesn't have a default mapping.
This is because some customers prefer to set it to `EmployeeNumber`, and others like to set it to `emailAddress`.
Assign the mapping to the correct value for your organization.

4. SP-initiated SSO

Note: This section applies only to SAML or OIDC integrations that support app-initiated Single Sign-On (SSO), also known as Service Provider (SP) initiated SSO.

Provide instructions for your users to sign in with Okta from your app. The user sign-in flow starts from your app’s sign-in page. The user enters their credentials and your app sends the authorization request to Okta (the Identity Provider) to authenticate the user.

SP-initiated SSO instructions example

## SP-initiated SSO

The sign-in process is initiated from {yourAppPortal}.

1. From your browser, navigate to the {appName} sign-in page.
2. Enter your Okta credentials (your email and password) and click "Sign in with Okta".
If your credentials are valid, you are redirected to the {appName} dashboard.