|
Tag: Redirect target changed |
| (12 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | <translate>
| + | #REDIRECT [[Saml2-single-sign-on-integration-guide/MicrosoftAzureAD]] |
| − | = Microsoft Azure Active Directory SSO Configuration =
| |
| − | Microsoft Azure Active Directory (AD) single sign-on (SSO) enables users to sign in just one time to applications in the Microsoft Azure AD in order to access integrated applications.
| |
| − | | |
| − | With Azure AD SSO, users can sign in with one account to launch applications from the Office 365 portal, Dynamics 365, or the Azure AD MyApps access panel. Moreover, administrators can control user account management, and automatically add or remove user access to applications based on group membership. Without SSO, users have to remember passwords and sign in to each application separately.
| |
| − | | |
| − | Bright Pattern supports Azure AD SSO using the SAML (Security Assertion Markup Language) SSO method, which works for applications that authenticate using a SAML protocol like SAML 2.0 or WS-Federation.
| |
| − | | |
| − | With SAML SSO, Azure AD authenticates to the application by using the user's Azure AD account. Azure AD communicates the credentials to the application through a connection protocol. With SAML-based SSO, you can map users to specific application roles based on rules defined in your SAML claims.
| |
| − | | |
| − | This article will show you how to configure Azure AD SSO for your organization.
| |
| − | | |
| − | You will learn how to:
| |
| − | * Create an enterprise application
| |
| − | * Assign owner, users, and user groups to the application
| |
| − | * Configure the application for SAML-based SSO
| |
| − | * Configure application-specific domain and URLs
| |
| − | * Configure user attributes
| |
| − | * Get a SAML signing certificate
| |
| − | * Validate settings
| |
| − | * Add an SSO integration account in Bright Pattern
| |
| − | * Use Azure AD credentials in integration account properties
| |
| − | | |
| − | == Prerequisites ==
| |
| − | Before configuring Azure AD SSO, you will need the following:
| |
| − | * [https://www.office.com Microsoft Office 365 account]. If you are unable to log into Microsoft directly, please contact your Microsoft system administrator to review permission and access level settings.
| |
| − | * [https://azure.microsoft.com/en-us/free/ Microsoft Azure account/subscription] (free trial OK). Without this, you will have no directory and will not be able to access any data in Azure AD.
| |
| − | * [https://azure.microsoft.com/en-us/pricing/details/active-directory/ P2 Premium edition access to Azure Active Directory] (free trial OK). Without this, you will not be able to access or create enterprise applications or configure SSO.
| |
| − | * Bright Pattern Contact Center version 5.3 or later
| |
| − | | |
| − | == Configuration in Azure Portal ==
| |
| − | This procedure generally follows Microsoft’s tutorial, [https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-portal Configure SAML-based single sign-on for an application with Azure Active Directory]. For more information on SSO, see [https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/what-is-single-sign-on Microsoft Azure documentation].
| |
| − | | |
| − | === Step 1: Create a new enterprise application ===
| |
| − | # Sign in to the Microsoft Azure portal.<br /><br />
| |
| − | # Go to ''Azure Active Directory > Enterprise applications'' and click '''+ New application'''.<br /><br />[[File:ADSSO1b.png|thumb|800px|center|Create new enterprise application]]<br /><br />
| |
| − | # Under ''Add your own app'', choose '''Non-gallery application''' because this type is used for non-standard applications. The first type, “Application you’re developing,” is needed for API access and the second type, “On-premises application,” is needed for local server.<br /><br />[[File:ADSSO2b.png|thumb|800px|center|Non-gallery application]]<br /><br /> | |
| − | # In ''Add your own application'', set the display name of the application and click '''Add'''.<br /><br />[[File:ADSSO3b.png|thumb|800px|center|Application properties]]<br /><br />
| |
| − | '''Note:''' If you have not done this before, you will need to add '''Premium access''' to use this feature. Click the box that appears and follow the directions to add a free trial to Azure AD Premium P2. <br /><br />
| |
| − | '''Helpful tip:''' After activating the trial, you need to sign out and then sign in again to proceed with adding an application.<br /><br />[[File:MSSO-Add-App-Premiumb-53.png|thumb|800px|center|Activate a trial to access the feature]]<br /><br />
| |
| − | | |
| − | Then you will see the overview page for the application.<br /><br />[[File:ADSSO4.png|thumb|800px|center|Application overview]]<br /><br />
| |
| − | | |
| − | === Step 2: Add owner and users ===
| |
| − | # Adding yourself, the admin, as a user allows you to configure and edit the application. Adding other users allows others to use it as well.]<br /><br />
| |
| − | # On the overview page for the application, go to ''Manage > Owners'' and then click '''add'''.<br /><br />[[File:ADSSO5b.png|thumb|800px|center|Add owners]]<br /><br />
| |
| − | # In ''Select Owners'', add yourself as the owner of the application so that you can modify the application. Then click '''Select'''.]<br /><br />
| |
| − | # Then go to ''Manage > Users'' and groups and click '''Add user'''.<br /><br />[[File:ADSSO6b.png|thumb|800px|center|Add users]]<br /><br />
| |
| − | # Click '''Users and groups''', select the users with rights to use this application, and click '''Assign'''.<br /><br />
| |
| − | # After you add the users, you can repeat these steps to add the group, if desired.
| |
| − | | |
| − | === Step 3: Configure SSO ===
| |
| − | In the ''Single sign-on'' section, you will choose the application for which you want to configure SSO, and then select the SAML method of SSO.
| |
| − | | |
| − | # Go to ''Manage > Single sign-on'' to select a single sign-on method.<br /><br />
| |
| − | # Choose '''SAML'''.<br /><br />[[File:ADSSO7b.png|thumb|800px|center|SAML method]]<br /><br />
| |
| − | # The ''Set up SSO with SAML Preview'' page will open with the following boxes.<br /><br />[[File:MSSO8.png|thumb|800px|center|SSO configuration page]]<br /><br />
| |
| − | | |
| − | ==== Basic SAML Configuration ====
| |
| − | In ''Basic SAML Configuration'', you will name the application being configured for SSO and specify the source of the SAML token.
| |
| − | | |
| − | | |
| − | [[File:MSSO7-Basic-SAML-53.png|thumb|800px|center|Basic SAML Configuration]]
| |
| − | | |
| − | | |
| − | # Click '''Edit''' and set:
| |
| − | ## '''Identifier (Entity ID)''' - Identifies the application for which SSO is being configured. This is also known as the Entity ID. Use any unique name (e.g., “ExampleApp”). Azure AD sends the identifier to the application as the Audience parameter of the SAML token. The application is expected to validate it. This value also appears as the Entity ID in any SAML metadata provided by the application.<br /><br />
| |
| − | ## '''Reply URL''' - Specifies where the application expects to receive the SAML token. Set '''https://<tenant>.brightpattern.com/agentdesktop/sso/redirect''' and be sure to replace “<tenant>” with your contact center name.<br /><br />For example:<br /><br />'''https://example.brightpattern.com/agentdesktop/sso/redirect'''<br /><br />[[File:ADSSO9b.png|thumb|800px|center|Basic SAML Configuration Identifier and Reply URL]]<br /><br />
| |
| − | # '''Important:''' Leave the other properties (Sign-on URL, Relay State, and Logout URL) empty because they are not supported for sign-in to Agent Desktop. Setting any value for these properties will cause Azure AD SSO to fail AND will prevent login to your instance of Agent Desktop from any browser.<br /><br />[[File:ADSSO9c.png|thumb|800px|center|Leave these properties empty!]]<br /><br />
| |
| − | # Click '''Save'''.
| |
| − | | |
| − | | |
| − | ==== User Attributes & Claims ====
| |
| − | In ''User Attributes & Claims'', you will specify what information (e.g., user's name, email, etc.) Azure AD sends to the application in the SAML token when a user signs in.
| |
| − | | |
| − | # Click '''Edit''' to set attributes for the identity provider to identify your system. You will see the following list of claims and values.<br /><br />[[File:ADSSO10.PNG|thumb|800px|center|User Attributes & Claims]]<br /><br />
| |
| − | # Edit the following attributes for Just-in-time (JIT) user provisioning:<br /><br />
| |
| − | ## '''user.mail''' - Delete this from the list because it is unnecessary<br /><br />
| |
| − | ## '''user.givenname''' - Click '''Edit''' and change ''Name'' to ''FirstName''<br /><br />
| |
| − | ## '''user.userprincipalname''' - (Note there are two--choose the one with claim name that ends with “/nameidentifier”.) Leave this attribute as-is.<br /><br />
| |
| − | ## '''User.surname''' - Click '''Edit''' and change ''Name'' to ''LastName''<br /><br />
| |
| − | ## '''User.userprincipalname''' - (Note there are two--choose the one with claim name that ends with “/name”.) Click '''Edit''' and change ''Name'' to ''Email''<br /><br />
| |
| − | When done, your list should look like this:<br /><br />[[File:ADSSO11.PNG|thumb|800px|center|Edited attributes]]<br /><br />
| |
| − | | |
| − | ==== SAML Signing Certificate ====
| |
| − | In the ''SAML Signing Certificate'' section, you will create and download a SAML certificate, which Azure AD uses to sign the SAML tokens that it sends to the application.
| |
| − | | |
| − | # Click '''Edit''' and select '''New Certificate'''.<br /><br />[[File:ADSSO12b.png|thumb|800px|center|Create new certificate]]<br /><br />
| |
| − | # In the new certificate row that appears, set the desired Signing Option and Signing Algorithm, and then click '''Save'''. In this example, we selected “Sign SAML response and assertion” and “SHA-256”.<br /><br />[[File:ADSSO13b.png|thumb|800px|center|Signing Option and Signing Algorithm]]<br /><br />
| |
| − | # Click download for the Certificate (Base64). The contents of this certificate will pasted into our configuration in later steps.<br /><br />[[File:ADSSO14b|thumb|800px|center|Download Base64 certificate]]<br /><br />
| |
| − | # After it downloads, open it and '''Install Certificate'''.
| |
| − | | |
| − | ==== Set up ====
| |
| − | Next you will set up the application to use Azure AD as a SAML identity provider. This is needed for your app to connect to Azure AD.
| |
| − | | |
| − | Copy the '''Log in URL''' value and paste it into a separate text doc. When configuring your SSO integration account in later steps, you will paste this into the ''Identity Provider Single Sign-On URL'' property in your Bright Pattern SSO integration account.<br /><br />[[File:ADSSO15b|thumb|800px|center|Copy Log in URL]]<br /><br />
| |
| − | | |
| − | ==== Validate single sign-on ====
| |
| − | After configuration is done on the Azure portal, you should validate the settings to make sure that sign-in works correctly.
| |
| − | | |
| − | # Click '''Test'''.<br /><br />
| |
| − | # Click '''Sign in as current user'''. This lets you see if SSO works for you.<br /><br />[[File:ADSSO16b.png|thumb|800px|center|Validate SSO]]<br /><br />
| |
| − | # If it works, you should see the Bright Pattern Agent Desktop login page.<br /><br />[[File:MSSO-AD-Login-53.PNG|thumb|800px|center|Agent Desktop login]]<br /><br />
| |
| − | | |
| − | === Errors and How to Fix Them ===
| |
| − | ==== HTTP Error 404 ====
| |
| − | This likely means that the Reply URL is incorrect, and your tenant’s Agent Desktop cannot be found. Go back to ''Basic SAML Configuration'' and check that the Reply URL is '''https://<tenant>.brightpattern.com/agentdesktop/sso/redirect'''
| |
| − | | |
| − | | |
| − | [[File:ADSSO-Error1.png|thumb|800px|center|404, Page Not Found]]<br /><br />
| |
| − | | |
| − | | |
| − | ==== Redirects to Microsoftonline with HTTP Error 404 ====
| |
| − | This error could mean one of the following:
| |
| − | | |
| − | # In ''Basic SAML Configuration'', you tried to set a value for Relay State, which is unsupported. Go back and leave all optional URLs blank, and '''Save'''.<br /><br />
| |
| − | # This likely means that more than one Azure AD application has a Reply URL that is pointing to the same tenant. Try checking other registered applications and enterprise applications in your Active Directory. Check their Reply URLs and remove any extraneous app Reply URLs that have a callback to your tenant.
| |
| − | | |
| − | | |
| − | [[File:ADSSO-Error-Relay.PNG|thumb|800px|center|404, Page Not Found]]
| |
| − | | |
| − | | |
| − | == Configuration in Bright Pattern ==
| |
| − | Bright Pattern integrates with SAML 2.0 identity providers to allow you to configure SSO functionality for Agent Desktop and Contact Center Administrator applications. After you have configured SAML SSO for your application in Azure AD, you will need to add an SSO integration account in Bright Pattern. This integration account is what enables your contact center to work with Azure AD.
| |
| − | | |
| − | === Step 1: In Bright Pattern, add SSO integration account ===
| |
| − | In the Bright Pattern Contact Center Administrator application, go to ''Call Center Configuration > Integration Accounts'' and add a new '''Single Sign-On''' integration account. This is a general type of SSO account that Bright Pattern uses for various integrations.<br /><br />[[File: Add-SSO-Integration-53.PNG|thumb|800px|center|Add SSO integration account]]
| |
| − | | |
| − | === Step 2: Edit properties with your Azure AD app credentials ===
| |
| − | In ''Properties'', name the account (any name). The account properties are split into two sections: Agent Desktop SSO and Admin SSO.
| |
| − | | |
| − | In the Agent Desktop SSO properties, specify the following:<br /><br />[[File:ADSSO20.PNG|thumb|800px|center|Add SSO integration account]]
| |
| − | | |
| − | | |
| − | * '''Enable Single Sign-On''' - Select the checkbox to enable SSO<br /><br />
| |
| − | * '''Identity Provider Single Sign-On URL''' - The “Login URL”, which is taken from Setup in Azure AD SAML SSO configuration (e.g., “https://login.microsoftonline.com/e5251310-8bha-41ee-a27b-686060g872b5/saml2”)<br /><br />[[File:ADSSO17b.png|thumb|800px|center|Where to find Login URL]]<br /><br />
| |
| − | * '''Identity Provider Issuer''' - The “Azure AD Identifier”, which is taken from ''Setup'' in Azure AD SAML SSO configuration (e.g., https://sts.windows.net/e5251310-8bbb-41gg-a37t-686060f972b5/)<br /><br />
| |
| − | * '''Identity Provider Certificate''' - The Base 64 certificate that you downloaded from Azure AD. Copy and paste the contents between the “BEGIN” and “END” tags.<br /><br />[[File:ADSSO18.png|thumb|800px|center|Copy certificate contents]]<br /><br />
| |
| − | * '''Enable Just-in-time user provisioning''' - Select the checkbox to enable just-in-time (JIT) user provisioning. JIT user provisioning automatically creates call center users on the first SSO login attempt authorized by the identity provider. If you enable JIT, you must also use a template (see next property).<br /><br />
| |
| − | * '''Use Template''' - Select this checkbox to copy assignments (e.g., username format, email, roles, teams, skills, etc.) from a specific user with the agent role, and apply them to new call center users created by JIT user provisioning.
| |
| − | | |
| − | In Admin SSO properties, specify the same values as above, if desired. Admin SSO properties are optional. When selecting the user for Use Template, be sure to select a user with the admin role.
| |
| − | | |
| − | Lastly, click '''Apply''' to save your changes.
| |
| − | | |
| − | | |
| − | This completes Azure AD SSO configuration.
| |
| − | | |
| − | | |
| − | | |
| − | </translate>
| |
