Twilio SendGrid Single Sign-On with Azure Active Directory

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.

   

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.

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.

   

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

   

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

   

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

   

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

7. Click Create at the bottom.

   

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

   

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

   

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

  

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.

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

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

  

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.

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.

   

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.

     

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.

   

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.

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.

   

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.

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

   

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.

   

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

   

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

   

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

   

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

   

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.

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.

   

9. Verify or edit the fields as follows.

• Name identifier format: Email address
• Source attribute: user.userprincipalname

  

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.

    

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

  

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

  

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.