Windows Authentication for OData

Authentication at the API level is based on Windows authentication; either NTLM or Kerberos protocols will be used depending on the underlying Windows OS and domain configuration. The client program or process which sends the OData HTTP request must be able to respond to the authentication challenge which the server sends. Client tools such as Excel Power Query and Power BI have this capability built-in, as do web browsers and some programming language modules (including C#/.NET). If you are using an API tool, such as Postman, or a general-purpose programming language you need to ensure that code is present and enabled to handle the Windows authentication protocol.

Server (IPS) Configuration

To enable Windows authentication, an IPS Administrator needs to modify the service setting 'Enable Windows Authentication'. The setting applies to all PlanningSpace tenants and it is not possible to enable/disable at the tenant level.

This mode of authentication can only be used with SAML2-type user accounts. These accounts require an external identity provider (IdP) service to be provided to support OAuth2 authentication.

All OData requests sent to the PlanningSpace API server require authentication based on a valid user account for the PlanningSpace tenant that is being queried. A user account can only access via the OData API the same tenant data that it is allowed to access via the PlanningSpace UI (i.e., as determined by the workgroup-based and individual account permissions).

Code sample (PowerShell)

The following examples use standard PowerShell commands and library modules; no additional setup should be required.

The simplest case is to use Windows authentication with 'UseDefaultCredentials', which invokes the use of the Windows user account where you are currently logged in. The PlanningSpace tenant must have a SAML2-type user account based on that Windows account. For example:

$tenantUrl = 'https://ipsserver.mycompany.com/TENANTNAME'
Invoke-RestMethod -Uri ($tenantUrl + '/PlanningSpaceDataflow/data/v1/Currencies?$top=3') -UseDefaultCredentials

Note that although the API response will originally be in JSON format, the Invoke-RestMethod command will convert the response to a PowerShell object which can be more easily manipulated using native PowerShell operations. Alternatively you can work with the JSON-format response by appending a pipe to the end of the command:

Invoke-RestMethod -Uri ($tenantUrl + '/PlanningSpaceDataflow/data/v1/Currencies?$top=3') -UseDefaultCredentials | ConvertTo-JSON

If you want to use a different Windows account for authentication (which must already exist as a SAML2 user account in the PlanningSpace tenant), use the command 'Get-Credential' first to create a credential object:

$cred = Get-Credential

This presents a dialog box where you enter the username and password. You only need to do this once until the PowerShell is re-started, as the credential object will be stored in the current PowerShell process.

N.B. the dialog in 'Get-Credential' is not doing a Windows logon process, rather it is converting the explicit user/password strings into an encrypted credential object, which is stored in the variable '$cred'.

Then, use the 'Credential' parameter in the API request:

Invoke-RestMethod -Uri ($tenantUrl + '/PlanningSpaceDataflow/data/v1/Currencies?$top=3') -Credential $cred

Every API request needs to include a credential object, or 'UseDefaultCredentials'. Windows authentication has a high level of security because the user credentials are not transmitted inside the API request that is sent to the server.

Windows authentication in Power BI and Excel Power Query

You can use Windows authentication when you are setting up an 'OData feed' in a client data analysis tool. The following details are for the OData Feed setup in Power BI and Excel Power Query.

The only difference with the 'Basic' authentication setup, as used for API key authentication, is at the authentication dialog:

Choose the Windows option. Then:

• Click the Use my current credentials selection to connect using the Windows user account where you are currently logged in; the PlanningSpace tenant must have a SAML2-type user account based on that Windows account.
• Click the Use alternate credentials selection to connect using a different Windows account, and fill in the User name and Password in the input boxes.

For other details about setting up an OData Feed, see Using Excel Power Query as a client or Power BI Create an OData connection.