Twilio SendGrid Single Sign-On with Okta

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 for a full list of Twilio SendGrid features available by plan.

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.

The Twilio SendGrid SAML-based Okta integration supports the following SSO features:

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

This documentation will guide you through SSO setup using the official Twilio SendGrid SAML integration available in the Okta App Catalog.

To add, delete, or modify an SSO integration, log in 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.

   Expand image

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. 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.

   Expand image

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.

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.

   Expand image

3. Search for "SendGrid", and you will see the official Twilio SendGrid Okta SAML App.

   Expand image

4. Select SendGrid to load its detail page. From the detail page, select Add.

   Expand image

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.

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.

  Expand image

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

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 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.

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.

   Expand image

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" 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.

• 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. Be sure that you do not copy and paste any extra spaces when adding the ID.

  Expand image
  Expand image

• Application username format: Email

• Update application username on: Create and update

• Password reveal: Leave this box unchecked.

  Expand image

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

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

     Expand image

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.

   Expand image

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.

     Expand image

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.

   Expand image

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.

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

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.

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.

   Expand image

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.

Expand image

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

   Expand image

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.

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.

   Expand image

5. The General Settings tab will load. You do not need to make any changes. Select Next.

   Expand image

6. The Configure SAML tab will load where you can make changes as shown below to the Attribute Statements (optional) section.

   Expand image

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

    Expand image

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.

    Expand image

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 for instructions.

If you are having trouble configuring Twilio SendGrid SSO, please submit a support ticket, and the Twilio SendGrid Support Team will be in touch.