Skip to contentSkip to navigationSkip to topbar
On this page

SendGrid Single Sign-On


Twilio SendGrid Single Sign-On (SSO) uses the widely supported Security Assertion Markup Language (SAML 2.0)(link takes you to an external page) to integrate your Twilio SendGrid user authentication with identity and access management platforms such as Okta(link takes you to an external page) and Microsoft Azure Active Directory(link takes you to an external page).

This documentation provides an overview of Twilio SendGrid's SSO offering and configuration steps to set up SSO for any IdP that supports SAML 2.0. We also provide the following IdP-specific configuration guides.


Twilio SendGrid IdP guides

twilio-sendgrid-idp-guides page anchor


Plans and pricing

plans-and-pricing page anchor

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(link takes you to an external page) for a full list of Twilio SendGrid features available by plan.

  • Identity Provider (IdP)

    • Services such as Okta, Azure Active Directory, and Duo.
  • Service Provider (SP)

    • Twilio SendGrid is the SP in the SAML relationship.

SSO and SAML terminology is defined throughout this document. One IdP often uses different terminology from another to label the same required fields. This document attempts to clarify and call attention to the alternative terminology used by IdPs whenever possible.

Because terminology can vary among IdPs, you may find the following high level overview helpful. There is also a table at the end of this document that maps different IdP terminology to the correct Twilio SendGrid fields.

Values created by Twilio SendGrid

values-created-by-twilio-sendgrid page anchor

Your IdP will usually require one value from Twilio SendGrid: the Single Sign-On URL. This URL tells your IdP where to send its SAML assertion. This URL is also the value set for the Audience URL (SP Entity ID).

Values created by the IdP

values-created-by-the-idp page anchor

Twilio SendGrid will need three values from your IdP: a SAML Issuer ID, a login URL, and an X509 certificate.

The SAML Issue ID is a string — usually a URL — that identifies the SP (Twilio SendGrid) to the IdP when making SSO requests. The login URL is your IdP's SAML endpoint — it receives the SSO requests. The X509 certificate is used to identify and verify requests from your IdP.


SSO Settings and configuration steps

sso-settings-and-configuration-steps page anchor

Access and manage your SSO settings

access-and-manage-your-sso-settings page anchor

The Twilio SendGrid SSO settings menu(link takes you to an external page) allows you to configure integrations with your IdP(s). Managing users and permissions is covered in the user management section of this document.

Add a Twilio SendGrid SSO Configuration

add-a-twilio-sendgrid-sso-configuration page anchor

Adding an SSO configuration requires some back-and-forth between the Service Provider (Twilio SendGrid) and your IdP. The Twilio SendGrid App will provide values required by your IdP. Likewise, your IdP will provide values required by Twilio SendGrid. This document will cover the exchange in sections, beginning from the Twilio SendGrid App.

Twilio SendGrid Service Provider settings

twilio-sendgrid-service-provider-settings page anchor

To add, delete, or modify an SSO integration, log in(link takes you to an external page) to the top level of your Twilio SendGrid account using your administrator credentials.

  1. Once logged in, navigate to Settings > SSO Settings. 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 following configuration values needed by your IdP.

  3. You will add the Single Sign-On URL to your IdP.

    • Depending on your IdP, some of the other fields may be required. If you enable just-in-time (JIT) Provisioning, your IdP will also require FirstName and LastName attributes. See the JIT section of this page for JIT configuration details.
Twilio SendGrid SSO Metadata FieldDescription
NameA friendly name for your SAML SSO configuration.
Single Sign-On URLThe Twilio SendGrid URL where your 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 KeyA public key used to verify that requests are coming from Twilio SendGrid.
Default RelayStateIdentifies a specific SP resource that an IdP will direct the user to following successful authentication.
Name ID formatThe format used by an IdP when identifying a user in the SAML assertion.
Application usernameThe default username used for the Service Provider's application. This is Email when using Twilio SendGrid.
Add an IdP configuration.

Once you have added the previous settings where appropriate in your IdP, your IdP will provide the values necessary to complete the setup in the Twilio SendGrid App.

  1. From the page displaying your SendGrid SSO configuration, click Next. A page will load and display the following SAML fields.
IdP Metadata FieldDescription
SAML Issuer IDAn identifier — usually a URL — provided by your IdP to identify the Service Provider in the SAML interaction. Your IdP may call this an "Entity ID", "Identity Provider Issuer", "Azure AD Identifier", or other identifier.
Embed LinkThe IdP's SAML POST endpoint. This endpoint should receive requests and initiate an SSO login flow. Your IdP may call this the "Identity Provider Single Sign-On URL", "Login URL", or some other authentication URL.
CertificatesThis X509 certificate is used by Twilio SendGrid to verify that SAML requests are coming from an IdP it knows and trusts.
  1. Copy the values from your IdP to the appropriate fields in the Twilio SendGrid App.

    Add values from your IdP to the Twilio SendGrid configuration.
  2. Click Add Certificates to load the configuration menu. The loaded modal will have one field labeled X509 Certificate.

  3. Paste the certificate provided by your IdP into the X509 Certificate field and click Add Certificate. The modal will close after you click Add Certificate.

    Add an X509 certificate to a Twilio SendGrid SSO integration.
  4. Select Enable SSO to complete the configuration. You can also Save without enabling.

Your SSO configuration should now be complete. You can follow the next steps in this document to edit or delete a configuration. You can also skip to the user management section to begin onboarding SSO users.

Disable or enable an SSO IdP Configuration

disable-or-enable-an-sso-idp-configuration page anchor
  1. Toggle the state of a configuration by selecting Settings > SSO Settings from the left sidebar navigation of the Twilio SendGrid App. 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. Selecting Disable will load a modal asking you to confirm your decision. Disabling a configuration will inactivate the configuration but will not delete it. Once disabled, any SSO users whose access is tied to the configuration will no longer be able to authenticate with Twilio SendGrid

    Temporarily disable a Twilio SendGrid IdP configuration.
  4. To reenable a configuration, select the action menu. For any disabled configuration, you will see the options to Edit or Enable.

  5. Selecting Enable will reactivate the configuration for any Teammates assigned to it.

Edit or delete an SSO IdP configuration

edit-or-delete-an-sso-idp-configuration page anchor
  1. Edit or delete 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 FieldDescription
StatusA toggle where you can enable or disable the SSO configuration.
Just-in-Time ProvisioningA toggle to enable or disable just-in-time (JIT) provisioning. When JIT is enabled, you can auto provision users with read-only permissions. See the just-in-time provisioning section of this doc for more information.
  1. After modifying any of the fields in your configuration, select Save at the bottom of the page.

  2. To delete the configuration, select Delete My IdP configuration.

    Edit a Twilio SendGrid IdP configuration.
  3. Selecting Delete My IdP configuration will load a modal asking you to confirm the deletion. Check the confirmation box and select Delete.

    Permanently delete a Twilio SendGrid IdP configuration.

Once you have successfully enabled an SSO IdP configuration, you will need to add SSO users to the account. Twilio SendGrid calls these users Teammates.

SSO Teammates vs Password Teammates

sso-teammates-vs-password-teammates page anchor

An account administrator can add two types of Teammates to an account: SSO Teammates and Password Teammates.

Password Teammates will log in with a username, password, and Twilio SendGrid 2FA. This documentation covers the SSO Teammate setup only. For more information about our Teammates feature, see the dedicated Teammates documentation.

(warning)

Warning

A Teammate can either be a Password Teammate or an SSO Teammate but not both.

Twilio SendGrid does not currently offer a migration tool that will convert existing Teammates to SSO Teammates. You must manually delete a Password Teammate and add them back as an SSO Teammate.

(information)

Info

Twilio SendGrid requires Two-factor Authentication (2FA) to access its services. Configuring 2FA for SSO Teammates should not be done in the Twilio SendGrid App. You will manage any 2FA requirements for your SSO Teammates in your IdP. For example, the Okta or Duo apps may be configured to send Push or SMS notifications.

As an administrator of a parent Twilio SendGrid account, you can assign SSO Teammates to the parent account or a selection of Subusers.

(information)

Info

Only administrators on a Twilio SendGrid parent account can access both the Twilio SendGrid parent account and Subusers.

Think of Subusers as separate Twilio SendGrid sub-accounts that are tied to a single parent account. Each Subuser can have its own authenticated domains, IP addresses, and Teammates. However, all billing for the Subusers will roll up to their parent Twilio SendGrid account. Subusers are helpful for several use-cases. For example, a parent account may create one Subuser for transactional email and another for marketing email. A service integrator may create a Subuser for each client they serve.

Think of Teammates like users on a single Twilio SendGrid parent or Subuser account. When adding Teammates to your parent account, which is configured with your SSO IdP, you will elect to give the Teammate access to the parent account or a selection of Subusers.

See the Subusers documentation to learn more about Twilio SendGrid Subusers and how to manage them.

Add Teammates with just-in-time provisioning

add-teammates-with-just-in-time-provisioning page anchor

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

(information)

Info

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

(information)

Info

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 FieldDescription
StatusA toggle where you can enable or disable the SSO configuration.
Just-in-Time ProvisioningA toggle to enable or disable just-in-time (JIT) provisioning. When JIT is enabled, you can auto provision users with read-only permissions. See the just-in-time provisioning section of this doc for more information.
  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 — be sure to include them. Without the first and last name attributes, Twilio SendGrid will assign the name Unknown to both. These attributes will have the values "user.firstName" and "user.lastName", "user.givenname" and "user.surname", or something similar depending on your IdP.

You can modify a Teammate's first and last names as an administrator in the Twilio SendGrid App, but we recommend that you include the appropriate name values initially.

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.

A Teammate can be added to a parent account, a single Subuser, or multiple Subusers.

Add a Teammate to a parent account

add-a-teammate-to-a-parent-account page anchor
  1. To add a Teammate, navigate to Settings > Teammates. A page will load displaying any existing Teammates. If there are no existing Teammates, you will see a "Get started creating teammates" message.
  2. Click Add Teammate > Add SSO teammate.
Add a Teammate.
  1. A menu will load and display the following fields required to create the Teammate.
Teammate Configuration FieldDescription
Teammate's Email AddressTwilio SendGrid will use this email address as the primary identifier when authenticating the SSO user. For this reason, a Teammate's email address must match the address you assign it in your IdP, and the address cannot be changed after you create it. If a single user must access multiple accounts, you will need to configure your IdP to pass through a unique email address for each account+user pair; these unique email addresses must be added as SSO Teammates in the Twilio SendGrid App.
Teammate's First NameThe Teammate's first name.
Teammate's Last NameThe Teammate's last name.
  1. At this point, you must select whether your Teammate should be granted access to the parent account or a selection of Subusers. To grant the Teammate access to the parent account, select Add to this parent account and select Next.
  2. When granting an SSO Teammate access to the parent account, you will be taken to a second menu where you can give the Teammate admin, read-only, or restricted access permissions. See the Teammates documentation for more about Teammate scopes.
Configure a Teammate's permissions.

Add a Teammate to multiple Subusers

add-a-teammate-to-multiple-subusers page anchor

You may give a Teammate access to multiple Subusers from the parent account. When adding a Teammate to multiple Subusers from the parent account with the SendGrid application user interface (UI), they will be given administrator access to each Subuser. If you prefer to give a Teammate restricted access to multiple Subusers, you can do so with the Single Sign-On Teammates API.

Multiple Subuser access with the SendGrid application UI
multiple-subuser-access-with-the-sendgrid-application-ui page anchor

To add a Teammate to multiple Subusers from the parent account, follow steps 1 through 3 in Add a Teammate to a parent account section above. Then, proceed with the instructions below.

  1. At this point, you must select whether your Teammate should be granted access to the parent account or a selection of Subusers. To grant the Teammate access to a selection of Subusers, select Add to specific subuser account and select Next.
  2. Select the specific Subusers you want to make available.
  3. Click Save to finish creating the Teammate.
Multiple Subuser access with the SendGrid Single Sign-On Teammates API
multiple-subuser-access-with-the-sendgrid-single-sign-on-teammates-api page anchor

To add a Teammate to multiple Subusers with restricted access, see the Single Sign-On Teammates operations for details. General steps are provided below.

  1. When creating or editing a Teammate, set the has_restricted_subuser_access Boolean property to true.
  2. In the subuser_access array, define an object for each Subuser the Teammate should have access to.
  3. In each object:
    1. Include a Subuser ID in the id property to grant the Teammate access to that Subuser.
    2. Set the permission_type property to restricted.
    3. Provide a persona or the individual permissions the Teammate should be granted in the scopes array.

See Teammate Permissions for more information about the personas and scopes that may be given to a Teammate. See the Single Sign-On Teammates API reference for detailed API information.

Add a Teammate to one Subuser

add-a-teammate-to-one-subuser page anchor

To grant restricted permissions to a single Subuser account using the SendGrid application UI, you can add an SSO Teammate to the specific Subuser after switching into the desired Subuser's account.

  1. Click your account user at the top left of the navigation sidebar to display a dialog. Click Change Account in the dialog.
Change accounts to log in as a Subuser.
  1. A page will load displaying any existing Subusers.
  2. Click Log In beside the Subuser to which you want to add the Teammate. You will then be logged in to the SendGrid Subuser's account.
  3. You can now add a Teammate to the specific Subuser. The process follows the same steps listed in the "Add a Teammate to a parent account" section of this page.
  4. Because you are adding the Teammate directly from the context of the Subuser's account, you can assign the Teammate admin, read-only, or restricted access permissions for the Subuser. See the Teammates documentation for more about Teammate scopes.

Existing Teammates can be edited from the Settings > Teammates page of the Twilio SendGrid App.

  1. On the Teammates management page, each Teammate will have an action menu on the far right. Click the action menu to reveal Edit and Delete options.

    Edit an existing Twilio SendGrid Teammate.
  2. Selecting Edit from the action menu will load a sidebar modal with the same fields that were present when adding the Teammate. You can edit any of the fields except the Teammate's email address, which cannot be changed after the Teammate is created.

Existing Teammates can be deleted from the Settings > Teammates page of the Twilio SendGrid App.

  1. On the Teammates management page, each Teammate will have an action menu on the far right. Click the action menu to reveal Edit and Delete options.

    Edit an existing Twilio SendGrid Teammate.
  2. Select Delete from the action menu to load a modal asking you to confirm the deletion. Click Confirm.

    Confirm deletion of a Twilio SendGrid Teammate.

User authentication flow

user-authentication-flow page anchor

User authentication can be initiated in two ways: from the Service Provider or from the IdP. We call these SP-initiated and IdP-initiated authentication flows respectively.

SP-initiated authentication flow

sp-initiated-authentication-flow page anchor

The SP-initiated flow occurs when a user authenticates directly with the Twilio SendGrid App.

When a user enters their email address, Twilio SendGrid performs a check and redirects any email address associated with an SSO account to the SSO login page. Users will then authenticate by entering their IdP credentials.

IdP-initiated authentication flow

idp-initiated-authentication-flow page anchor

The IdP-initiated flow occurs when a user authenticates with their IdP. For example, a user may click on the SendGrid app tile from Okta. This flow will authenticate the user and redirect them to the Twilio SendGrid App.

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 if you have enabled JIT.


Because SAML values are often labeled differently from one IdP to another, the following table attempts to map IdP-specific labels to the Twilio SendGrid labels for common IdPs. Note that the Twilio SendGrid Single Sign-On URL and Audience URL (SP Entity ID) are the same URL.

AzureOktaOneLogin
Azure IdP LabelTwilio SendGrid Label
Reply URL (Assertion Consumer Service URL)Single Sign-On URL
Identifier (Entity ID)Audience URL (SP Entity ID)
Azure AD IdentifierSAML Issuer ID
Login URLEmbed Link

Does Twilio SendGrid encrypt the SAML assertion?

Twilio SendGrid does not encrypt the SAML assertion itself. However, all information is sent over HTTPS.

Can a user be both an SSO Teammate and a Password Teammate?

A Teammate cannot be both a Password and SSO Teammate. They must be added as one or the other. If you want to change the way a Teammate accesses Twilio SendGrid, you must delete them and add them back as the other type of Teammate.


  • When configuring your IdP integration, you can set the Name ID Format to "emailAddress" if leaving it unspecified causes an error.
  • When enabling just-in-time provisioning, you should give the IdP FirstName and LastName entity attributes to properly set up the Teammate's first and last names. These will have the values "user.firstName" and "user.lastName", "user.givenname" and "user.surname", or something similar depending on your IdP.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.