Rate this page:

Twilio SendGrid Single Sign-On with Azure Active Directory

This guide will help you configure the Twilio SendGrid Single Sign-On (SSO) with Microsoft Azure Active Directory (AD). 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 Azure AD, Twilio SendGrid, and their relationship to one another.

  • Identity Provider (IdP): Azure 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 Azure integration supports the following SSO features:

Configuration steps

This documentation will guide you through SSO setup using the official Twilio SendGrid SAML integration available in the Azure AD Gallery.

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. You will add the Single Sign-On URL to your Azure integration as detailed in the next section of this guide. The rest of the values are provided for reference. Note that the Single Sign-On URL and Audience URL are the same.
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 an IdP configuration

Add the Twilio SendGrid application from the Azure AD Gallery

Once an SSO Integration is added to your Twilio SendGrid account, you can configure the Twilio SendGrid Azure integration in the Azure Portal. You will select the official integration from the Azure AD App Gallery.

  1. Sign in to the Azure Portal.
  2. Select Azure Active Directory from the list of services. If you do not see Azure Active Directory, try searching or go to All services.

    Azure AD Portal home page

  3. From the Active Directory page, go to Enterprise applications in the left menu.

    Add an enterprise application to Azure AD

  4. A page will load where you can select + New application at the top.

    Add a new application to Azure AD

  5. The Azure AD Gallery will load. Search for "SendGrid" and select Twilio SendGrid from the results.

    Search and select Twilio SendGrid in the Azure AD Gallery

  6. A preview with application details will appear to the right.

  7. Click Create at the bottom.

    Create the Twilio SendGrid Azure AD application

  8. The Twilio SendGrid SSO application overview page will load. Select Get started on the Set up single sign on tile.

    Set up single sign on for your integration

  9. The Single sign-on page will load. Select SAML.

    The SAML tile in your app's single sign-on setup panel

  10. A page will load where you can configure the SAML values as shown in the following sections of this guide.

Configure the Twilio SendGrid Azure application

Once the official Twilio SendGrid application is added to your Azure Portal, you will configure it to establish the SAML relationship between Twilio SendGrid and Azure AD.

  1. Retrieve the Twilio SendGrid Single Sign-on URL from the Twilio SendGrid App if you have not already done so.
  2. Click the Edit icon in the following sections of the Azure configuration page, and modify them as outlined below. You will click Save after editing each section.
Basic SAML Configuration

Note that the value is the same for both required fields because the Single Sign-on URL and Audience URL are the same for Twilio SendGrid.

  • Identifier (Entity ID): The Audience URL (SP Entity ID) provided by the Twilio SendGrid App.
  • Reply URL (Assertion Consumer Service URL): The Single Sign-on URL provided by the Twilio SendGrid App.
  • Sign on URL: Add https://app.sendgrid.com/ssologin to this optional field if you want to enable SP-initiated SSO for Twilio SendGrid.
    Add Twilio SendGrid SSO configuration values to your Azure AD application

If you have already integrated Twilio SendGrid with Azure AD 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.

Attributes & Claims

The Attributes & Claims are pre-populated for you when using the official Twilio SendGrid integration. You do not need to make any changes to this section of the SAML configuration. The following information is provided for your reference.

There are three attributes used by Twilio SendGrid: the Unique User Identifier, a FirstName, and a LastName. The FirstName and LastName attributes are required only if you enable JIT provisioning. See the JIT provisioning section of this guide for more information.

The Unique User Identifier's Name identifier format is set to Email address, and the Source attribute is set to user.userprincipalname.

Configure the Unique User ID
Unique User ID configuration values

The FirstName and LastName attributes have a Name and Source attribute. These attributes are set as shown below.

  • FirstName: user.givenname
  • LastName: user.surname
    FirstName and LastName attributes

The Unique User Identifier, FirstName, and LastName attributes are the only attributes used by Twilio SendGrid. You can optionally delete the remaining attributes that Azure AD includes during the app creation process.

Attributes & Claims menu with complete values

SAML Signing Certificate

The SAML Signing Certificate section is where you will find the X509 certificate that identifies Azure assertions to Twilio SendGrid.

  1. Download the Base64 encoded version of the certificate and open it in a text editor.
  2. You will copy the certificate to your clipboard and add it to the Twilio SendGrid App in the next section.
Set up Twilio SendGrid

The set up section contains values required by Twilio SendGrid to establish a relationship with Azure AD.

  1. Copy the following values from this section of the Azure SAML set up page. You will use them in the next section of this guide. Note that the Login URL and Logout URL are the same for this setup.
    • Login URL
    • Azure AD Identifier

Complete SAML setup with Twilio SendGrid

Once you have configured the previous settings where appropriate in your Azure integration, you must add the values provided by Azure to your Twilio SendGrid SSO configuration.

  1. You should have the following values from the Set up Twilio SendGrid section of your Azure SAML setup.
    • Login URL
    • Azure AD Identifier
  2. Return to the Twilio SendGrid App.
  3. From the page displaying your SendGrid SSO configuration, click Next.

    Add IdP Configuration page in the Twilio SendGrid App

  4. You will now add the values you retrieved from Azure as specified below.

    • SAML Issue ID: The Azure AD Identifier. This value will be a URL.
    • Embed Link: The Azure Login URL. This is Azure AD's SAML POST endpoint, and it receives requests that initiate an SSO login flow.
      The Twilio SendGrid SSO App page with complete IdP values
  5. Click Add Certificates to display a menu with an X509 Certificate field.

  6. Open the Base64 encoded X509 certificate you downloaded from Azure in a text editor and copy it to your clipboard.
  7. Paste the X509 Certificate into the X509 Certificate field in the Twilio SendGrid App and click Add Certificate.

    Add an X509 certificate to the Twilio SendGrid App

  8. Select Enable SSO to complete the configuration. You can also Save without enabling.

Your SSO configuration and integration with the Azure Active Directory IdP is now complete.

Adding users to your Azure application

Once you complete your Azure 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 Azure AD. 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 Azure AD manually (i.e., not using the official integration).

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

  1. Sign in to the Azure Portal.
  2. Select Azure Active Directory from the list of services. If you do not see Azure Active Directory, try searching or go to All services.

    Azure AD Portal home page

  3. From the Active Directory page, go to Enterprise applications in the left menu.

    Add an enterprise application to Azure AD

  4. You will see a list of your applications, including your Twilio SendGrid integration. Select it from the list.

    You Twilio SendGrid Azure AD app in a list of enterprise applications

  5. Your application's page will load. Select Get started from the Set up single sign on tile.

    Set up single sign on for your integration

  6. The SAML configuration settings will load for the Twilio SendGrid integration. Edit the Attributes & Claims section as shown below.

    The SAML SSO configuration settings page

Attributes & Claims

The one required attribute you must make sure is correct is the Unique User Identifier. The Name identifier format must be set to Email address.

  1. To edit the Unique User Identifier, click Edit on the Attributes & Claims menu.
  2. From the page that loads, click the Unique User Identifier (Name ID) field to load a details page.

    Configure the Unique User ID

  3. Verify or edit the fields as follows.

  • Name identifier format: Email address
  • Source attribute: user.userprincipalname
    Unique User ID configuration values

Additional FirstName and LastName attribute statements are needed if you enable just-in-time (JIT) provisioning. For each attribute statement, you will have a Name and Source attribute. You will set up FirstName and LastName attributes as follows.

  1. Click Edit on the Attributes & Claims menu.
  2. From the page that loads, click + Add new claim to load a configuration page.

    Add a new attribute to your integration

  3. Add the FirstName attribute with the following values.

  • Name: FirstName
  • Namespace: You can leave this field blank.
  • Source: Leave Attribute checked.
  • Source attribute: user.givenname
    The FirstName attribute settings
  1. Click Save and repeat this process to add a LastName attribute with the following values.
  • Name: LastName
  • Namespace: You can leave this field blank.
  • Source: Leave Attribute checked.
  • Source attribute: user.surname
    The LastName attribute settings

The Unique User Identifier, FirstName, and LastName attributes are the only attributes used by Twilio SendGrid. You can optionally delete the remaining attributes that Azure AD includes during the app creation process.

Attributes & Claims menu with complete values

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