Personalized Community is here!
Quickly customize your community to find the content you seek.
Check out the latest Business Central updates!Learn about the key capabilities and features of Dynamics 365 Business Central and experience some of the new features.
Download overview guide | Watch Business Central video
2020 Release Wave 2Discover the latest updates and new features to Dynamics 365 planned through March 2021.
Release overview guides and videos Release Plan | Preview 2020 Release Wave 2 TimelineWatch the 2020 Release Wave 2 virtual launch event
Ace your Dynamics 365 deployment with packaged services delivered by expert consultants. | Explore service offerings
Connect with the ISV success team on the latest roadmap, developer tool for AppSource certification, and ISV community engagements | ISV self-service portal
The FastTrack program is designed to help you accelerate your Dynamics 365 deployment with confidence.
FastTrack Program | Finance TechTalks | Customer Engagement TechTalks | Upcoming TechTalks
The latest version of BcContainerHelper (BcContainerHelper version 2.0.1 | Freddys blog) comes with a new concept called a BcAuthContext. A BcAuthContext is really just a hashtable with authentication information for a Business Central online tenant.
This blog post describes the concept and how to obtain and refresh a BcAuthContext. Subsequent blog posts will describe how to use them.
A BcAuthContext is created using New-BcAuthContext. New-BcAuthContext supports 4 different OAuth2 flows:
Once you create a BcAuthContext, the access token is valid for 60 minutes. The BcAuthContext contains information about the expiration timestamp AND the BcAuthContext contains enough information to get a new access token. All BcContainerHelper functions, that takes a BcAuthContext as a parameter will implicitly call Renew-BcAuthContext, which will renew the access token if the validity period is less than 10 minutes. Renewing the auth context will return immediately if the access token is still valid.
For pipelines connecting to Business Central online environments, I recommend using the devicecode flow to create an authcontext manually and then store the refresh token in a keyvault accessible from the pipeline. This refresh token must be renewed every 3 months (validity 90 days). The devicecode and refresh_token flows are both enabled on the default AAD App (ClientID = “1950a258-227b-4e31-a9cf-717495945fc2”) which is a Microsoft Azure PowerShell well known app.
You can use Set-AzKeyVaultSecret to store the refresh token in a keyvault for access from your pipeline.
The easiest way to create a BcAuthContext is by issuing this command:
$authContext = New-BcAuthContext -includeDeviceLogin
which should give an output like this:
Now you can open a browser using https://aka.ms/devicelogin or https://microsoft.com/devicelogin, enter the code DEM276827 and then login with your AAD credentials. You will see a dialog like this:
Indicating that you will be signed in using an AAD App called Microsoft Azure PowerShell. After the login you will see something like:
And if you display the content of the $authContext variable you will see something like:
By default, the devicecode flow will wait 5 minutes for the device login to complete. You can specify a different wait time using the deviceLoginTimeout parameter (default [TimeSpan]::FromMinutes(5))
With the refresh token from the devicecode flow, you can create a new BcAuthContext (in your pipeline) using:
$authContext2 = New-BcAuthContext -refreshToken $refreshToken
You have to refresh the refresh token in your keyvault for every 90 days. Note that the refresh token is invalidated if the password of the authenticated user changes.
With the password flow, you can authenticate using a AAD username and password. Storing your username and password in an app or in a keyvault is not recommended and multi factor authentication (MFA) is NOT supported, but for testing purposes (or for getting a refresh token), you can do like this:
$authContext7 = New-BcAuthContext -credential $credential
$authcontext7.RefreshToken can stored in a Keyvault and can be used subsequently to get a new accesstoken.
The client_credentials flow is currently only used for some automation APIs. Over time, all CI/CD tasks should be able to run using this flow, but today only some automation APIs can be reached with this. You need to create an AAD App as described here. https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication and specify the ClientID and ClientSecret for this app to the New-BcAuthContext:
$authcontext4 = New-BcAuthContext `
-clientID $PublisherAppClientIdSecret.SecretValueText `
Note that service 2 service doesn’t authenticate as a specific user in Business Central and therefore this flow currently cannot be used for all purposes.
Once you have a BcAuthContext, the Access Token is only valid for 60 minutes, but you can refresh the access token by running:
$authContext = ReNew-BcAuthContext -bcAuthContext $authContext
If the auth context is still valid, the function returns immediately. If not, you might see something like:
The renew function will renew the access token if the validity period is below 300 seconds. You can specify a different minimum validity period if you need to.
Beside the parameters for the various flows described above, there are few other parameters indicating which resources you are authenticating to and what authority you are using as authenticator. By default these parameters are set to authenticate towards online Business Central tenants. If you are authenticating towards docker instances or onprem instances, you would have to modify these parameters. The parameters and their default values are:
ClientID is used to specify which AAD App is used for the authentication. The default value is 1950a258-227b-4e31-a9cf-717495945fc2, which is a well known AAD App used by the Microsoft Azure PowerShell module.
Resource and Scopes is used to specify the Resource/Scopes you are authenticating to. The client_credentials flow uses Scopes, the other flows are using Resource. Both are defaulted to https://api.businesscentral.dynamics.com/ (Scopes have an added .default)
TenantID is set to Common by default, meaning that you will be authenticating your user towards all AAD tenants and can use the obtained access token to access any Business Central tenant your user has access to. You can specify the AAD tenant ID by providing the Guid or the tenant domain (69cb4a05-4ea8-412d-9f34-10fb5cf7db05 or demo.onmicrosoft.com in the examples above).
Authority is the authority used to authenticate the request. Default value is https://login.microsoftonline.com/$TenantID (where $TenantID is the value of the TenantId parameter)
Freddy KristiansenTechnical Evangelist
Business Applications communities