# Twilio SendGrid Single Sign-On with Okta

This guide will help you configure the Twilio SendGrid SAML-based Okta integration. For additional information, such as how to edit and manage users, see the complete [Twilio SendGrid SSO documentation](/docs/sendgrid/ui/account-and-settings/sso).

Twilio SendGrid Single Sign-On (SSO) uses the widely supported [Security Assertion Markup Language (SAML 2.0)](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/auth-saml) to integrate your Twilio SendGrid user authentication with identity and access management platforms.

## Prerequisites

### Plans and pricing

Single Sign-On (SSO) is available for Twilio SendGrid Email API Pro, Premier, and Marketing Campaigns Advanced plans only. See the Twilio SendGrid [pricing page](https://sendgrid.com/pricing/) for a full list of Twilio SendGrid features available by plan.

### Terminology

Throughout this guide, you will see the following terms used to describe Okta, Twilio SendGrid, and their relationship to one another.

* Identity Provider (IdP): Okta is the IdP in this SAML relationship.
* Service Provider (SP): Twilio SendGrid is the SP in this SAML relationship.

## Supported features

The Twilio SendGrid SAML-based Okta integration supports the following SSO [features](https://help.okta.com/en/prod/Content/Topics/Reference/glossary.htm):

* IdP-initiated SSO
* SP-initiated SSO
* JIT (Just-In-Time) Provisioning

## Configuration steps

This documentation will guide you through SSO setup using the official [Twilio SendGrid SAML integration available in the Okta App Catalog](https://www.okta.com/integrations/sendgrid/).

### Add an SSO Integration to your Twilio SendGrid account

To add, delete, or modify an SSO integration, [log in](https://app.sendgrid.com/login) to the top level of your Twilio SendGrid account using your administrator credentials.

1. Navigate to **Settings > SSO Settings** in the left menu. The SendGrid App will display a page with an **Add Configuration** button.

   ![Twilio SendGrid SSO settings page with an option to add configuration.](https://docs-resources.prod.twilio.com/715f00ab88e50e64b7594498a428ec12378a3a59efee108a2fa6ebd05c7f17a5.png)
2. Click **Add Configuration**. A page will load and display the configuration fields listed in the table below.
3. Each of these fields is already preconfigured in [the official Twilio SendGrid Okta integration](https://www.okta.com/integrations/sendgrid/). Descriptions of each field are provided in the following table for your reference.
4. You need only one piece of information from this page for Twilio SendGrid's Okta integration: the SendGrid Integration ID. You can copy it from the end of either the **Single Sign-On URL** or **Audience URL**.

   ![SSO configuration showing integration ID in Single Sign-On and Audience URLs.](https://docs-resources.prod.twilio.com/3d07f4a83f25795b78e557e39027da7c69e6bf53e72b56133cd5a071d18c26f7.jpg)
5. Click **Next** to proceed to the next page in the Twilio SendGrid App. You will now go to Okta to begin setup with the Twilio SendGrid integration.

#### Twilio SendGrid SSO Metadata Field Reference

| **Twilio SendGrid SSO Metadata Field** | **Description**                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                               | A friendly name for your SAML SSO configuration.                                                                                                                    |
| **Single Sign-On URL**                 | The Twilio SendGrid URL where the IdP should `POST` its SAML assertion. The Single Sign-On URL and the Audience URL are the same when using Twilio SendGrid.        |
| **Audience URL (SP Entity ID)**        | A string identifier that defines the intended audience for the SAML assertion. The Audience URL and the Single Sign-On URL are the same when using Twilio SendGrid. |
| **SP Public Key**                      | A public key used to verify that requests are coming from Twilio SendGrid.                                                                                          |
| **Default RelayState**                 | Identifies a specific SP resource that an IdP will direct the user to following successful authentication.                                                          |
| **Name ID format**                     | The format used by an IdP when identifying a user in the SAML assertion.                                                                                            |
| **Application username**               | The default username used for the Service Provider's application. This is **Email** when using Twilio SendGrid.                                                     |

### Add the Twilio SendGrid application from the Okta App Catalog

Once an SSO Integration is added to your Twilio SendGrid account, you can configure the Twilio SendGrid Okta integration in your Okta Developer Console.

The URL for your Okta Developer Console will follow the pattern:
`<your subdomain>.okta.com/admin/dashboard`

1. Navigate to **Applications > Applications** on the left. You will see a list of active applications and a **Browse App Catalog** button.
2. Click **Browse App Catalog**.

   ![Okta Applications page with options to create app integration and browse app catalog.](https://docs-resources.prod.twilio.com/6564bf554e39f1e8cfed2e1f429574ea8b921de8d6b8c023ec3dd86f1edaa1d6.jpg)
3. Search for "SendGrid", and you will see the official Twilio SendGrid Okta SAML App.

   ![Okta integration catalog showing search results for SendGrid.](https://docs-resources.prod.twilio.com/1730d5c169556d06720f929c926bd43921c99db15d33f61cc49d16c5f4c87052.jpg)
4. Select **SendGrid** to load its detail page. From the detail page, select **Add**.

   ![Twilio SendGrid integration page on Okta with Single Sign-On and JIT provisioning.](https://docs-resources.prod.twilio.com/18602b63ff6672e97d99afe5b87cb69e297c5e732c96aa2ceac0a4c010a820a0.jpg)

#### Configure the Twilio SendGrid Okta integration

Once the official Twilio SendGrid integration is added to your Okta Developer Console, you will configure it to establish the SAML relationship between Okta and Twilio SendGrid.

##### General Settings

You can leave the form fields in the **General Settings** tab as they are when the tab loads. They are listed here for reference.

* **Application label:** **SendGrid**.
* **Application visibility:** Leave both boxes unchecked.
* **Browser plugin auto-submit:** Leave this box checked.

  ![Okta settings page showing Twilio SendGrid app settings with options for visibility and provisioning.](https://docs-resources.prod.twilio.com/715824a0bdb8bc31dbea2b1b41bf167dc60a1663c39531b51e737f6e0e3ce64b.jpg)

1. Click **Next** to load the **Sign-On Options** tab.

##### Sign-On Options

You will be able to select **SAML 2.0** or **Secure Web Authentication** as your sign on method. Select **SAML 2.0**.

1. Leave the **Default Relay State** blank.
2. You do not need to add any attribute statements. Twilio SendGrid uses FirstName and LastName attribute statements for just-in-time (JIT) provisioning. See the [JIT section of this document](#just-in-time-provisioning) to understand JIT provisioning. These attribute statements are already added for you when using the official Twilio SendGrid Okta integration. If you attempt to add them manually, an error will occur before you can complete the configuration.

> \[!NOTE]
>
> If you have already integrated Twilio SendGrid with Okta manually (i.e., not using the official integration), you can enable JIT provisioning with your current integration. See the "[Manually configuring JIT provisioning](#manually-configuring-jit-provisioning)" section for instructions.

3. Leave **Disable Force Authentication** checked.
4. In the **SAML 2.0** tab, you will see a message stating that "SAML 2.0 is not configured until you complete the setup instructions." Click **View Setup Instructions**.

   ![SAML 2.0 setup instructions button and identity provider metadata link.](https://docs-resources.prod.twilio.com/91966e5183418c07d47d55f5e0726eaf6aaed408acd4ef55a924ad7e06d47423.jpg)
5. A new page will open with instructions and information required by the Twilio SendGrid App to complete SAML setup as outlined in the "[Complete SAML setup with Twilio SendGrid](#complete-saml-setup-with-twilio-sendgrid)" section of this guide. Leave the new page open — you will return to it.
6. Before returning to the Twilio SendGrid App, complete the **Advanced Sign-on Settings** section as shown below.

##### Advanced Sign-on Settings

* **SendGrid integration ID:** This ID is specific to your SSO integration in Twilio SendGrid. You can retrieve it in the Twilio SendGrid App from the end of your Twilio SendGrid Single Sign-on URL, Audience URL, or by viewing your integration from the [Twilio SendGrid SSO Settings page](https://app.sendgrid.com/settings/sso). Be sure that you do not copy and paste any extra spaces when adding the ID.

  ![SSO configuration showing integration ID in Single Sign-On and Audience URLs.](https://docs-resources.prod.twilio.com/3d07f4a83f25795b78e557e39027da7c69e6bf53e72b56133cd5a071d18c26f7.jpg)

  ![SSO Settings page showing incomplete configuration and integration ID.](https://docs-resources.prod.twilio.com/645925cd6078885145be7d9613fbb185bfb38bd72352112df168b07ed6af3d7a.jpg)
* **Application username format:** **Email**
* **Update application username on:** **Create and update**
* **Password reveal:** Leave this box unchecked.

  ![Okta SAML 2.0 configuration with sign-on options and SendGrid integration ID field.](https://docs-resources.prod.twilio.com/d5495fe41e1fe7e3a0d462b68b70c233b7a3d5719eb27541ccc42597252a7db0.jpg)

5. Click **Done** and navigate to the page that opened when you clicked **View Setup Instructions** earlier.

### Complete SAML setup with Twilio SendGrid

After clicking **View Setup Instructions** in the previous step, a new page opened with instructions and information required by the Twilio SendGrid App to complete SAML setup. You can return to the setup instructions page in Okta by navigating to your Twilio SendGrid integration and selecting the **Sign On** tab.

1. You should copy the following values from the page.
   * **SAML Issuer ID**
   * **Embedded Link**
   * **X.509 Certificate**

     ![Instructions for entering Okta IdP values, including SAML Issuer ID and certificate details.](https://docs-resources.prod.twilio.com/8257c1c12a8af9d33215d484f8e5a54f53c861ed62fd3cca854f179b4a7ff5af.jpg)
2. Return to the Twilio SendGrid App.
3. From the page displaying your SendGrid SSO configuration, click **Next** if you have not done so already.

   ![Twilio SendGrid IdP Configuration page with SAML Issuer ID and Embed Link fields.](https://docs-resources.prod.twilio.com/ede0655552f3d99e177139279bcc93b38f4210df78706e0ebcc18fb556b2cd64.jpg)
4. You will now add the values you retrieved from Okta as specified below.
   * **SAML Issue ID:** The **SAML Issuer ID**. This value will be a URL.
   * **Embed Link:** The Okta **Embedded Link**. This is Okta's SAML `POST` endpoint, and it receives requests that initiate an SSO login flow.

     ![Twilio SendGrid IdP Configuration page with SAML Issuer ID and Embed Link fields.](https://docs-resources.prod.twilio.com/ede0655552f3d99e177139279bcc93b38f4210df78706e0ebcc18fb556b2cd64.jpg)
5. Click Add Certificates to display a menu with an X509 Certificate field.
6. Copy the **Okta X.509 Certificate** and paste it into the **X509 Certificate** field in the Twilio SendGrid App. Then, click **Add Certificate**.

   ![Interface for adding an X509 certificate in Twilio SendGrid with certificate details form.](https://docs-resources.prod.twilio.com/7bd7a238e7f4409ea0b15b99f3322fc223d08c22fb4b68bdb7586a43abc0b408.jpg)
7. Select **Enable SSO** to complete the configuration. You can also **Save without enabling**.

Your SSO configuration and integration with the Okta IdP is now complete.

## Adding users to your Okta Application

Once you complete your Okta configuration in the Twilio SendGrid App, you will be able to manage users. Twilio SendGrid calls these users Teammates.

### Just-in-Time provisioning

If you enable just-in-time (JIT) provisioning for your SSO configuration, you need only to assign users to the Twilio SendGrid App in Okta. Assigned users will be created as SSO Teammates when they log in to Twilio SendGrid for the first time.

> \[!NOTE]
>
> JIT provisioning will assign Teammates to the Twilio SendGrid parent account. It is not possible to assign JIT provisioned Teammates to Subusers.

> \[!NOTE]
>
> JIT provisioning is only possible from an IdP-initiated sign-on flow. When assigning users to your Twilio SendGrid App, you may want to instruct them to log in from your IdP the first time.

To enable JIT provisioning for your SSO configuration, you must edit the SAML configuration from the SSO settings page in the Twilio SendGrid App.

1. Edit a configuration by selecting **Settings > SSO Settings** from the left sidebar navigation. A page will load displaying all your existing IdP configurations.
2. Each configuration will have an action menu to the far right. Select this menu to display a dropdown where you can choose **Edit** or **Disable**.

   ![SSO settings page with options to edit or disable IdP configuration.](https://docs-resources.prod.twilio.com/f1f6c589e1e67ad724ea255de6224973b09cbfbed87da5656864debcf952e142.png)
3. Select **Edit** from the action menu. A page will load that allows you to modify or complete an unfinished SSO integration. In addition to the fields available during initial setup, you will have **Status** and **Just-in-Time Provisioning** toggles.

| **Twilio SendGrid SSO Metadata Field** | **Description**                                                                                                                              |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status**                             | A toggle where you can enable or disable the SSO configuration.                                                                              |
| **Just-in-Time Provisioning**          | A toggle to enable or disable just-in-time (JIT) provisioning. When JIT is enabled, you can auto provision users with read-only permissions. |

![Edit My IdP configuration with status and just-in-time provisioning enabled.](https://docs-resources.prod.twilio.com/e54c374b88ca49b3657d8d56041ec6c2c21a76780cc806a0e7695e80de82561d.jpg)

4. Click the **Just-in-Time Provisioning** toggle so that **Enabled** is shown in blue. Then, click **Save** at the bottom of the page.

   ![Edit a Twilio SendGrid IdP configuration.](https://docs-resources.prod.twilio.com/c6c7c5ffd41646b3233656cff5c88d63bffae098386ca80cdbf9c1c38db3c1f5.jpg)

The Twilio SendGrid SAML integration supports **FirstName** and **LastName** entity attributes. You can modify the values assigned to them as an administrator in the Twilio SendGrid App.

JIT provisioned Teammates will be given a Restricted Access account with permissions that correspond to Read-Only access. An administrator can modify a Teammate's permissions in the Twilio SendGrid App. See the Teammates documentation for [more about Teammate scopes](/docs/sendgrid/ui/account-and-settings/teammates#configuring-permissions).

### Manually configuring JIT provisioning

> \[!WARNING]
>
> The following JIT instructions are provided as a reference for customers who have already integrated Twilio SendGrid with Okta manually (i.e., not using the official integration).

If you already have Twilio SendGrid configured with Okta using a manually created configuration, you can add JIT provisioning by editing your existing configuration in your Okta Developer Console.

The URL for your Okta Developer Console will follow the pattern:
`<your subdomain>.okta.com/admin/dashboard.`

1. Navigate to **Applications > Applications** on the left.
2. Select your Twilio SendGrid application to load its detail page.
3. Select the **General** tab.
4. Click **Edit** in the **SAML Settings** section to load your integration's configuration settings.

   ![The Okta settings page for a manually integrated Twilio SendGrid integration.](https://docs-resources.prod.twilio.com/0728678f41e4f28553620273ffb2ce875a5e38f30c28abf1526a29f98d621c09.jpg)
5. The **General Settings** tab will load. You do not need to make any changes. Select **Next**.

   ![Form for Okta Support feedback on SAML integration configuration with options for customer type and app details.](https://docs-resources.prod.twilio.com/ff070b528cf90354187319b4be7e1ddcea09de5fe0181109e224cc7bf7a5205e.jpg)
6. The **Configure SAML** tab will load where you can make changes as shown below to the **Attribute Statements (optional)** section.

   ![Okta SAML settings with fields for Single sign on URL, Audience URI, and Name ID format.](https://docs-resources.prod.twilio.com/b36ff20480de918c39b8c4f44bf529f438bd2d6dfb524ed0bfd08421fe2c050f.jpg)

#### Attribute Statements (optional)

7. For each attribute statement, you will have a **Name**, **Name format**, and a **Value**. You will set up a FirstName and LastName attribute as follows.

* FirstName
  * **Name:** **FirstName**
  * **Name format:** **Unspecified**
  * **Value:** **user.firstName**
* LastName
  * **Name:** **LastName**
  * **Name format:** **Unspecified**
  * **Value:** **user.lastName**

    ![SAML attribute statements for first and last name with unspecified format.](https://docs-resources.prod.twilio.com/8a0e34225641859d2d348428afcfb792ff549b6ad9a1623736379746ef5f1078.jpg)

#### Group Attribute Statements (optional)

8. You can leave this section blank.
9. You do not need to do anything else with this section. Select **Next** to continue to the **Feedback** tab.
10. You can now select **Finish** on the **Feedback** tab to complete your JIT configuration update.

    ![The Okta Feedback tab in a manually integrated Twilio SendGrid integration.](https://docs-resources.prod.twilio.com/c9795bd4adb8c79c63525ca22eaa260793570cc996d62d5c3798cd0447163392.jpg)

### Additional user management steps

You can add Twilio SendGrid SSO Teammates manually, delete Teammates, and modify Teammates' permissions in the Twilio SendGrid App. See the [user management section of the Twilio SendGrid SSO docs](/docs/sendgrid/ui/account-and-settings/sso#manage-users) for instructions.

## Support

If you are having trouble configuring Twilio SendGrid SSO, please [submit a support ticket](https://support.sendgrid.com/hc/en-us), and the Twilio SendGrid Support Team will be in touch.