Oftentimes organizations use a large number of SaaS applications. And with a large number of user accounts for their employees and customers, it can get difficult for both the end user and the organization—end users have to memorize different credentials for multiple applications and organizations have to support multiple applications, and securely manage thousands of user accounts on each application.
As a result of this, organizations have been using single sign-on (SSO), which allows users to securely sign-on to multiple applications through one credential, and allows organizations to manage all accounts through a single user directory.
Both Twilio and SendGrid (now in GA) allow SSO using Security Assertion Markup Language (SAML 2.0) to integrate your Twilio and SendGrid user authentications with any identity and access management (IAM) platforms that support SAML 2.0.
For this tutorial, you are going to learn how to integrate Twilio and SendGrid accounts, account management, and user authentication all through single sign-on. The identity provider (IdP) you’ll be using to configure SSO for this tutorial is Okta.
If you are just looking to implement SSO with only Twilio or SendGrid without the other, feel free to skip to their respective integration sections: Twilio Integration, SendGrid Integration. And finish the setup in the testing section: Test SSO Connection.
If you are wanting to configure SSO with a different IdP, check out the other following tutorials:
Integrate Twilio and SendGrid Accounts through Single Sign-On with Azure Active Directory (coming soon!)
Integrate Twilio and SendGrid Accounts through Single Sign-On with SAML 2.0 (coming soon!)
Before we proceed with the tutorial, let's talk about SSO in more detail.
SSO is a method of authentication that relies on an Identity Provider (IdP)—such as Okta—to securely authenticate users to multiple applications or services with one set of login credentials. SSO also centralizes all users to a single platform where organizations can authorize roles and permissions to all users for each application.
Not only does SSO streamline the sign-in process for users and allow organizations to manage all users through one platform, it also minimizes security risks. For more information on this, check out this SendGrid blog: How Single Sign-On (SSO) Improves Your Account Security.
SSO is based on a sharing of identity attributes given by the IdP to a Service Provider (SP)—such as Twilio and SendGrid. When a user is authenticated by an IdP, they are automatically granted access to all other SP’s that are trusted with it and authorized by their organization. This trusted relationship requires a back and forth communication between the IdP and the SP through a protocol.
Twilio and SendGrid both use the Security Assertion Markup Language (SAML) protocol to securely authenticate users as it is the industry standard. Not only is SAML able to authenticate users, it’s also able to authorize user roles and permissions.
Let’s take a look at an example where a user is already authorized to use Twilio or SendGrid by their organization—where their IdP is Okta—and is attempting to sign-in. This is how the SSO authentication flow would look like:
The user will first attempt to sign-in to SendGrid or Twilio. Based on the user's email, the SP will figure out what organization they are a part of and that Okta is their IdP.
The SP will send out a SAML request in a redirect to Okta.
Okta will verify the request and will have the user sign-in. Once the user signs-in, Okta will set an SSO cookie within the user's browser so they won't have to sign-in again. In some cases, the IdP will already notice the SSO cookie in the user's browser and will skip to step 4 without asking the user for any information.
Okta generates a SAML assertion and is returned to the user's browser, which is then relayed back to the SP through another redirect.
Using a stored certificate, the SP verifies the SAML assertion and grants the user access to the service.
As referred in step 3, any subsequent sign-ins to Twilio, SendGrid or any other SPs the user is authorized to use will automatically be authenticated by the IdP without having them sign-in again.
If you want more information on how cookie and session management work with Okta, check out their documentation: Session management with Okta.
The authentication flow above is just one way an SSO authentication can start. The example and the flow above is considered a Service Provider Initiated (SP-initiated) sign-in. This is usually triggered when the user attempts to directly sign-in to the SP.
Another way where an SSO authentication can start is through the IdP - this is called an Identity Provider Initiated (IdP-initiated) sign-in. This is usually triggered when the user first signs-in to their IdP and selects their SP through the platform. This shortens the flow by removing the SAML request from the SP and will have the authentication flow start at step 3 in the diagram above.
Some SPs don’t support SP-initiated sign-ins. Both Twilio and SendGrid support SP-initiated and IdP-initiated sign-ins.
IdP-initiated sign-ins carry a security risk, so it should be avoided when possible. In this flow, SPs receive an unsolicited SAML assertion, which could have possibly been stolen and spoofed. For more information on this, check out this article: The Dangers of SAML IdP-Initiated SSO.
Now let’s take a look at how SAML is configured between the SP and the IdP and what is needed to implement it.
The assertion that is generated by the IdP is based on a configuration that's mutually agreed by both the SP and the IdP. When the SP receives the assertion, it needs to validate that it came from a valid IdP.
To validate the assertion, the SP needs an X.509 Certificate, which is given by the IdP and is stored to verify the SAML assertions. The SP also needs the IdP’s SSO URL to send SAML POST requests to receive information. The IdP will need the SP’s SSO URL, which is where the SAML responses are posted to.
Depending on the IdP and SP you choose, the SAML parameters for the configuration will be different and you may need to provide more metadata than other IdPs or SPs.
Certain SPs, such as SendGrid, support Just-in-Time (JIT) provisioning to automatically create a user account upon sign-in from their IdP. With JIT provisioning enabled, you will only need to assign users an application from their IdP and users will be created by the SP with default permissions upon signing in for the first time. This further streamlines the SSO process for organizations by not having to manually create an account for each user in each application.
This tutorial will also show how to enable JIT provisioning for SendGrid. However, if you want more details on this, check out the SendGrid documentation: Add Teammates with just-in-time provisioning.
In order to allow a user to login by SSO for Twilio for the first time, that user needs to be added to your Twilio Organization and the account needs to be created first. At this time, only SendGrid supports JIT provisioning, while Twilio does not.
An email account under your verified domain—for testing purposes. Adding users to your Twilio Organization (needed for SSO) requires their email domains be verified
Let’s get started with integrating your Twilio account with Okta. In this section, you’ll first create an organization within Twilio to configure your SSO profile. Once that’s configured, you’ll head over to your Okta admin console to create a SAML integration with Twilio. You’ll be given metadata by both Twilio and Okta to configure on each end which will then complete your SSO setup for Twilio.
To configure an SSO profile, you’ll need access to the Twilio Admin Center, which requires you to be an administrator or owner of an Organization. If you have yet to set up an Organization with your Twilio account, follow these steps and come back once you’ve created your Organization.
Head to the Twilio Admin Center, and navigate to the Single sign-on section on the left panel. Then, click on Create new SSO profile, which will be display Twilio’s metadata for the SSO configuration:
The metadata values displayed are what will be provided to Okta to configure the SAML integration. Save this tab for the next section and open a new tab to set up the SSO configuration on your Okta account.
In the new tab, sign into your developer account on Okta and head to the admin console. Select Applications>Applications on the left panel and you will be presented with this menu:
Click on Create App Integration to select the sign-in method for the Twilio integration:
Select SAML 2.0 and click Next.
Enter in Twilio Console for the App name and feel free to upload the Twilio logo as the App logo. You can download the Twilio logo here from our brand platform page.
Click Next and you’ll be presented with the SAML settings, which is where you’ll enter in the metadata given by Twilio. Here, you’ll need to do a few things:
Place the ACS/SSO URL from the Twilio metadata in the Single sign-on URL field and select the Use this for Recipient and Destination URL check box.
Place the Audience URL/Entity ID from Twilio metadata in the Audience URI (SP Entity ID) field.
From the Name ID format drop-down, select EmailAddress.
From the Application username drop-down, select Email.
Click Show Advanced Settings and ensure that the Response and Assertion Signature drop-downs have Signed selected and that the Assertion Encryption drop-down has Unencryptedselected.
The reason why Unencrypted is selected for the Assertion Encryption is because end-to-end encryption is already provided at the transport layer using the HTTPS connection.
After completing the above steps, your SAML settings will look like the following:
Click Next and you’ll be directed to the feedback section. Fill out the feedback questions and click Finish. You’ll then be redirected to your newly integrated app page:
The next step is to provide Twilio with the metadata from Okta. Click View Setup Instructions to navigate to a page that displays Okta’s IdP metadata:
Save this tab and head back over to your SSO profile on Twilio.
In this section, you’ll finish up the SAML configuration in Twilio by configuring Okta’s IdP metadata. Back in your SSO profile on Twilio click on the two check boxes at the bottom:
The check boxes are to ensure you’ve done steps 3–5 from the previous section. Click Continue and the next section will have you provide the IdP metadata given by Okta:
Select Okta in the Your Identity Provider drop-down box and enter the Identity Provider Issuer, Identity Provider Single Sign-On URL, and X.509 Certificate from the Okta metadata obtained in the previous section in their respective fields.
Click Save & Continue and the next section will be to test out the SSO connection. But before you test it out, let’s configure SSO with your SendGrid account.
If you want to just integrate Twilio with SSO and finish the setup process, feel free to skip to the testing portion of the tutorial.
This section is fairly similar to the Twilio integration. You’ll create the integration with your SendGrid account and then with your Okta account. The last step will be to configure the metadata given by both SendGrid and Okta on each other’s end.
SendGrid provides two methods of configuring SSO with Okta: Adding the official SendGrid app integration through Okta’s app library (coming soon!), or manually creating the SendGrid integration (like how it was for the Twilio Integration).
We recommend adding the official app integration through Okta’s app catalog as this simplifies the configuration process. However, since the official SendGrid app integration is not in Okta yet, this section will show how to integrate it manually.
Sign into your SendGrid dashboard and click on the Settings drop-down in the left panel:
You should see SSO Settings within the drop-down. However, if it's not present, ensure your account has either been upgraded to the Pro, Premier, or Advanced Marketing Campaigns plan. Check out the SendGrid docs on Upgrading your Planfor more info.
Click on SSO Settings and click Add Configuration. You’ll then be presented with your SendGrid SAML metadata:
Save this tab and open your Okta admin console on another browser tab.
The next few steps are similar to what we did in the Twilio integration. If you get lost, feel free to follow along and view the screenshots in that section.
Head to Applications>Applications on the left panel. Click on Create App Integration, select SAML 2.0 and click Next.
Enter in SendGrid for the App name and feel free to upload the SendGrid logo as the App logo. You can download the SendGrid logo here from our brand resources page.Click Next and you’ll be presented with the SAML settings, which is where you’ll enter in the metadata given by SendGrid.
Head back to the IdP configuration in SendGrid and grab the Single Sign-On URL and the Audience URL (SP Entity ID). Back in the Okta tab, place these two values in their respective fields. Leave the Use this for Recipient URL and Destination URL check box selected and within the Application username check box, select Email. Leave every other setting to its default value and your SAML settings should look like this:
For this tutorial, we’ll also showcase how to enable Just-in-Time (JIT) provisioning for SendGrid. Assigned users will be created as SSO Teammates when they log into Twilio SendGrid for the first time. To enable this, we’ll need to configure the Attribute Statements within the SAML settings.
Scroll down to the attribute statements section and you’ll notice the Name, Name Format, and Value fields. You'll need to add two attributes: one for the first name and another for the last name. For the first name attribute: enter FirstName for the Name, select Unspecified for the Name Format, and enter user.firstName for the Value. For the last name attribute: enter LastName for the Name, select Unspecified for the Name Format, and enter user.lastName for the Value.
After entering the attributes, your Attributes Statements section will look like the following:
Make sure to add these attributes in Okta—without it, SendGrid will assign the name Unknown to both.
You are now finished with setting up the SAML settings for SendGrid in Okta. Scroll down, click Next and you’ll proceed to the feedback section. Follow the instructions given by Okta to fill out the feedback section, click Finish and you’ll be directed to the Sign On tab for your newly created SendGrid application:
The last step is setting up SAML metadata from Okta to your SSO configuration in SendGrid. Click View Setup Instructions and you’ll be provided with the Identity Provider Single Sign-On URL, Identity Provider Issuer, and X.509 Certificate, which you will add to SendGrid. Save this tab and head back to the IdP configuration setup in SendGrid.
Within the IdP configuration setup in SendGrid, click Next and you’ll see where to input the given metadata values from Okta into SendGrid:
Place the Identity Provider Issuer from the Okta metadata into the SAML Issuer ID field and place the Identity Provider Single Sign-On URL into the Embed Link field.
Click Add Certificate and a tab will appear on the right side of the screen. Paste in the X.509 Certificate given by Okta within the text box and click Add Certificate. Once you’re finished adding all of the metadata values, click Enable SSO and you’ll be directed to the SSO settings menu with the completed IdP configuration you just setup.
Now in order to enable JIT provisioning, you’ll need to click on the three dots (...) next your new IdP configuration and click Edit:
Once you’re in the editing menu, click the Enabled switch under the Just-in-Time Provisioning label:
Scroll down and click Save. The next and last step for this tutorial is testing out the SSO connection for both Twilio and SendGrid applications.
Now that the setup is completed with Twilio and SendGrid on Okta, let’s assign both applications to a user within your organization and see how the SSO process looks like.
Before you test it out and proceed, ensure you have access to an email under your verified domain and follow these steps to add that email as a user to your Twilio Organization. Once added, login to your email inbox and follow the steps given by Twilio to complete your account. Since JIT provisioning is enabled for SendGrid, you won’t need to add this user as a Teammate to your SendGrid account.
Within these next sections, you’ll be adding the test user to Okta and then authorizing them in the Twilio and SendGrid applications. Lastly, you’ll test out the connection by signing into both applications as the test user.
Head back to your Okta admin console and access the People page by clicking Directory > People on the left tab:
Then click on Add Person and fill out the form for your test user. Select the Send user activation email now check box—this will automatically activate the user and send them an email to complete their Okta account setup—and click Save.
You’ll notice you also have an option to add this user to a group. Managing user access individually, especially when assigning applications to users in bulk, can be time-consuming. Creating and assigning users to groups makes this process much easier. For more information on groups, check out the Okta docs: About Groups.
Now that you have a user within your Okta directory, let's assign them to the SSO applications you just integrated.
Click on the user’s name you just added and you’ll be directed to the applications tab of their profile. Click on Assign Applications and you’ll see a list of the SSO applications you’ve set up:
Click Assign on one of the applications and you’ll be prompted to enter a user name for them for that application. This field should already have their email as their username (since that's how it was set up in the SAML integration for both applications). Click on Save and Go Back and repeat the steps for the other application.
Since the test user is now assigned both applications, let’s finish the account setup for this user. Sign into your test user’s email inbox and find the email from Okta that was sent earlier to complete the account setup. Click on Activate Okta Account, enter in a password and click on Reset Password to complete the setup. You’ll then be redirected to the Okta portal as a nonadministrative user.
Now that the Twilio Console and SendGrid applications have been assigned to your test user, let's test out the SSO process!
In the Twilio integration section, we were left off at testing the connection from the SSO profile that was being set up. Sign back in as the organization owner/administrator in Twilio, head back to the SSO section in the admin center and click on your SSO profile:
Enter in the test user’s email address (which should already be set up and a part of your Twilio Organization) and click Send Email. Head back to your test users email inbox and you’ll see this email from Twilio:
The email will ask you to test out the SSO process by signing into Twilio, which will then redirect you to your IdP (Okta) to sign-in and will lastly redirect you to your Twilio Console—this process is called an SP-initiated sign-in. Let’s see how it works!
SP-initiated SSO
Click on clicking on this link in the email, type in your test users email into Twilio, and sign into Okta with the test users account. You will then be successfully signed into your Twilio Console! The SP-initiated SSO process should have gone like this:
Now sign out and sign back to Twilio as the organization owner and head back to the SSO profile to complete the setup:
Click I already tested this connection, and you’ll proceed to enforce SSO on users that belong to your verified domain. Enter your domain in the field and click Enforce SSO. You’ll be asked one more time to enforce SSO and to verify it. Click on the verification check box and click Enforce SSO, which will complete the SSO setup for Twilio.
Now let's test out SSO and JIT provisioning with SendGrid! JIT provisioning is only possible from an IdP-initiated sign-on flow, so you’ll sign back on to Okta as the test user to test it out.
IdP-initiated SSO with JIT provisioning
Once you’re signed into Okta, click on the SendGrid tile and you’ll be signed in with your account, which will automatically be set up on SendGrid:
After your very first sign-in to SendGrid (with JIT provisioning enabled), you’ll also be able to sign in directly through SendGrid.
Ta-da! You have officially set up and integrated your Twilio and SendGrid accounts all through single sign-on. Not only does this streamline the sign-on process for users within your organization, but it also allows you to provision and manage your users all through one platform.
I hope you enjoyed this tutorial and learned a few things about SSO along the way! So now what’s next? For Twilio, you can learn more about Organizations, managed users, and roles, and for SendGrid, you can learn more about Teammates and Subusers and how they can help you manage your users. Happy building!
