Configure Okta Single Sign-On (SSO) For Microsoft Dynamics On-Premises

How-To Guide:Configure Okta Single Sign-On(SSO) for Microsoft DynamicsOn-PremisesUse Case: Configure DynamicsOn-Premises WS-Fed claims-basedauthentication via Okta User’s Okta profile of first name, last name and loginmatch the Microsoft Dynamics On-Premises profile Microsoft Dynamics On-Premises users are notprovisioned by Okta but are managed by the MicrosoftDynamics adminDynamics (On-Premises) can be configured to useclaims-based authentication to authenticate both internal usersand to enable access for external users not using VPN.Integration OverviewClaims-based authentication relies on a trust establishedbetween a Relying Party—which can be an application likeDynamics On-Premises—and a Trusted Claims Provideror Trusted Issuer like Okta. A user authenticates to an IdentityProvider (Okta). The Identity Provider issues a claim containinginformation about the user. These claims are called “assertions.”The Relying Party (Dynamics On-Premises) will allow or denyaccess based on the information contained within the claim.Configure Okta with the appropriate MicrosoftDynamics On-Premises application URLs, NameIDformat and user attributes as well as generate themetadata file and certificate needed by MicrosoftDynamics.A key benefit of using claims-based authentication is the usernever needs to provide credentials (user name/password) to theapplication, but rather, access is based on an established trustbetween the RP and trusted claims provider and issued claim.This guide outlines how to configure Microsoft Dynamics OnPremises for SSO via Okta. By following the procedures in thisguide, you can replace your Microsoft ADFS infrastructure withOkta for claims-based authentication to Microsoft Dynamics OnPremises.Note: This guide applies to both Dynamics On-Premises andDynamics CRM 2016. CRM/Dynamics SDK integration is out ofscope for this guide.Assumptions Claims-based authentication and IFD have already beenconfigured with another security token service (i.e. ADFS)Users accessing Microsoft Dynamics On-Premises havebeen created/provisioned within OktaStep 1: Create an Okta Integration Network (OIN) appusing the WS-Fed templateStep 2: Configure Microsoft Dynamics On-Premisesfor SSO with OktaReplace ADFS with Okta as the trusted claims provider/trusted issuer.Step 3: Configure Microsoft Dynamics On-Premiseswith Okta as a trusted claims provider/trusted issuerAdd the Okta certificate to the Microsoft Dynamicsdatabase.Step 4: Configure Okta Bookmark appCreate an OIN Bookmark app in Okta that will appearas a chiclet on assigned user’s Okta organizationhomepage.Step 5: Assign WS-Fed and Okta Bookmark OIN appsAssign both the WS-Fed and Okta Bookmark OIN appsto allow users access to Microsoft DynamicsOn-Premises.1

Step 1: Create an Okta Integration Network(OIN) app using the WS-Fed template1. From the Admin app for your Okta Org, navigate toApplications Applications and click Add Applicationin the top leftIn this step of the guide, we will be configuring Oktawith the appropriate Microsoft Dynamics On-Premisesapplication URLs, NameID format and user attributes aswell as generating the metadata file and certificate neededby Microsoft Dynamics.2. In the top left search field, type WS-Fed and thenchoose Template WS-Fed by clicking Add3. Fill out the following fields, replacing the italicized textwith the information specific to your environment:FieldValueApplication Labele.g. Dynamics On-PremWeb Application URLhttps://ifd.atkoice.comNotesDiscovery Web ServiceDomain URL specified during IFD setupRealmhttps://ifd.atkoice.com/Discovery Web ServiceDomain URL specified during IFD setupNote: Trailing Forward SlashReplyTo URLhttps://ifd.atkoice.comDiscovery Web ServiceDomain URL specified during IFD setupAllow ReplyTo OverrideNot selectedNameID FormatEmailAddressAudience Restrictionhttps://ifd.atkoice.comDiscovery Web ServiceDomain URL specified during IFD setupAssertion Authentication ContextPasswordProtectedTransportGroup Attribute ValueWindowsDomainQualifiedNameGroup Attribute Name (Optional)N/ADynamics does not use groups forclaims-based accessYou can accept the entity/claims/roleGroup FilterN/AUsername Attribute StatementsNoneCustom Attribute entity/claims/upn user.loginDynamics does not use groups forclaims-based accessNote: Pipe ‘ ’ between upn anduser.loginEnsure the Okta User Login matchesthe expected login when the userwas added to CRM/Dynamics(i.e. a.user01@acmepartners.com)2

FieldValueApplication Visibility—do not displayCheckedNotesapplication icon to usersApplication Visibility—do not displayCheckedapplication icon in the Okta Mobile appProvisioningUncheckedAuto-launchUncheckedStep 2: Configure Microsoft Dynamics OnPremises for SSO with OktaIn this step of the guide, we will be replacing ADFS withOkta as the trusted claims provider/trusted issuer.Okta WS-Fed OIN app1.From the properties of your OIN app, click theSign On tabMicrosoft Dynamics—Configure claims-basedauthentication1.On the Microsoft Dynamics server, start the DeploymentManager2.In the Deployment Manager console tree, click MicrosoftDynamics, and then in the right pane, click ConfigureClaims-Based Authentication3.Review the contents of the page, and then click Next 2.Within the Settings section, right-mouse click theIdentity Provider Metadata hyperlink and chooseCopy Link Address4.On the Specify the security token service page, enterthe Okta federation metadata URL previously copied andclick Next 3.Next, click the Setup Instructions button, which willopen another tab in your browser5.4.Right-mouse click on the hyperlink labeled DownloadCertificate and save the Okta certificate locally on theDynamics Server:On the Specify the encryption certificate page, clickSelect and choose the certificate previously usedwhen configuring claims-based authentication and clickNext 6.Review the results on the System Checks page, resolveany issues (as-needed); otherwise click “Next ”a.example. C:\ToolsMicrosoft Dynamics—Remove existing internet-facingdeployment (IFD) and claims-based authenticationconfigurationsa.Note: Microsoft does not support TLS1.2 out of thebox. If you receive an error stating the metadataURL is inaccessible, perform the following steps:1.On the Microsoft Dynamics server, start the DeploymentManagerii.2.In the right pane, choose Disable Internet-FacingDeployment and from an Administrative CommandPrompt type iisresetiii. Copy the file to the CRMWeb Directory(i.e. C:\Program Files\Microsoft Dynamics CRM\CRMWeb)3.Return to the Deployment Manager, and in the right panechoose Disable Claims-Based Authentication and froman Administrative Command Prompt type iisresetiv. Use http://localhost/FederationMetadata.xml orhttps://localhost/FederationMetadata.xml; basedon your available IIS bindingsDownload the metadata file by clicking the linkon the OIN app setup pageNote: Resetting IIS after each change should help minimizethe chance of any unexpected errors when configuring SSOwith Okta3

7.On the Review your selections and then click Apply tab,click Apply and then click FinishMicrosoft Dynamics—Configure internet-facingdeployment (IFD)1.On the Microsoft Dynamics server, start the DeploymentManager2.In the Deployment Manager console tree, click MicrosoftDynamics, and then in the right pane, click ConfigureInternet-Facing Deployment3.Review the contents of the page, and then click Next 4.On the Make Microsoft Dynamics CRM available to userwho connect through the Internet page, the followingthree (3) fields should be present and contain the previousconfiguration’s URLs:a.6.On the next Make Microsoft Dynamics CRM availableto user who connect through the Internet page, thefollowing field should be present and contain the previousconfiguration’s URL:a.i.e. auth.atkoice.comii.For external access, this URL needs to bepublicly resolvable and accessiblei.e. atkoice.comOrganization Web Service Domaini.c.Once verified, click Next Web Application Service Domainii.b.5.i.e. atkoice.comDiscovery Web Serviceiii. i.e. ifd.atkoice.com4.For external access, this URL needs to bepublicly resolvable and accessible4

3.Once verified, click Next SQL Server Management Studio4.Review the results on the System Checks page, resolveany issues (as needed); otherwise click Next 1.Launch SQL Server Management Studio (SSMS)connecting to the SQL server hosting your CRM/Dynamics database2.Expand Databases MSCRM CONFIG Tables3.Right-mouse click dbo.Certificates and clickEdit Top 200 Rows4.Locate the row for the Okta certificate, and change theType to TrustedIssuera.b.9.If you receive an error regarding the Discovery WebService (e.g. “The Discovery Web Service could notbe accessed. The domain is unavailable or does notexist.”; this can be ignored)Click Next On the Review your selections and then click Apply tab,click Apply and then click FinishNote: If you add/remove organizations to your MicrosoftDynamics On-Premises deployment, simply re-run thissection of the setup guide.Step3:ConfigureMicrosoftDynamicsOn-Premises with Okta as a trusted claimsprovider/trusted issuera.Once saved, verify the CertificateData contains theplain text contained within the Okta certificateb.If not, simply copy and paste the relevant text fromthe Okta certificate downloaded in Step 2: OktaWS-Fed OIN app to the CertificateData fieldIn this step of the guide, we will be adding the Okta certificateto the Microsoft Dynamics database.Step 4: Configure Okta Bookmark appPowerShell1.Launch PowerShell as Administrator2.Type Add-PSSnapin Microsoft.Crm.PowerShell andhit Enter3.Type Set-CrmCertificate -DataFile C:\Tools\okta.cert-StoreName “My” -CertificateType “AppFabricIssuer”–StoreLocation DistinguishedName” and hit Entera.b.In this step of the guide, we will be creating an OIN Bookmarkapp in Okta that will appear as a chiclet on assigned users’Okta organization homepage, allowing users to access theappropriate Microsoft Dynamics organization.Okta Bookmark OIN app1.Update -DataFile to match the download path ofthe Okta certificateFrom the Admin app for your Okta Org, navigate to“Applications Applications and click Add Applicationin the top left2.Ensure there is a single “ at the end of thePowerShell stringIn the top left search field, type “Bookmark” and thenchoose Bookmark App by clicking Add3.Fill out the following fields, replacing the italicized textwith the information specific to your environment:i.i.e. FindBySubjectDistinguishedName5

FieldValueNotesApplication labele.g. Acme erviceUrlThe default behavior with thisintegration is the user will login usingthe Discovery Web Service URL andland on the Microsoft Dynamicsorganization they were created inNote: To access any other MicrosoftDynamics Organizations, the user cansimply type https://crmOrgname.domainName.com or create/deploybrowser bookmarksRequest IntegrationUncheckedApplication Visibility—do not displayUncheckedapplication icon to usersApplication Visibility—do not displayUncheckedapplication icon in the Okta Mobile appStep 5: Assign WS-Fed and Okta BookmarkOIN appsIn the final step of this guide, we will be assigning both theWS-Fed and Okta Bookmark OIN apps to allow usersaccess to Microsoft Dynamics On-Premises.Closing summaryYou have now successfully replaced your Microsoft ADFSinfrastructure for Microsoft Dynamics On-Premises withOkta for claims-based authentication.WS-Fed and Okta Bookmark OIN app1. From the Admin app for your Okta Org, navigate toApplications Applications and click each of thepreviously created OIN apps2. From the Assignments tab, click Assignto People or Assign to Groups, as appropriate3. No username format is needed for the BookmarkOIN app4. For the WS-Fed OIN app Assign to People, verifythe username matches the expected CRM/Dynamicsusernamea. For Assign to Groups, no username formatconfirmation is needed6

Okta for claims-based authentication to Microsoft Dynamics On-Premises. Note: This guide applies to both Dynamics On-Premises and Dynamics CRM 2016. CRM/Dynamics SDK integration is out of scope for this guide. Assumptions User's Okta profile of first name, last name and login match the Microsoft Dynamics On-Premises profile