O NE S TREAM XF ® A ZURE AD C ONFIGURATION G UIDE U PDATED M AY 2023 OneStream XF Azure AD Configuration Guide Page 2 of 24 O NE S TREAM XF A ZURE AD OIDC C ONFIGURATION G UIDE Copyright © 2023 OneStream Software LLC. All rights reserved. While every reasonable precaution has been taken in the preparation of this document, neither the author nor the OneStream development team assumes responsibility for errors, omissions, or for damages resulting from the use of the information contained herein. However, the information contained in this document is believed to be accurate. OneStream Software, OneStream XF, Extensible Dimensionality and the OneStream logo are trademarks of OneStream Software LLC in the United States and other countries. Microsoft, Microsoft Office, Microsoft Azure, Windows, Windows Server, Excel, .NET Framework, Silverlight, Internet Explorer, Internet Information Server, Windows Communication Foundation and SQL Server are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. DevExpress is a registered trademark of Developer Express, Inc. Cisco is a registered trademark of Cisco Systems, Inc. Intel is a trademark of Intel Corporation. AMD64 is a trademark of Advanced Micro Devices, Inc. Firefox is a trademark of the Mozilla Foundation. Other names may be trademarks of their respective owners. OneStream XF Azure AD Configuration Guide Page 3 of 24 Table of Contents Microsoft Azure AD Configuration ............................................................................................................ 4 Azure AD Configuration: Adding an Application ................................................................................... 4 Web Application Setup (Required) ....................................................................................................... 4 Native Application Setup (Required) .................................................................................................... 9 Mobile Application Setup (Optional) .................................................................................................. 13 REST API Setup (Optional) ................................................................................................................... 19 Azure AD Configuration Variables for OneStream XF ......................................................................... 24 OneStream XF Azure AD Configuration Guide Page 4 of 24 Microsoft Azure AD Configuration Azure AD Configuration: Adding an Application Any application that wants to use the capabilities of Azure AD must first be registered in an Azure AD tenant. This registration process involves giving Azure AD details about the application, such as the URL where it is located, the URL to send replies after a user is authenticated, the URI that identifies the app, etc. DIRECTIONS: Please create the four application registrations as shown below (Web and Native are required, Mobile and REST API are optional.) Please use the form on the last page of this guide to store the Application IDs, URIs, and keys when asked to take note of them. When completed, please securely send the form to OneStream Cloud Services. Web Application Setup (Required) This section will describe the setup of the Azure AD application used by OneStream XF to authenticate clients accessing the Microsoft Silverlight application using a PC and Internet Explorer. NOTE: See the following pages for example screenshots of these steps. The Client ID will be different than the example shown. Also, the sitename placeholder should be updated to reflect your environment’s site name. 1.) Log on to the Azure portal. 2.) Select Azure Active Directory from the services list. 3.) In the left navigator under Manage, s elect App registrations OneStream XF Azure AD Configuration Guide Page 5 of 24 4.) Click the New registration button. a. In the Register an application window , enter the name of the application in the Name field. Note: Use a name that identifies the type of application being created, such as OneStream Web. b. Choose Accounts in this organizational directory only for the Supported account types selection c. Verify that Web is displayed in the dropdown under Redirect URI. Note : This is the default value and should automatically be what is displayed. If is it not, select it from the list. d. Enter the sign-on URL of the application in the text field to the right of the dropdown under Redirect URI. For example, https://sitename.onestreamcloud.com/onestreamweb/onestreamxf.aspx a. No spaces, or it will not allow you to create the URL b. Lower case only e. Click Register 5.) The application that was just created will now open into the Overview pane. a. Take note of the Application (client) ID value and copy this information to the last page of this form. OneStream XF Azure AD Configuration Guide Page 6 of 24 6.) Click on Authentication a. Under Redirect URI’s, click Add URI. b. Enter the URL for the Windows app of your OneStream environment in the Redirect URI field in addition to the existing entry. Note : Lower case only. Example: https://sitename.onestreamcloud.com/onestreamweb/onestreamwindowsapp.aspx c. Copy the ...windowsapp.aspx URL to the last page of this document. d. Click Save 7.) Navigate to implicit grant in the same pane a. Click the ID tokens checkbox. b. Click Save 1. Click Expose an API on the navigation bar a. Select the Set button for Application ID URI b. Copy the value of the URI and paste it to the last page of this document. c. Click Save. OneStream XF Azure AD Configuration Guide Page 7 of 24 8.) Click Add a scope and fill in the following parameters: a. Scope name: user_impersonation b. Who can consent?: Admins and users c. Admin consent display name: Access OneStream Web d. Admin consent description: Allow the application to access OneStream Web on behalf of the signed-in user. e. User consent display name: Access OneStream Web f. User consent description: Allow the application to access OneStream Web on your behalf. g. State: Enabled h. Click Add scope at the bottom to confirm. OneStream XF Azure AD Configuration Guide Page 8 of 24 9.) Navigate to Branding a. For the Home page URL, Enter the site URL of https://sitename.onestreamcloud.com/onestreamweb/onestreamxf.aspx b. Copy this information to the last page. Note : Lower case only. c. Click Save 10.) Click Certificates & secrets in the navigation bar to generate a key. a. Click New client secret and give it a Description such as OneStream Web b. Set an expiration per your internal policies. The longest possible is 24 months. c. Click the Add button. The key is generated. d. Copy the key’s Value to the Web Key section on the last page of this form. Note: The key cannot be accessed again. If you miss copying it, you must create a new one. 11.) Grant admin consent. a. Navigate to API Permissions b. Click ‘Grant admin consent for [company name.] OneStream XF Azure AD Configuration Guide Page 9 of 24 Native Application Setup (Required) This section will describe the setup of the Azure application used by OneStream XF to authenticate clients accessing the Application using the OneStream App for Windows, the Excel Add-In, and Studio. Note: See the following pages for example screenshots of these steps. The Client ID and Secret values will be different than the examples shown. 1.) Log on to the Azure portal. a. Select Azure Active Directory from the services list. b. In the left navigator under Manage, s elect App registrations 2.) Click the New registration button. a. In the Register an application window, enter a Name such as OneStream Native. b. Choose Accounts in this organizational directory only for the Supported account types selection c. Verify that Public/client (mobile & desktop) is selected in in the dropdown under Redirect URI. d. Enter https://onestreamclient in the text field to the right of the dropdown under Redirect URI. Note : Lower case only OneStream XF Azure AD Configuration Guide Page 10 of 24 e. Click Register 3.) The application will now open in the Overview pane a. Copy the Application (client) ID value to the last page of this document. 4.) Navigate to Authentication and under Advanced settings change the ‘Allow public client flows” slider to Yes. Click Save. OneStream XF Azure AD Configuration Guide Page 11 of 24 5.) Navigate to Branding a. Enter the site URl of https://onestreamclient for the Home Page URL. Note : Lower case only. b. Copy this information to the last page of this document c. Click Save 6.) Click API permissions in the left navigation bar a. Click Add a permission b. Click API’s my organization uses under Select an API c. In the Search bar, type the name of the Web registration you created, OneStream Web d. Click the name of the Web registration, OneStream Web OneStream XF Azure AD Configuration Guide Page 12 of 24 7.) On the new screen, Click the large Delegated permissions box on top a. Click the user_impersonation checkbox b. Click the Add permissions button on the bottom 8.) The newly added entry now appears in the API permissions section. 9.) Grant admin consent. a. In API Permissions, click the center bar that says ‘Grant admin consent for [company name.] OneStream XF Azure AD Configuration Guide Page 13 of 24 Mobile Application Setup (Optional) This section will describe the setup of the Microsoft Azure AD application used by OneStream XF to authenticate clients accessing the application using the HTML 5 / Mobile interface. Note: The Client ID and Secret values will be different than the examples shown. Also, the sitename placeholder should be updated to reflect your environment’s site name. 1.) Log on to the Azure portal. a. Select Azure Active Directory from the services list. b. In the left navigator under Manage, s elect App registrations 2.) Click the New registration button. a. Name : OneStream Mobile. b. Supported Account types: Accounts in this organizational directory only c. Redirect URI: Web d. Enter your mobile URL in the text field to the right of the dropdown under Redirect URI. https://sitename.onestreamcloud.com:50004/onestreammvc e. Click the Register button OneStream XF Azure AD Configuration Guide Page 14 of 24 3.) The application that was just created will now open into the Overview pane. a. Copy the Application ID value to the last page of this document. 4.) Click on Authentication on the navigation bar a. In the implicit grant section b. Click the ID tokens checkbox c. Click Save OneStream XF Azure AD Configuration Guide Page 15 of 24 5.) Click Expose an API on the navigation bar a. Select the Set button for Application ID URI (see screenshot below) b. Change this App ID URI value to your site URL of https://sitename.onestreamcloud.com:50004/onestreammvc c. Copy this information to the last page of this document. Note : This value must be entered exactly d. Click Save 6.) Click Add a scope and fill in the following parameters a. Scope name: user_impersonation b. Who can consent?: Admins and users c. Admin consent display name: Access OneStream Mobile d. Admin consent description : Allow the application to access OneStream Mobile on behalf of the signed-in user. e. User consent display name : Access OneStream Mobile f. User consent description: Allow the application to access OneStream Mobile on your behalf. g. State: Enabled h. Click Add scope at the bottom to confirm OneStream XF Azure AD Configuration Guide Page 16 of 24 7.) Navigate to Branding a. Enter the site URL of https://sitename.onestreamcloud.com:50004/onestreammvc for the Home page URL b. Copy this information to the last page. Note : This value must be entered exactly. c. Click Save OneStream XF Azure AD Configuration Guide Page 17 of 24 8.) Click Certificates & secrets in the navigation bar to generate a key a. Click New client secret b. Description : OneStream Mobile c. Expires: Set an expiration per your internal policies. The longest possible is 24 months. d. Click Add e. The key is generated. Copy the Value to the last page of this document. Note: The Key Value is only available now. If you do not copy it, you will have to generate a new one. 9.) Click API permissions in the left navigation bar a. Click Add a permission b. Click the APIs my organization uses tab c. In the Search bar, type OneStream Web (or whatever name you used for the OneStream web app you created earlier.) d. Click on OneStream Web in the results OneStream XF Azure AD Configuration Guide Page 18 of 24 10.) Click the Delegated permissions box a. Click the checkbox for user_impersonation b. Click Add permissions at the bottom c. The newly added entry now appears in the API permissions section. Creating the Mobile registration is now complete. OneStream XF Azure AD Configuration Guide Page 19 of 24 REST API Setup (Optional) This app registration is used to secure the OneStream XF REST API by providing a bearer token to be used in calls made to the API. 1.) Log on to the Azure portal. b. Select Azure Active Directory from the services list. c. In the left navigator under Manage, s elect App registrations 2.) Click New registration at the top a. Name: OneStream REST API b. Supported Account types: select the option that makes sense for your organization c. Redirect URI : Web d. Text field: Blank e. Click Register OneStream XF Azure AD Configuration Guide Page 20 of 24 3.) Click Overview on the left a. Copy the Application (client) ID field to the last page of this document 4.) Click on Authentication on the left a. Click Add a platform b. Select the Web box in the new pane c. Redirect URI : https://sitename.onestreamcloud.com/onestreamapi d. Under Implicit Grant, check both the Access tokens and the ID tokens boxes e. Click Configure at the bottom