> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Okta Integration
> Set up Okta SSO and SCIM provisioning with Courier to enable secure logins, role management, and automated user syncing via SAML 2.0 and Okta's admin interface.
Okta SSO and SCIM provisioning are available on the Enterprise plan. [Contact Sales](mailto:sales@courier.com) or [Courier Support](mailto:support@courier.com) to get started.
## How It Works
Okta SSO for Courier uses SAML 2.0 through AWS Cognito. Setup is a joint process between your team and Courier:
1. **You** create a SAML 2.0 app in Okta using the values provided below.
2. **You** send the SAML metadata URL and your email domain(s) to [Courier Support](mailto:support@courier.com).
3. **Courier** configures the backend to recognize your identity provider and maps your domain(s) to Okta.
4. **You** test SSO login and set up the bookmark app for your team.
## Prerequisites
* An Okta account with Admin privileges.
* A list of users who will access Courier and their intended [roles](/platform/workspaces/roles-permissions) (e.g., Administrator, Developer, Designer, Analyst). You'll assign these when provisioning users through Okta.
* Contact [Courier Support](mailto:support@courier.com) before starting so your backend configuration can be coordinated with the steps below.
## Create the App Integration in Okta
Navigate to the Applications > Applications section of the Okta admin panel and hit the "Create App Integration" button.
Select SAML 2.0 as the sign-in method and hit "Next".
Enter `Courier` as the app name and optionally provide the Courier logo, then click "Next".
You can optionally upload the Courier logo. [Download it here](pathname:///img/logo_2023.png).
Enter the following values in their respective fields under SAML settings:
* **Single sign-on URL**: `https://courier.auth.us-east-1.amazoncognito.com/saml2/idpresponse`
* **Audience URI (SP Entity ID)**: `urn:amazon:cognito:sp:us-east-1_ptbRzqiLw`
In the **Attribute Statements** section, enter the following information:
| Name | Name Format | Value |
| -------------------------------------------------------------------- | ----------- | ---------- |
| `id` | Unspecified | user.id |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | Unspecified | user.email |
Hit "Next", then under "Application Feedback" select "I'm an Okta customer adding an internal app" and hit "Finish".
From the "Sign On" tab of the new Courier application integration, find the Metadata URL. Copy the link address and send it to the Courier support team member.
Along with the metadata URL, confirm which **email domain(s)** should route through Okta (e.g., `yourcompany.com`). If your organization uses multiple domains, list all of them.
That's all you need for Okta sign-in. Assign users from the **Assignments** tab of the Courier app integration in Okta.
## Creating a Courier Bookmark App
Courier does not support IdP-initiated login, so users cannot launch Courier by clicking an app tile in Okta. Instead, create a bookmark app that points to your SSO login URL.
Once Courier Support has configured your SSO backend, your bookmark URL will follow this pattern (replace `YOUR_PROVIDER_NAME` with the provider name Courier gives you):
```
https://courier.auth.us-east-1.amazoncognito.com/oauth2/authorize?response_type=token&identity_provider=YOUR_PROVIDER_NAME&client_id=5f4fmec2qnuscp89qbt8nsuftj&redirect_uri=https%3A%2F%2Fapp.courier.com%2Flogin%2Fcallback&scope=aws.cognito.signin.user.admin%20email%20openid%20profile
```
Courier Support will provide your specific provider name (e.g., `OktaYourCompany`) and the complete bookmark URL after backend configuration is complete.
Log in to the Okta admin panel as an Admin and go to **Applications > Applications**.
Click **Browse App Catalog**, search for `Bookmark App`, select it, and click **Add**.
Enter an app name (e.g. `Courier Login`) and paste the bookmark URL from Courier Support into the URL field.
Click **Save**, then assign to users to test.
## Migrating Users to Okta
Enabling Okta SSO does not automatically switch existing users to Okta. Users who signed up with email or Google will continue using their original login method until they are re-invited. To migrate them:
From the [Settings > Team](https://app.courier.com/settings/team) page in Courier, confirm that "Require Google SSO" is not checked.
Remove and re-invite any users who should sign in with Okta.
If SCIM provisioning is enabled, the manual "Invite User" button is hidden in Courier. Migration must go through Okta app assignments — assign the user in Okta, and SCIM will send them a new invite automatically.
## Accepting an Okta Invitation
Sign out of any existing Courier session.
Click the "join" button from the email invite.
Enter your work email (the email address your invite was sent to) and hit continue.
Users with Okta logins to Courier must use the email login process.
## User Provisioning with Okta SCIM v2
Contact Courier support for a SCIM endpoint URL and bearer token.
Navigate to the Courier App from the Okta admin panel, go to the provisioning tab, and click "Edit".
Enter the following settings:
* **SCIM connector base URL**: the URL provided by Courier
* **Unique identifier field for users**: `userName`
* **Supported provisioning actions**: check "Push New Users" and "Push Profile Updates"
* **Authentication Mode**: `HTTP Header`
* **Bearer token**: the token provided by Courier
Hit "Save".
After 30 seconds the provisioning tab should have a "To App" section on the left. If it doesn't, try refreshing the page. Once it appears, select it and hit the "Edit" button. Check "Create Users", "Update User Attributes", and "Deactivate Users", then hit save.
Using the side menu, navigate to Directory > Profile Editor and hit the edit profile button of the Courier App.
Hit the "Add Attribute" button and enter the following values:
* Data type: `string`
* Display name: `Role`
* Variable name: `role`
* External name: `role`
* External namespace: `urn:ietf:params:scim:schemas:core:2.0:User`
* Description: `Courier Role`
Check the "Define enumerated list of values" checkbox and enter the following values:
* Display Name: `Admin`, Value: `ADMINISTRATOR`
* Display Name: `Manager`, Value: `MANAGER`
* Display Name: `Developer`, Value: `DEVELOPER`
* Display Name: `Designer`, Value: `DESIGNER`
* Display Name: `Support`, Value: `SUPPORT_SPECIALIST`
* Display Name: `Analyst`, Value: `ANALYST`
Check the "Attribute required" checkbox and hit "save".
If the `role` attribute is not set on a user's Okta app assignment, they default to the **Analyst** role with the lowest permission level. Set a sensible default (e.g., `DEVELOPER`) in the Profile Editor and override only for administrators and managers.
If users were already assigned to the Courier app before you set up provisioning, edit their assignment and update their role.
### Finalizing User Provisioning
* Changes to user assignments in the Courier Okta app will automatically be reflected in the Courier Workspace.
* Users will receive an invite via email to Courier when added.
* Users are automatically removed from the Courier Workspace when no longer assigned in Okta.
## Troubleshooting
| Symptom | Cause | Fix |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "You must be signed in with an SSO provider" message in Courier | You're logged in via email or Google, not Okta SSO. The SSO management page only appears for SSO-authenticated sessions. | Log out and sign in again through the Okta bookmark app or via email login flow. |
| All users showing as Analyst role | The `role` attribute is not set on their Okta app assignments. | Edit each user's assignment in Okta and set the `role` value. Consider setting a default in the Profile Editor. |
| Workspace shows "Free plan" | This is a display artifact of the Analyst role's reduced permissions. The actual plan is tied to the workspace, not the user. | Restore the user's intended role (e.g., `ADMINISTRATOR`) via their Okta assignment. |
| Can't click Courier tile in Okta to log in | Courier's auth provider (AWS Cognito) does not support IdP-initiated login. | Use the [bookmark app](#creating-a-courier-bookmark-app) instead. |
| SCIM-provisioned users can't accept invites | Invite verification codes expire after 14 days. If users don't accept in time, subsequent SCIM syncs find stale invitation objects and skip re-sending. | Delete the stale invitation objects, then re-push users from Okta (remove and re-assign). Note: Okta *group* membership changes may not trigger SCIM events; use app-level assignment changes. |
| "Invite User" button missing in Courier | SCIM provisioning is enabled, which hides manual team management. | Manage users through Okta app assignments instead. |