New with Fonolo is the ability to integrate your SAML2 Single Sign On with the Fonolo Portal. This guide will walk you through setting up Fonolo’s SSO with okta.
1. Add Fonolo as an App
After logging in as an Administrator into okta, start by going to Directory (1), then click on Applications (2).
Click the green Add Application button (1) in the top right.
Click the green Create New App button (1) in the top right in order to create the Fonolo App.
In the popup shown below, ensure that Web is selected (1), and that SAML 2.0 is chosen as the Sign on Method (2). Then click the green Create button (3) at the bottom.
For the App Name (1), enter Fonolo (or similar). Optionally, you can add the Fonolo logo (2) for your users to see when they are logged into okta.
You can click and save the following image to use as the logo:
Click on the green Next button (3) to continue.
On the Configure SAML tab, the fields in your okta account should be filled out exactly as they are in the example shown below (1).
- Single sign on URL – https://portal.fonolo.com/saml
- Use this for Recipient URL and Destination URL CHECKED
- Allow this app to request other SSO URLs UNCHECKED
- Audience URI (SIP Entity ID) – https://portal.fonolo.com/saml/metadata
- Name ID Format – EmailAddress
- Application Username – Email
- Update Application Username on – Create and Update
Open the Advanced Settings link (2) to continue the configuration.
In the Advanced Settings section, your configurations should match the same settings shown in the below example (1).
- Response – Signed
- Assertion Signature – Signed
- Signature Algorithm – RSA-SHA256
- Digest Algorithm – SHA256
- Assertion Encryption – Unencrypted
- Enable Single Logout – UNCHECKED
- Authentication Context Class – x.509 Certificate
- Honor Force Authentication – Yes
- SAML Issuer ID – http://www.okta.com/$(org.externalkey)
Here, we will federate Okta user profile field values to SAML attributes. The Service Provider (in this case, Fonolo) will use the federated SAML attribute values accordingly. In the Attributes Statements, add the following 4 lines, as per the screenshot below (1).
Once you have entered the Attributes, click the green Next button (2) at the bottom to continue.
On the Feedback step, you can select whichever options apply to your particular case (1). Once finished, click the green Finish button (2) to complete the Application building process.
Sign On Methods
Now that the Application has been created, click on the grey View Setup Instruction (1) to get the URLs and certificate that will be used on the Fonolo side to finish the SSO integration.
Copy and paste the Identity Provider Single Sign-On URL (1), and the Identity Provider Issuer URL (2) into a notepad to use later in the Fonolo Portal.
Click the grey Download Certificate button (3) to download the certificate file to use later in the Fonolo Portal.
Next, click on the Assignments tab (1). Here, you will assign this new Application to other okta Portal Users so that they have access to the Fonolo Application. Click the green Assign button (2), and then click Assign to People (3).
Select the Users you wish to have access to the Fonolo Application (1). Then click the Done button at the bottom of the popup (2).
Next, you need to define the fields that exist within your okta user profiles for Fonolo. Start by going to Directory (1), then click on the Profile Editor (2).
Click on the grey Profile button (1) under the Fonolo App that you created.
Next, click the Add Attribute button (1).
Fonolo uses a unique field, called Fonolo Role, to determine what level of access a user has within the Fonolo Portal. Here we will define this field in okta. Fill out the corresponding fields exactly as shown below.
- (1) Data Type – String
- (2) Display Name – FonoloRole (no space, capitalized)
- (3) Variable Name – FonoloRole (no space capitalized)
- (4) Description – User type in the Fonolo Portal
- (5) Enum – CHECKED
- (6) Attribute Members –
Display Name Value StatsOnly StatsOnly StandardUser StandardUser AccountManager AccountManager
Once completed, click the green Save button (7) at the bottom of the popup.
Click the Add Attribute button again, and continue to add the following 3 fields (First Name, Last Name, Email), exactly as shown below. You can click on the following images to expand them.
Once all 4 Attributes have been defined and are displayed on the page (1), click Map Attributes (2) to continue.
Under the “Okta to Fonolo” section (not “Fonolo to Okta”), select the corresponding okta fields (1) that you previously defined when setting up the Fonolo App. Map them to the appropriate Fonolo User Profile fields on the right, ensuring that you also select “Apply mapping on user create and update” in the drop down lists (2). This will ensure that any changes made on the okta side will always reflect on the Fonolo side. Once complete, click the green Save Mappingsbutton (3) at the bottom of the page.
If prompted with an option asking, “Do you want to apply these mappings to all users with this profile?”, click the green Apply Updates Now button (1).
4. Fonolo Portal Setup
Next is to configure the Fonolo Portal for SSO. You will need to be logged in as an Account Manager in the Fonolo Portal. Start by going to Admin (1), then click on Settings (2).
Next, click on the Security Tab (1).
Then, click on Single Sign-On (1).
Start by clicking the green Add Single Sign-On Profile button (1) in the top right.
Using the example below, start by giving the SSO Profile a label (1) for reference within the Fonolo Portal. Copy the Identity Provider Issuer URL you had previously saved from the okta Portal, and enter it in the next field (2). The Identity Provider Single Sign-On URL from the okta Portal will go into the SAML Endpoint field (3) next.
Click the Browse button (4) and select the certificate that you had downloaded from the okta Portal. It should upload and process automatically. Request Binding (5) should be set as HTTP Redirect.
Lastly, in the Email Domains field (6), list out the domains of the corporate email addresses that your Users will use. These should not be webmail address (gmail, hotmail, etc.) and should only include your corporate domains.
Account Creation and Account Update should checked by default, and will allow you to automatically generate and update Fonolo User Accounts during SSO login.
The Required Attributes can be left as the default settings unless further customization is needed. You can now save the profile, and SSO setup is complete.
5. Testing Login
To test out the new SSO connectivity, log in as a user in the okta Portal that you have added the App to.
Click on the Fonolo Portal Login App (1), and you should be redirected in a new tab to the Fonolo Portal, logged in as the user type specified in the okta Portal.