Enabling Single Sign-On with Okta for administrator access

With Soapbox, you have the ability to enable single sign-on with Okta as the identity provider so that Okta users can login to the Soapbox administrator using their Okta account credentials.

Step 1: Create an Application in Okta

To set up single sign-on, you will first need to create a new App Integration in your Okta account. When creating this app integration in Okta, follow the steps below.

1. Go to Okta console > Applications > Applications, and click the blue Create App Integration button
2. In the "Create a new app integration" modal, select "SAML 2.0" and click the Next button
3. On the "Create SAML Integration" page, in the "General Settings" section, for "App name" use "Soapbox Engage", and click the Next button
4. On the "SAML Settings" section, fill in the following values, and click the Next button
   1. Single sign-on URL:  https://{your Soapbox domain}/saml/default-sp
   2. Audience URI (SP Entity ID):  https://{your Soapbox domain}/saml/default-sp
   3. Default RelayState:  https://{your Soapbox domain}/administrator/index.php?option=com_login&task=saml
   4. Name ID format:  EmailAddress
   5. Application username:  email
   6. Update application username on:  Create and update
5. On the "Help Okta Support understand how you configured this application" section, for "App type" check the box "This is an internal app that we have created", and click the Finish button.
    

For reference, here is a full overview of every possible value, please refer to the following SAML Settings of your Okta app integration.
Single Sign On URL: https://{your Soapbox domain}/saml/default-sp

Examples of custom and default prefix domains include the following:

https://www.example.org/saml/default-sp
https://act.example.org/saml/default-sp
https://example.secure.nonprofitsoapbox.com/saml/default-sp
Recipient URL:  https://{your Soapbox domain}/saml/default-sp
Destination URL:  https://{your Soapbox domain}/saml/default-sp
Audience Restriction:  https://{your Soapbox domain}/saml/default-sp
Default Relay State:  https://{your Soapbox domain}/administrator/index.php?option=com_login&task=saml
Name ID format: EmailAddress
Response:  Signed
Assertion Signature:  Signed
Signature Algorithm:  RSA_SHA256
Digest Algorithm:  SHA256
Assertion Encryption:  Unencrypted
SAML Single Logout:  Disabled
SAML Signed Request:  DIsabled
authnContextClassRef:  PasswordProtectedTransport
Assertion Inline Hook:  None (disabled)
SAML Issuer ID:  http://www.okta.com/${org.externalKey}
Audience URI (SP Entity ID): https://{your Soapbox domain}/saml/default-sp
Application Username: email

Step 2: Assign users or groups to your Application in Okta

On the Assignments tab of your new Okta Application, add all users or groups you wish to be able to login to Soapbox via Okta.

Step 3: View Setup Instructions in Okta

Once you have created your Application in Okta and assigned users, you'll need to access the configuration details in Okta that you will enter in Soapbox Engage. To do so, go to the Sign On tab of the Okta application and click the blue "View SAML setup instructions" on the right side of the page. Keep the tab that opens available as you move to the next step.

Step 4: Configure Single Sign-On for Okta in Soapbox

To configure Single Sign-On for Okta in Soapbox:

• Login to your Soapbox administrator
• Go to Single Sign-On
• On the Service Provider Setup tab, for Enable Admin Single Sign-on, select Yes
• For Identity Provider Entity ID, enter the Identity Provider Issuer from the Okta Application Setup Instructions
• For Admin SAML Login URL, enter the Identity Provider Single Sign-On URL from the Okta Application Setup Instructions
• For X.509 Certificate, enter the portion of the X.509 Certificate from the Okta Application Setup Instructions that falls between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".  IMPORTANT:  Make sure "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" are NOT included in the X.509 Certificate field
• Click the Login Settings tab
• For Login Button Text under Administrator Options section, enter the text of the hyperlink to appear on the administrator login page that admins will click to login using Okta. You may wish to change this to "Login with Okta".
• For Login Options, choose whether you wish users to be able to login with EITHER their Soapbox user credentials or their Okta credentials OR only their Okta credentials
• Click Save

Single Sign-On has now been enabled for your administrator account.

Step 5: Add users to the User Manager in Soapbox

To access the Soapbox administrator using Okta credentials, an individual must have an enabled user account in Soapbox with a username that matches their Okta email address. To create accounts in Soapbox:

• Go the User Manager
• Click New to create a user
• For First Name, enter the first name of the user
• For Last Name, enter the last name of the user
• For Username, enter the email of the user that is associated with their Okta account
• For E-mail, enter the email of the user that is associated with their Okta account
• For New Password, enter a password of your choosing. This will not be used when logging in via single sign-on, however.
• For Verify Password, re-enter the password
• For Group, under Public Back-End, select either Manager or Administrator. The primary difference between the two is that Administrators can create and edit users while Managers cannot.
• Click Save
• Repeat for each user you wish to grant access to the administrator