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.

Twilio SendGrid Single Sign-On (SSO) uses the widely supported Security Assertion Markup Language (SAML 2.0) 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 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:

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

Add an SSO Integration to your Twilio SendGrid account

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.

    Twilio SendGrid SSO settings page

  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.

    The SendGrid integration ID in the Single Sign-On URL and Audience URL

  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.

    Browse the Okta App Catalog

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

    Search for the Twilio SendGrid Okta integration

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

    The official Twilio SendGrid Okta integration landing page

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.
    General settings for the Twilio SendGrid Okta integration
  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 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.

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

  1. Leave Disable Force Authentication checked.
  2. 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.

    View Setup Instructions

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

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

    The SendGrid integration ID in the Single Sign-On URL and Audience URL
    The SendGrid integration ID on the SSO Settings Page

  • Application username format: Email

  • Update application username on: Create and update
  • Password reveal: Leave this box unchecked.
    The complete SAML 2.0 configuration setup in Okta
  1. 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
      The Okta-supplied IdP values required by the Twilio SendGrid App
  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.

    The Twilio SendGrid App's IdP Configuration page

  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.
      The Twilio SendGrid SSO IdP configuration with Okta's values
  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.

    Add an X509 certificate to Twilio SendGrid

  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.

JIT provisioning will assign Teammates to the Twilio SendGrid parent account. It is not possible to assign JIT provisioned Teammates to Subusers.

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.

    The Twilio SendGrid SSO IdP configuration action menu

  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 a Twilio SendGrid IdP configuration

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

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.

Manually configuring JIT provisioning

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

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

    Name your Okta application

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

    The Okta SAML Settings tab in a manually integrated Twilio SendGrid integration

Attribute Statements (optional)
  1. 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
      First and last name attributes and values
Group Attribute Statements (optional)
  1. You can leave this section blank.
  2. You do not need to do anything else with this section. Select Next to continue to the Feedback tab.
  3. 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

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

Support

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

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more