Twilio SendGrid Single Sign-On with Azure Active Directory

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

The Twilio SendGrid SAML-based Azure 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 Azure AD Gallery.

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

Expand image

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.

   Expand image

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

   Expand image

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

   Expand image

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

   Expand image

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

7. Click Create at the bottom.

   Expand image

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

   Expand image

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

   Expand image

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

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.

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: This field is optional and should be left blank. If you are using just-in-time provisioning to create your Teammates, you must leave this field blank.

  Expand image

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.

Expand image

Expand image

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

• FirstName: user.givenname

• LastName: user.surname

  Expand image

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.

Expand image

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.

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

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.

   Expand image

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.

     Expand image

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.

   Expand image

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.

Once you complete your Azure 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 Azure AD. 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 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.

   Expand image

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

   Expand image

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

   Expand image

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

   Expand image

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

   Expand image

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.

7. To edit the Unique User Identifier, click Edit on the Attributes & Claims menu.

8. From the page that loads, click the Unique User Identifier (Name ID) field to load a details page.

   Expand image

9. Verify or edit the fields as follows.

• Name identifier format: Email address

• Source attribute: user.userprincipalname

  Expand image

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.

10. Click Edit on the Attributes & Claims menu.

11. From the page that loads, click + Add new claim to load a configuration page.

    Expand image

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

  Expand image

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

  Expand image

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.

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.